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.


Generated on Thu Mar 29 17:59:09 2007 for MiniMIME by  doxygen 1.5.1