Hunny Software Home || Hunny MIME++ Home || Hunny Mail++ Home

BodyStructureData Class Reference

Detailed Description

BodyStructureData is a class that contains the data of an IMAP4 BODYSTRUCTURE structure.

An IMAP4 FETCH response may optionally contain a BODY or BODYSTRUCTURE data item, which supplies information about the structure of a message stored on the server. BODYSTRUCTURE has the same fields as BODY, but adds additional fields. Since BODYSTRUCTURE provides more information than BODY, this library uses one class, BodyStructureData, for both IMAP4 structures. In the case of a BODY structure, some fields of the BodyStructureData object are empty.

The BODYSTRUCTURE structure is key to the effective use of IMAP4. One of the significant advantages of IMAP4 over POP3 is the ability to retrieve only the memo text part of a message, without retrieving any of the (possibly large) attachments. This ability requires the correct interpretation of the information provided in a BODYSTRUCTURE structure.

The contents of a BODYSTRUCTURE structure depend on the MIME media type of the message. In compound types, such as multipart or message/rfc822 types, there may be several BODYSTRUCTURE structures that are nested. The following table shows which fields are allowed in the BODYSTRUCTURE depending on the media type:

                                       message/
                             text       rfc822    multipart   default
 --------------------------------------------------------------------
 media-type                 "TEXT"    "MESSAGE"  "MULTIPART"     *
 media-subtype                *       "RFC822"        *          *
 content-type-params          *           *           *          *
 content-id                   *           *                      *
 content-description          *           *                      *
 content-transfer-encoding    *           *                      *
 content-length               *           *                      *
 content-md5                  *           *                      *
 content-disposition          *           *           *          *
 body-parts                              (1)          *           
 envelope                                 *                       
 number-of-lines              *           *                       
 --------------------------------------------------------------------
 (1) A MESSAGE/RFC822 entity contains a single BODYSTRUCTURE structure,
     which provides information about the encapsulated message.

Note that since certain header fields may be absent from a message, it is possible that some information will be unavailable. Unavailable information will be absent from the BODYSTRUCTURE data returned by the server.

To get the BODYSTRUCTURE information from the IMAP4 server, first send a FETCH command with a BODY or BODYSTRUCTURE data item. Use the function Imap4Client::Fetch to send this command. Then iterate over the returned responses to find the related FETCH response, represented by an instance of FetchResponse. Use the FetchResponse::BodyStructure member function to get the contained instance of BodyStructureData. Finally, extract the information from the BodyStructureData object.

Public Member Functions

BodyStructureData ()

Default constructor.

BodyStructureData (const BodyStructureData &other)

Copy constructor.

virtual ~BodyStructureData ()

Destructor.

BodyStructureData & operator= (const BodyStructureData &other)

Assignment operator.

const char * MediaType () const

Gets the media type.

const char * MediaSubtype () const

Gets the media subtype.

unsigned NumContentTypeParams () const

Gets the number of parameters in the Content-Type header.

const char * ContentTypeParamName (unsigned index) const

Gets the name of the parameter at the specified position in the Content-Type header field.

const char * ContentTypeParamValue (unsigned index) const

Gets the value of the parameter at the specified position in the Content-Type header field.

const EnvelopeData * Envelope () const

Gets the ENVELOPE structure.

int NumBodyParts () const

Gets the number of nested BODYSTRUCTURE items.

const BodyStructureData * BodyPart (unsigned index) const

Gets the BODYSTRUCTURE item at the specified position.

const char * ContentId () const

Gets the value of the Content-ID header field.

const char * ContentDescription () const

Gets the value of the Content-Description header field.

const char * ContentTransferEncoding () const

Gets the value of the Content-Transfer-Encoding header field.

const char * ContentDisposition () const

Gets the value of the Content-Disposition header field.

unsigned NumContentDispositionParams () const

Gets the number of parameters in the Content-Disposition header field.

