MailComponent

Derived from: none
Declared in:  include/public/MailComponent.h
Library: libmail.so

MailComponent is the base class for the vast majority of the public Mail Kit. It is, however, important to remember that MailComponent is not abstract, and is useful by itself. A MailComponent has the important quality of being able to read the headers of a message or component without instantiating whatever massive quantity of data might lie therein. This is useful primarily to determine the kind of data you are dealing with, so that the user can make a decision as to whether it should be shown.

Constructor and Destructor

MailComponent()

Initializes the MailComponent and does nothing else.

 

virtual ~MailComponent()

Destroys the MailComponent. Does nothing of interest.

Hook Functions

virtual status_t GetDecodedData(BPositionIO *data)

Retrieves the data contained in this component in canonical format and places this data in data. The various attachments subclasses implement this function to return decoded data, and PlainTextBodyComponent returns UTF8 text. MailComponent implements this function to do nothing and return B_OK.

Return Value:

- B_OK if everything succeeds.

- Something else in the event of failure.

virtual status_t SetDecodedData(BPositionIO *data)

Sets the content of this component to the canonical format data contained in data. Thus, an attachment subclass would accept a file here and encode it into the specified encoding. MailComponent implements this function to do nothing and return B_OK.

Return Value:

- B_OK if everything succeeds.

- Something else in the event of failure.

virtual status_t Instantiate(BPositionIO *data, size_t length)

Initializes this component to the RFC 822 format data in data, starting at data ->Position(), for up to length bytes. Note that if you implement this function, your subclass may have taken up some of your data. As such, cache the position of data before calling your parent's version of Instantiate(), and then subtract the difference between the new position and your cached value, like this:

off_t cache = data->Position();
MailComponent::Instantiate(data,length);
length -= (data->Position() - cache);

Return Value:

- B_OK if everything succeeds.

- B_BAD_TYPE if we cannot handle data.

- Something else in the event of another kind of failure.

virtual status_t Render(BPositionIO *data)

Renders the component into RFC 822 format and places the result in data, starting at data ->Position().

Return Value:

- B_OK if everything succeeds.

- Something else in the event of failure.

virtual status_t MIMEType(BMimeType *mime)

Places the MIME type of the data into mime.

Return Value:

- B_OK if everything succeeds.

- Something else in the event of failure.

Member Functions

MailComponent* WhatIsThis()

Employs simple heuristics such as the MIME type to present you with an instance of a useful subclass of MailComponent. You can then use any of MailComponent's hook functions or RTTI calls to get more information. Bear in mind that the returned component is not set to any data. You must still Instantiate() it from whatever data this object was instantiated from.

bool IsAttachment()

Employs simple heuristics such as the MIME type and the Content-Disposition: header to determine whether this component is an attachment. Returns true if it is an attachment, false if not.

void SetHeaderField( const char *key, const char *value, uint32 charset = B_ISO1_CONVERSION, mail_encoding encoding = quoted_printable, bool replace_existing= true ) void SetHeaderField( const char *key, BMessage *structured_header, bool replace_existing= true )

Adds the specificed header of type key and with the UTF8 contents value to the component. SetHeaderField() converts any 8 bit data in value to charset (see the Support Kit on UTF8 for more information on this), and encodes it into 7 bit data using encoding. If replace_existing is true, replaces any existing header of this type with this one, otherwise adds a second one.

Thus, to set the header To: of some MailComponent component to foo@bar.com, we would do this:

component->SetHeaderField("To","foo@bar.com");

The version of the function that takes a BMessage sets a structured header. These are in the format unlabeled; key=value; key=value. The most common instance of this is the Content-Type header, where the MIME type is unlabeled, and various other information, such as character set, is specified in the key/value pairs. The format for structured_header is relatively simple: simply use BMessage::AddString(key,value) for each key/value pair. The only exception to this rule is the unlabeled data. For this, simply use the key unlabeled. Please note that the charset and encoding arguments defined for the text version of SetHeaderField is not provided here because structured headers cannot be encoded.

Thus, a relatively standard Content-Type header would be specified as follows:

BMessage structured;
structured.AddString("unlabeled","text/plain");
structured.AddString("charset","iso-8859-1");
component->SetHeaderField("To",&structured);

const char * HeaderField(const char *key, int32 index = 0) status_t HeaderField( const char *key, BMessage *structured_header, int32 index = 0 )

Returns the header key. If there is more than one header key, use index to iterate through them. In the event that the specified header does not exist, HeaderField() returns NULL. Thus, to retrieve the contents of the Subject: field in UTF8 format, you would do this:

const char *subject = component->HeaderField("Subject");

The version of this function that takes a BMessage decodes whatever structured header may exist in key and places it in structured_header according to the format laid out in SetHeaderField(). Returns B_NAME_NOT_FOUND if the header key does not exist. If it does exist, but is not structured, no error is returned; the entire contents of the header are placed in unlabeled.

 

const char * HeaderAt( int32 index)

Returns the key of the header at index. Useful for iterating through all the headers. If index is out of range, HeaderAt() returns NULL.

 

const char * RemoveHeader( const char *key)

Removes all headers with the key key.