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 147component->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 175BMessage structured; 176structured.AddString("unlabeled","text/plain"); 177structured.AddString("charset","iso-8859-1"); 178component->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 206const 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*/ 288