Public Member Functions | List of all members
BMailComponent Class Reference

The base class for most of the Mail Kit. More...

Inherited by BMailAttachment, BMailContainer, and BTextMailComponent.

Public Member Functions

 BMailComponent (uint32 defaultCharSet=B_MAIL_NULL_CONVERSION)
 Initializes a new BMailComponent with the specified character set. More...
 
virtual ~BMailComponent ()
 Destructor.
 
uint32 ComponentType ()
 Returns the component_type of this object. More...
 
virtual status_t GetDecodedData (BPositionIO *data)
 Retrieves the data contained in this component in canonical format and places it into data. More...
 
const char * HeaderAt (int32 index) const
 Returns the key of the header at index. More...
 
const char * HeaderField (const char *key, int32 index=0) const
 Returns the header key. More...
 
status_t HeaderField (const char *key, BMessage *structured_header, int32 index=0) const
 Returns the header key. More...
 
bool IsAttachment ()
 Employs simple heuristics such as the MIME type and the Content-Disposition: header to determine whether this component is an attachment. More...
 
virtual status_t MIMEType (BMimeType *mime)
 Places the MIME type of the data into mime. More...
 
status_t RemoveHeader (const char *key)
 Removes all headers with the key key. More...
 
virtual status_t RenderToRFC822 (BPositionIO *render_to)
 Renders the component into RFC-822 format. More...
 
virtual status_t SetDecodedData (BPositionIO *data)
 Sets the content of this component to the canonical format data contained in data. More...
 
void SetHeaderField (const char *key, const char *value, uint32 charset=B_MAIL_NULL_CONVERSION, mail_encoding encoding=null_encoding, bool replace_existing=true)
 Adds the specified header of type key and with the value to the component. More...
 
void SetHeaderField (const char *key, BMessage *structured_header, bool replace_existing=true)
 Adds a structured header of type key to the component. More...
 
virtual status_t SetToRFC822 (BPositionIO *data, size_t length, bool parse_now=false)
 Sets this object from a component in RFC-822 format. More...
 
BMailComponentWhatIsThis ()
 Employs simple heuristics such as the MIME type to present you with an instance of a useful subclass. More...
 

Detailed Description

The base class for most of the Mail Kit.

Note that BMailComponent is not abstract, and is useful by itself. A BMailComponent 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.

Since
Haiku R1

Constructor & Destructor Documentation

◆ BMailComponent()

BMailComponent::BMailComponent ( uint32  defaultCharSet = B_MAIL_NULL_CONVERSION)

Initializes a new BMailComponent with the specified character set.

Since
Haiku R1

Member Function Documentation

◆ ComponentType()

uint32 BMailComponent::ComponentType ( )

Returns the component_type of this object.

Since
Haiku R1

◆ GetDecodedData()

status_t BMailComponent::GetDecodedData ( BPositionIO data)
virtual

Retrieves the data contained in this component in canonical format and places it into data.

The various attachments subclasses implement this function to return decoded data, and BTextMailComponent returns UTF8 text. BMailComponent implements this function to do nothing and return B_OK.

Since
Haiku R1

Reimplemented in BTextMailComponent.

◆ HeaderAt()

const char * BMailComponent::HeaderAt ( int32  index) const

Returns the key of the header at index.

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

Since
Haiku R1

◆ HeaderField() [1/2]

const char * BMailComponent::HeaderField ( const char *  key,
int32  index = 0 
) const

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, you would do this:

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

◆ HeaderField() [2/2]

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

Returns the header key.

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.

Since
Haiku R1

◆ IsAttachment()

bool BMailComponent::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.
Since
Haiku R1

◆ MIMEType()

status_t BMailComponent::MIMEType ( BMimeType mime)
virtual

Places the MIME type of the data into mime.

Since
Haiku R1

◆ RemoveHeader()

status_t BMailComponent::RemoveHeader ( const char *  key)

Removes all headers with the key key.

Since
Haiku R1

◆ RenderToRFC822()

status_t BMailComponent::RenderToRFC822 ( BPositionIO data)
virtual

Renders the component into RFC-822 format.

It places the result in data, starting at data->Position().

Since
Haiku R1

Reimplemented in BTextMailComponent.

◆ SetDecodedData()

status_t BMailComponent::SetDecodedData ( BPositionIO data)
virtual

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. BMailComponent implements this function to do nothing and return B_OK.

Since
Haiku R1

Reimplemented in BTextMailComponent.

◆ SetHeaderField() [1/2]

void BMailComponent::SetHeaderField ( const char *  key,
const char *  value,
uint32  charset = B_MAIL_NULL_CONVERSION,
mail_encoding  encoding = null_encoding,
bool  replace_existing = true 
)

Adds the specified header of type key and with the value to the component.

Converts any 8 bit-data in value to charset 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 BMailComponent component to foo@e.nosp@m.xamp.nosp@m.le.co.nosp@m.m, we would do this:

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

If you want to delete a header, pass in a zero length or NULL string for the value field, or use BMailComponent::RemoveHeader.

Since
Haiku R1

◆ SetHeaderField() [2/2]

void BMailComponent::SetHeaderField ( const char *  key,
BMessage structured_header,
bool  replace_existing = true 
)

Adds a structured header of type key to the component.

Structured headers 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);
Since
Haiku R1

◆ SetToRFC822()

status_t BMailComponent::SetToRFC822 ( BPositionIO data,
size_t  length,
bool  parse_now = false 
)
virtual

Sets this object from a component in RFC-822 format.

Since
Haiku R1

Reimplemented in BTextMailComponent.

◆ WhatIsThis()

BMailComponent * BMailComponent::WhatIsThis ( )

Employs simple heuristics such as the MIME type to present you with an instance of a useful subclass.

You can then use any of BMailComponent'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.

Since
Haiku R1