Accessing and manipulating MIME parts

Creating and destroying MIME parts
mm_mimepart *	mm_mimepart_new (void)
mm_mimepart *	mm_mimepart_fromfile (const char *filename)
void	mm_mimepart_free (struct mm_mimepart *part)
Accessing the MIME part's mail header
int	mm_mimepart_attachheader (struct mm_mimepart *part, struct mm_mimeheader *header)
int	mm_mimepart_countheaders (struct mm_mimepart *part)
int	mm_mimepart_countheaderbyname (struct mm_mimepart *part, const char *name)
mm_mimeheader *	mm_mimepart_getheaderbyname (struct mm_mimepart *part, const char *name, int idx)
const char *	mm_mimepart_getheadervalue (struct mm_mimepart *part, const char *name, int idx)
int	mm_mimepart_headers_start (struct mm_mimepart *part, struct mm_mimeheader **id)
mm_mimeheader *	mm_mimepart_headers_next (struct mm_mimepart *part, struct mm_mimeheader **id)
Accessing and manipulating the MIME part's body
char *	mm_mimepart_getbody (struct mm_mimepart *part, int opaque)
void	mm_mimepart_setbody (struct mm_mimepart *part, const char *data, int opaque)
size_t	mm_mimepart_getlength (struct mm_mimepart *part)
char *	mm_mimepart_decode (struct mm_mimepart *part)
int	mm_mimepart_flatten (struct mm_mimepart *part, char **result, size_t *length, int opaque)
int	mm_mimepart_setdefaultcontenttype (struct mm_mimepart *part, int composite)
Accessing the MIME part's Content-Type information
void	mm_mimepart_attachcontenttype (struct mm_mimepart *part, struct mm_content *ct)
mm_content *	mm_mimepart_gettype (struct mm_mimepart *part)

---

Detailed Description

MIME parts, also called entities, represent the structure of a MIME message. ``Normal'' internet messages have only a single part, and are called ``flat'' messages. Multipart messages have more then one part, and each MIME part can have it's own subset of headers.

Provided here are functions to easily access all informations from a MIME part, including their specific headers and bodies.

---

Function Documentation

void mm_mimepart_attachcontenttype	(	struct mm_mimepart *	part,
		struct mm_content *	ct
	)

Attaches a context type object to a MIME part

Parameters:

	part	A valid MIME part object
	ct	The content type object to attach

Returns:

Nothing

This function attaches a Content-Type object to a MIME part. It does not care whether the Content-Type suites the actual content in the MIME part, so the programmer should take care of that.

int mm_mimepart_attachheader	(	struct mm_mimepart *	part,
		struct mm_mimeheader *	header
	)

Attaches a mm_mimeheader object to a MIME part

Parameters:

	part	A valid MIME part object
	header	A valid MIME header object

Returns:

0 if successfull or -1 if the header could not be attached

int mm_mimepart_countheaderbyname	(	struct mm_mimepart *	part,
		const char *	name
	)

Retrieves the number of MIME headers with a given name in a MIME part

Parameters:

	part	A valid MIME part object
	name	The name of the MIME header which to count for

Returns:

The number of MIME headers within the MIME part

int mm_mimepart_countheaders

(

struct mm_mimepart *

part

)

Retrieves the number of MIME headers available in a MIME part

Parameters:

part

A valid MIME part object

Returns:

The number of MIME headers within the MIME part

char* mm_mimepart_decode

(

struct mm_mimepart *

part

)

Decodes a MIME part according to it's encoding using MiniMIME codecs

Parameters:

A

valid MIME part object

Returns:

0 if the MIME part could be successfully decoded or -1 if not

Note:

Sets mm_errno on error

This function decodes the body of a MIME part with a registered decoder according to it's Content-Transfer-Encoding header field.

int mm_mimepart_flatten	(	struct mm_mimepart *	part,
		char **	result,
		size_t *	length,
		int	opaque
	)

Creates an ASCII representation of the given MIME part

Parameters:

	part	A valid MIME part object
	result	Where to store the result
	length	Where to store the length of the result
	opaque	Whether to use the opaque MIME part 0 on success or -1 on error.

See also:

mm_context_flatten

This function creates an ASCII representation of a given MIME part. It will dynamically allocate the memory needed and stores the result in the memory region pointed to by result. The length of the result will be stored in length. If opaque is set to 1, mm_mimepart_flatten will store an opaque version of the MIME part in result, which means no headers will be created or sanitized. This is particulary useful if the part is digitally signed by e.g. PGP, and the signature spans the header fields of the part in question.

void mm_mimepart_free

(

struct mm_mimepart *

part

)

Frees all memory allocated by a mm_mimepart object.

Parameters:

part

