docs/user/mail/MailComponent.dox

   1 /*
   2  * Copyright 2017 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Augustin Cavalier <waddlesplash>
   7  *              Nathan Whitehorn
   8  *
   9  * Corresponds to:
  10  *              headers/os/mail/MailComponent.h  hrev51708
  11  *              src/kits/mail/MailComponent.cpp  hrev51708
  12  */
  13
  14
  15 /*!
  16         \file MailComponent.h
  17         \ingroup mail
  18         \brief Provides the BMailComponent and BTextMailComponent classes.
  19 */
  20
  21
  22 /*!
  23         \enum component_type
  24         \ingroup mail
  25
  26         Possible component types
  27
  28         \since Haiku R1
  29 */
  30
  31
  32 /*!
  33         \var component_type B_MAIL_PLAIN_TEXT_BODY
  34
  35         The plain text body of a message.
  36
  37         \since Haiku R1
  38 */
  39
  40
  41 /*!
  42         \var component_type B_MAIL_SIMPLE_ATTACHMENT
  43
  44         Any other kind of multipart component.
  45
  46         \since Haiku R1
  47 */
  48
  49
  50 /*!
  51         \var component_type B_MAIL_ATTRIBUTED_ATTACHMENT
  52
  53         An attachment that contains BeOS attributes.
  54
  55         \since Haiku R1
  56 */
  57
  58
  59 /*!
  60         \var component_type B_MAIL_MULTIPART_CONTAINER
  61
  62         A multipart container attachment.
  63
  64         \since Haiku R1
  65 */
  66
  67
  68 /*!
  69         \class BMailComponent
  70         \ingroup mail
  71         \brief The base class for most of the Mail Kit.
  72
  73         Note that BMailComponent is not abstract, and is useful
  74         by itself. A BMailComponent has the important quality of
  75         being able to read the headers of a message or component without
  76         instantiating whatever massive quantity of data might lie therein.
  77         This is useful primarily to determine the kind of data you are dealing
  78         with, so that the user can make a decision as to whether it should be shown.
  79
  80         \since Haiku R1
  81 */
  82
  83
  84 /*!
  85         \fn BMailComponent::BMailComponent(uint32 defaultCharSet = B_MAIL_NULL_CONVERSION)
  86         \brief Initializes a new BMailComponent with the specified character set.
  87
  88         \since Haiku R1
  89 */
  90
  91
  92 /*!
  93         \fn BMailComponent::~BMailComponent()
  94         \brief Destructor.
  95 */
  96
  97
  98 /*!
  99         \fn uint32 BMailComponent::ComponentType()
 100         \brief Returns the \c component_type of this object.
 101
 102         \since Haiku R1
 103 */
 104
 105
 106 /*!
 107         \fn BMailComponent* BMailComponent::WhatIsThis()
 108         \brief Employs simple heuristics such as the MIME type to present you with
 109                 an instance of a useful subclass.
 110
 111         You can then use any of BMailComponent's hook functions or RTTI calls to
 112         get more information. Bear in mind that the returned component is not set
 113         to any data. You must still Instantiate() it from whatever data this object
 114         was instantiated from.
 115
 116         \since Haiku R1
 117 */
 118
 119
 120 /*!
 121         \fn bool BMailComponent::IsAttachment()
 122         \brief Employs simple heuristics such as the MIME type and the Content-Disposition: header
 123                 to determine whether this component is an attachment.
 124
 125         \returns true if it is an attachment, false if not.
 126
 127         \since Haiku R1
 128 */
 129
 130
 131 /*!
 132         \fn void BMailComponent::SetHeaderField(const char *key, const char *value,
 133                 uint32 charset = B_MAIL_NULL_CONVERSION, mail_encoding encoding = null_encoding,
 134                 bool replace_existing = true)
 135         \brief Adds the specified header of type \a key and with the \a value
 136                 to the component.
 137
 138         Converts any 8 bit-data in \a value to
 139         \a charset and encodes it into 7-bit data using \a encoding. If
 140         \a replace_existing is true, replaces any existing header of this type with
 141         this one, otherwise     adds a second one.
 142
 143         Thus, to set the header To: of some BMailComponent \a component to
 144         foo@example.com, we would do this:
 145
 146 \code
 147 component->SetHeaderField("To","foo@example.com");
 148 \endcode
 149
 150         If you want to delete a header, pass in a zero length or NULL string
 151         for the value field, or use \ref BMailComponent::RemoveHeader.
 152
 153         \since Haiku R1
 154 */
 155
 156 /*!
 157         \fn void BMailComponent::SetHeaderField(const char *key,
 158                 BMessage *structured_header, bool replace_existing = true)
 159         \brief Adds a structured header of type \a key to the component.
 160
 161         Structured headers are in the format unlabeled; key=value; key=value. The most common
 162         instance of this is the Content-Type header, where the MIME type is
 163         unlabeled, and various other information, such as character set, is
 164         specified in the key/value pairs. The format for structured_header is
 165         relatively simple: simply use BMessage::AddString(key,value) for each
 166         key/value pair. The only exception to this rule is the unlabeled data.
 167         For this, simply use the key unlabeled. Please note that the charset and
 168         encoding arguments defined for the text version of SetHeaderField is not
 169         provided here because structured headers cannot be encoded.
 170
 171         Thus, a relatively standard Content-Type header would be specified as
 172         follows:
 173
 174 \code
 175 BMessage structured;
 176 structured.AddString("unlabeled","text/plain");
 177 structured.AddString("charset","iso-8859-1");
 178 component->SetHeaderField("To",&structured);
 179 \endcode
 180
 181         \since Haiku R1
 182 */
 183
 184
 185 /*!
 186         \fn const char* BMailComponent::HeaderAt(int32 index) const
 187         \brief Returns the key of the \c header at index.
 188
 189         Useful for iterating through all the headers. If index is out of range,
 190         HeaderAt() returns NULL.
 191
 192         \since Haiku R1
 193 */
 194
 195
 196 /*!
 197         \fn const char* BMailComponent::HeaderField(const char *key, int32 index = 0) const
 198         \brief Returns the header \a key.
 199
 200         If there is more than one header key, use \a index to iterate through them.
 201         In the event that the specified header does not exist, HeaderField()
 202         returns \c NULL. Thus, to retrieve the contents of the <code>Subject:</code>
 203         field, you would do this:
 204
 205 \code
 206 const char *subject = component->HeaderField("Subject");
 207 \endcode
 208
 209         \since Haiku R1
 210 */
 211
 212
 213 /*!
 214         \fn status_t BMailComponent::HeaderField(const char *key,
 215                 BMessage *structured_header, int32 index = 0) const
 216         \brief Returns the header \a key.
 217
 218         Decodes whatever
 219         structured header may exist in \a key and places it in \a structured_header
 220         according to the format laid out in SetHeaderField(). Returns
 221         \c B_NAME_NOT_FOUND if the header key does not exist. If it does exist,
 222         but is not structured, no error is returned; the entire contents of the
 223         header are placed in <code>unlabeled</code>.
 224
 225         \since Haiku R1
 226 */
 227
 228
 229 /*!
 230         \fn status_t BMailComponent::RemoveHeader(const char *key) const
 231         \brief Removes all headers with the key \a key.
 232
 233         \since Haiku R1
 234 */
 235
 236
 237 /*!
 238         \fn virtual status_t BMailComponent::GetDecodedData(BPositionIO *data)
 239         \brief Retrieves the data contained in this component in canonical format
 240                 and places it into \a data.
 241
 242         The various attachments subclasses implement this function to return
 243         decoded data, and BTextMailComponent returns UTF8 text. \c BMailComponent
 244         implements this function to do nothing and return \c B_OK.
 245
 246         \since Haiku R1
 247 */
 248
 249
 250 /*!
 251         \fn virtual status_t BMailComponent::SetDecodedData(BPositionIO *data)
 252         \brief Sets the content of this component to the canonical format data
 253                 contained in data.
 254
 255         Thus, an attachment subclass would accept a file here and encode it into
 256         the specified encoding. BMailComponent implements this function to do
 257         nothing and return \c B_OK.
 258
 259         \since Haiku R1
 260 */
 261
 262
 263 /*!
 264         \fn virtual status_t BMailComponent::SetToRFC822(BPositionIO *data,
 265                         size_t length, bool parse_now = false)
 266         \brief Sets this object from a component in RFC-822 format.
 267
 268         \since Haiku R1
 269 */
 270
 271
 272 /*!
 273         \fn virtual status_t BMailComponent::RenderToRFC822(BPositionIO *data)
 274         \brief Renders the component into RFC-822 format.
 275
 276         It places the result in data, starting at data->Position().
 277
 278         \since Haiku R1
 279 */
 280
 281
 282 /*!
 283         \fn virtual status_t BMailComponent::MIMEType(BMimeType *mime)
 284         \brief Places the MIME type of the data into mime.
 285
 286         \since Haiku R1
 287 */