const char * ContentDispositionParamName (unsigned index) const

Gets the name of the parameter at the specified position in the Content-Disposition header field.

const char * ContentDispositionParamValue (unsigned index) const

Gets the value of the parameter at the specified position in the Content-Disposition header field.

const char * ContentMd5 () const

Gets the value of the Content-MD5 header field.

unsigned Size () const

Gets the body size in bytes.

unsigned NumLines () const

Gets the number of lines in message or text body part.

void ImportData (const ListItem *root)

Called by the parser to set the data for this object.

Constructor & Destructor Documentation

BodyStructureData ( )

Default constructor.

BodyStructureData ( const BodyStructureData & other )

Copy constructor.

Parameters:

other other object to copy

~BodyStructureData ( ) [virtual]

Destructor.

Member Function Documentation

const BodyStructureData * BodyPart ( unsigned index ) const

Gets the BODYSTRUCTURE item at the specified position.
If the media type is multipart, the BODYSTRUCTURE structure should contain one or more nested BODYSTRUCTURE items. This function returns the nested BODYSTRUCTURE item at position index. The parameter index must satisfy index < NumBodyParts().

Parameters:

index position of the nested BODYSTRUCTURE item to get

Returns:
BODYSTRUCTURE item at the specified position

const char * ContentDescription ( ) const

Gets the value of the Content-Description header field.
If there is no Content-Description header field, the function returns an empty string.

Returns:
content-description if present; otherwise, empty string

const char * ContentDisposition ( ) const

Gets the value of the Content-Disposition header field (without the parameters).
If there is no Content-Disposition header field, the function returns an empty string.

Returns:
content-disposition if present; otherwise, empty string

const char * ContentDispositionParamName ( unsigned index ) const

Gets the name of the parameter at the specified position in the Content-Disposition header field.
The parameter index must satisfy index < NumContentDispositionParams().

Parameters:

index position of the parameter

Returns:
parameter name

See also:
ContentDispositionParamValue

const char * ContentDispositionParamValue ( unsigned index ) const

Gets the value of the parameter at the specified position in the Content-Disposition header field.
The parameter index must satisfy index < NumContentDispositionParams().

Parameters:

index position of the parameter

Returns:
parameter value

See also:
ContentDispositionParamName

const char * ContentId ( ) const

Gets the value of the Content-ID header field.
If there is no Content-ID header field, the function returns an empty string.

Returns:
content-id if present; otherwise, empty string

const char * ContentMd5 ( ) const

Gets the value of the Content-MD5 header field.
If there is no Content-MD5 header field, the function returns an empty string.

Returns:
content-md5 if present; otherwise, empty string

const char * ContentTransferEncoding ( ) const

Gets the value of the Content-Transfer-Encoding header field.
If there is no Content-Transfer-Encoding header field, the function returns an empty string.

Returns:
content-transfer-encoding, if present; otherwise, empty string

const char * ContentTypeParamName ( unsigned index ) const

Gets the name of the parameter at the specified position in the Content-Type header field.
The parameter index must satisfy index < NumContentTypeParams().

Parameters:

index position of the parameter

Returns:
parameter name

See also:
ContentTypeParamValue

const char * ContentTypeParamValue ( unsigned index ) const

Gets the value of the parameter at the specified position in the Content-Type header field.
The parameter index must satisfy index < NumContentTypeParams().

Parameters:

index position of the parameter

Returns:
parameter value

See also:
ContentTypeParamName

const EnvelopeData * Envelope ( ) const

Gets the ENVELOPE structure.
This item is present only if the media type is "MESSAGE/RFC822", and it describes the header fields of the encapsulated message.

Returns:
ENVELOPE structure if present; otherwise NULL

See also:
EnvelopeData

void ImportData ( const ListItem * root )

Called by the parser to set the data for this object.
Only the parser should call this function.

Parameters:

root root item of parse tree