A pointer to an allocated mm_mimepart object

See also:

mm_mimepart_new

struct mm_mimepart* mm_mimepart_fromfile

(

const char *

filename

)

Creates a MIME part from a file

Parameters:

filename

The name of the file to create the MIME part from

Returns:

A pointer to a new MIME part object

This function creates a new MIME part object from a file. The object should be freed using mm_mimepart_free() later on. This function does NOT set the Content-Type and neither does any encoding work.

char* mm_mimepart_getbody	(	struct mm_mimepart *	part,
		int	opaque
	)

Gets the pointer to the MIME part's body data

Parameters:

	part	A valid MIME part object
	opaque	Whether to get the opaque part or not

Returns:

A pointer to the MIME part's body

See also:

mm_mimepart_setbody

struct mm_mimeheader* mm_mimepart_getheaderbyname	(	struct mm_mimepart *	part,
		const char *	name,
		int	idx
	)

Get a MIME header object from a MIME part

Parameters:

	part	A valid MIME part object
	name	The name of the MIME header which to retrieve
	idx	Which header field to get (in case of multiple headers of the same name).

Returns:

A pointer to the requested MIME header on success, or NULL if there either isn't a header with the requested name or idx is out of range.

const char* mm_mimepart_getheadervalue	(	struct mm_mimepart *	part,
		const char *	name,
		int	idx
	)

Gets the value of a MIME header object

Parameters:

	part	A valid MIME part object
	name	The name of the header field to get the value from
	idx	The index of the header field to get, in case there are multiple headers with the same name.

Returns:

A pointer to the requested value on success, or NULL if there either isn't a header with the requested name or idx is out of range.

size_t mm_mimepart_getlength

(

struct mm_mimepart *

part

)

Gets the length of a given MIME part object

Parameters:

part

A valid MIME part object

Returns:

The size of the part's body in byte.

This function returns the total length of the given MIME part's body. The length does not include the headers of the MIME parts. If the function returns 0, no body part is set currently.

struct mm_content* mm_mimepart_gettype

(

struct mm_mimepart *

part

)

Gets the Content-Type of a given MIME part object

Parameters:

part

A valid MIME part object

Returns:

The Content-Type object of the specified MIME part

This function returns a pointer to the Content-Type object of the given MIME part. This pointer might be set to NULL, indicating that there is no Content-Type object for the given MIME part currently.

struct mm_mimeheader* mm_mimepart_headers_next	(	struct mm_mimepart *	part,
		struct mm_mimeheader **	id
	)

Returns the next MIME header of a given MIME part object

Parameters:

	part	A valid MIME part object
	id	A previously initialized MIME header object

Returns:

A pointer to the MIME header object or NULL if end of headers was reached.

See also:

mm_mimepart_headers_start

int mm_mimepart_headers_start	(	struct mm_mimepart *	part,
		struct mm_mimeheader **	id
	)

Initializes a header loop for a given MIME part

Parameters:

	part	A valid MIME part object
	id	The address of a MIME header object (to allow reentrance)

Returns:

0 on success or -1 on failure

See also:

mm_mimepart_headers_next

Looping through headers can be done in the following way:

 struct mm_mimeheader *header, *lheader;

 mm_mimepart_headers_start(part, &lheader);

 while ((header = mm_mimepart_headers_next(part, &lheader)) != NULL) {
        printf("%s: %s\n", header->name, header->value);        
 }

For convienience, the macro mm_mimepart_headers_foreach() can be used to loop through headers in a one-shot manner.

struct mm_mimepart* mm_mimepart_new

(

void

)

Allocates memory for a new mm_mimepart structure and initializes it.

Returns:

A pointer to a struct of type mm_mimeheader or NULL on failure

See also:

mm_mimepart_free

Note:

The memory must be freed by using mm_mimepart_free() later on.

void mm_mimepart_setbody	(	struct mm_mimepart *	part,
		const char *	data,
		int	opaque
	)

Sets the MIME part's body data

Parameters:

	part	A valid MIME part object
	data	A pointer to the data which to set

See also:

mm_mimepart_getbody

This functions sets the body data for a given MIME part. The string pointed to by data must be NUL-terminated. The data is copied into the MIME part's body, and thus, the memory pointed to by data can be freed after the operation.

int mm_mimepart_setdefaultcontenttype	(	struct mm_mimepart *	part,
		int	composite
	)

Sets the default Content-Type for a given MIME part

Parameters:

	part	A valid MIME part object
	part	Whether the Content-Type should be for composite or not

Returns:

0 on success or -1 on failure

This function sets a default Content-Type according to RFC 2045 with a value of "text/plain; charset="us-ascii"". This function should only be used if the MIME part in question does not have a valid Content-Type specification.

---