MIMEMultipartContainer

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

MIMEMultipartContainer uses the RFC 2046 multipart specification to allow you to place multiple components in a single message. Mostly useful for attachments and things.

Constructor and Destructor

MIMEMultipartContainer( const char *boundary = NULL, const char *this_is_an_MIME_message_text = NULL )

Initializes the MIMEMultipartContainer. Sets the boundary between parts to boundary. Note that boundary can be an arbitrary text string but must contain only US-ASCII characters and be unique to this particular MIMEMultipartContainer. It does not have to be globally unique, however. boundary must be specified, either here or through SetBoundary(). Also, sets the warning text about "This is an MIME message..." to this_is_an_MIME_message_text, which need not be specified at all.

virtual ~MIMEMultipartContainer()

Destroys the MIMEMultipartContainer. Note that this deletes all components which may have been added to this object. The ownership of all components is assumed by MIMEMultipartContainer when they are added.

Member Functions

virtual status_t GetDecodedData(BPositionIO *data)

Returns an error. MIMEMultipartComponents don't have data of their own..

Return Value:

- B_BAD_TYPE This operation is guranteed to fail.

virtual status_t SetDecodedData(BPositionIO *data)

Returns an error. MIMEMultipartComponents don't have data of their own..

Return Value:

- B_BAD_TYPE This operation is guranteed to fail.

virtual status_t Instantiate(BPositionIO *data, size_t length)

Does what you would expect. Creates a list of components from data. Note that you cannot delete data, as we cache it for later. This is because, as a memory and CPU saving measure, we do not actually instantiate these components until asked to. Thus instantiating an MIMEMultipartContainer is not a processor or memory-intensive operation.

Return Value:

- B_OK if everything succeeds.

- B_BAD_TYPE if data is not an MIME multipart component

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.

void SetBoundary( const char *boundary )

Sets the boundary between parts to boundary. Note that boundary can be an arbitrary text string but must contain only US-ASCII characters and be unique to this particular MIMEMultipartContainer. It does not have to be globally unique, however.

void SetThisIsAnMIMEMessageText( const char *text )

Sets the warning text about "This is an MIME message..." to text, which need not be specified at all. We reccomend that it only be set in the top-most MIMEMultipartContainer of the message.

void AddComponent( MailComponent *component )

Adds component to this MIMEMultipartContainer. Note that the MIMEMultipartContainer assumes ownership of component. Thus, you may not delete component. If you continue to modify to it after calling AddComponent(), your changes will be reflected when you call Render().

MailComponent * GetComponent( int32 index )

Returns the component at index. Instantiate()s it if it has not yet been instantiated. Otherwise, returns already instantiated component. Use RTTI or MailComponent hooks to do useful things with the returned component.

 

int32 CountComponents() const

Returns the total number of components in this MIMEMultipartContainer.

 

status_t ManualGetComponent( MailComponent * component, int32 index )

Attempts to Instantiate() component from the component at index. Note that this will fail either if component->Instantiate() fails or if the component at index either does not exist or exists only as a MailComponent and not as a raw buffer. In other words, this function will succeed if and only if the component at index exists, was part of the message when this MIMEMultipartContainer was instantiated and has not been written over since then, and component->Instantiate() succeeds on this buffer. component must be a valid MailComponent.

Return Value:

- B_OK if everything succeeds.

- B_BAD_INDEX if index is out of range

- B_NAME_IN_USE if the component at index does not exist in raw buffer form

- Something else if component->Instantiate() fails.

status_t RemoveComponent( int32 index )

Removes the component at index from the container and frees all memory associated with it (i.e. we delete it).

Return Value:

- B_OK if everything succeeds.

- B_BAD_INDEX if index is out of range