const char * MediaSubtype ( ) const

Gets the media subtype.
Content in the MIME standard is labeled with a media type, such as "text/plain" or "image/jpeg". The media type consists of a primary media type, such as "text" or "image", and a subtype, such as "plain" or "jpeg". This function returns the media subtype of the referenced content.

Returns:
media subtype

const char * MediaType ( ) const

Gets the primary media type.
Content in the MIME standard is labeled with a media type, such as "text/plain" or "image/jpeg". The media type consists of a primary media type, such as "text" or "image", and a subtype, such as "plain" or "jpeg". This function returns the primary media type of the referenced content.

Returns:
primary media type

int NumBodyParts ( ) const

Gets the number of nested BODYSTRUCTURE items.
The value is nonzero only if the media type is MULTIPART or MESSAGE/RFC822.
Use the BodyPart() member function to get the BODYSTRUCTURE structure for a specified body part.

Returns:
number of body parts

unsigned NumContentDispositionParams ( ) const

Gets the number of parameters in the Content-Disposition header field.
Use the member function ContentDispositionParamName to get the name of a parameter, and use the member function ContentDispositionParamValue to get the value of a parameter.

Returns:
number of parameters in the Content-Disposition header

unsigned NumContentTypeParams ( ) const

Gets the number of parameters in the Content-Type header.
Use the member function ContentTypeParamName to get the name of a parameter, and use the member function ContentTypeParamValue to get the value of a parameter.

Returns:
number of parameters in the Content-Type header

unsigned NumLines ( ) const

Gets the number of lines in message or text body part.

Returns:
number of lines in message or text body part

BodyStructureData & operator= ( const BodyStructureData & other )

Assignment operator.

Parameters:

other other object to copy

Returns:
*this

unsigned Size ( ) const

Gets the size of the body in bytes.

Returns:
size of the body in bytes


Public Member Functions
	BodyStructureData ()
	Default constructor.
	BodyStructureData (const BodyStructureData &other)
	Copy constructor.
virtual	~BodyStructureData ()
	Destructor.
BodyStructureData &	operator= (const BodyStructureData &other)
	Assignment operator.
const char *	MediaType () const
	Gets the media type.
const char *	MediaSubtype () const
	Gets the media subtype.
unsigned	NumContentTypeParams () const
	Gets the number of parameters in the Content-Type header.
const char *	ContentTypeParamName (unsigned index) const
	Gets the name of the parameter at the specified position in the Content-Type header field.
const char *	ContentTypeParamValue (unsigned index) const
	Gets the value of the parameter at the specified position in the Content-Type header field.
const EnvelopeData *	Envelope () const
	Gets the ENVELOPE structure.
int	NumBodyParts () const
	Gets the number of nested BODYSTRUCTURE items.
const BodyStructureData *	BodyPart (unsigned index) const
	Gets the BODYSTRUCTURE item at the specified position.
const char *	ContentId () const
	Gets the value of the Content-ID header field.
const char *	ContentDescription () const
	Gets the value of the Content-Description header field.
const char *	ContentTransferEncoding () const
	Gets the value of the Content-Transfer-Encoding header field.
const char *	ContentDisposition () const
	Gets the value of the Content-Disposition header field.
unsigned	NumContentDispositionParams () const
	Gets the number of parameters in the Content-Disposition header field.
const char *	ContentDispositionParamName (unsigned index) const
	Gets the name of the parameter at the specified position in the Content-Disposition header field.
const char *	ContentDispositionParamValue (unsigned index) const
	Gets the value of the parameter at the specified position in the Content-Disposition header field.
const char *	ContentMd5 () const
	Gets the value of the Content-MD5 header field.
unsigned	Size () const
	Gets the body size in bytes.
unsigned	NumLines () const
	Gets the number of lines in message or text body part.
void	ImportData (const ListItem *root)
	Called by the parser to set the data for this object.