MimeParserVtable.h File Reference

Detailed Description

In order to perform useful work using the functions in the MimeParser module, you must create and install callback functions that are called by the MIME parser object. This reference page describes the callback functions that you may implement and install into the parser. All callback functions are optional: the pointer in the vtable structure may be set to NULL for any callback function that is not implemented.

Remember that all the functions described in this reference page are functions that you implement. Your code should not try to call any of these functions, because they do not exist in the XStream MIME library. Rather, you implement these functions and install them, and the MIME parser calls them. To install them, create an instance of MimeParserVtable and set the pointers in that structure to point to your callback functions. Then call MimeParser_setVtable() to install the vtable structure.

Of course, the names of the functions and the names of the parameters are not significant: you may name the functions and parameters as you wish. You must, however, faithfully conform to the function prototypes. The number and types of the parameters must exactly match the documented functions.

The first parameter of all the callback functions is an opaque pointer to client data. This is the same pointer that you pass to the parser object when you call MimeParser_setVtable(). The parameter allows you to pass context information to your callback functions without using global variables. It also allows you to achieve the same effect as a virtual function in an object-oriented programming language such as C++ (which passes context information via the this pointer).

The example program in the file simple.c provides simple callback functions that print the values of their parameters. You may wish to experiment with this program to learn how the callback functions work.

Data Structures

struct MimeParserVtable

Table of callback functions for MimeParser. More...

Typedefs

typedef MimeParserVtable MimeParserVtable

Table of callback functions for MimeParser.

Functions

void Event (void *clientData, int event, const void *eventData)

Notifies the client of a parse event.

void HeaderField (void *clientData, const char *fieldName, size_t fieldNameOffset, size_t fieldNameLength, const char *fieldBody, size_t fieldBodyOffset, size_t fieldBodyLength)

Notifies the client of a header field in the MIME message.

void Bytes (void *clientData, const char *buffer, size_t offset, size_t length)

Conveys byte data to client.

void Error (void *clientData, int errorCode, const char *errorText)

Notifies the client of an error that occurred during parsing.

Typedef Documentation

typedef struct MimeParserVtable MimeParserVtable

Table of callback functions for MimeParser.
See the documentation of the individual functions in MimeParserVtable.h.

Function Documentation

void Bytes ( void * clientData,

const char * buffer,

size_t offset,

size_t length

)

Conveys byte data to client.
The parser calls this callback function at predictable times:

The parser calls Bytes() between the EVENT_BEGIN_SIMPLE_BODY and EVENT_END_SIMPLE_BODY events to convey the byte data in a non-multipart body.

The parser calls Bytes() between the EVENT_BEGIN_MESSAGE_BODY and EVENT_END_MESSAGE_BODY events to convey the byte data in an encapsulated message (MIME type "message/rfc822").

The parser calls Bytes() between the EVENT_BEGIN_MULTIPART_BODY and EVENT_BEGIN_BODY_PART events to convey the byte data in the preamble of a multipart message.

The parser calls Bytes() between the EVENT_END_BODY_PART and EVENT_END_MULTIPART_BODY events to convey the byte data in the epilogue of a multipart message.

In many cases, the buffer parameter points to the same array that was provided to the parser as an argument to the MimeParser_parseBuffer() function. The parser tries to avoid buffer-to-buffer copies whenever possible in order to achieve a performance boost. Important: Your code must not assume that the array is the same.

Parameters:

clientData pointer to client data

buffer pointer to a char array containing parsed byte data

offset offset in the array of the beginning of the parsed byte data

length length of the parsed byte data

void Error ( void * clientData,

int errorCode,

const char * errorText

)

Notifies the client of an error that occurred during parsing.
The MIME parser correctly parses all MIME messages that are correct according to the MIME standard. However, when a message is not correct according to the MIME standard, the parser will detect and report errors.
When an error occurs, the parser calls this callback function, and provides to the client both an error code and a short text description of the error that is suitable for writing to an error log. (Do not present this error message to an end user! It's not that kind of error message!)
Not all errors are fatal. You may wish to treat non-fatal errors as you would warnings: they indicate that there was a problem parsing the message. In many cases, if the parser recovers from a non-fatal error it will be unable to parse the message correctly.
The error constants are defined in the header file xmime/MimeParser.h. These constants are listed in the table below.

Constant Description

ERROR_OUT_OF_MEMORY The parser tried unsuccessfully to allocate memory. This is a fatal error.

ERROR_UNKNOWN_MEDIA_TYPE The parser could not interpret the field body of the Content-Type header field. This is not a fatal error. The parser makes a safe assumption about the media type and continues.

ERROR_MISSING_BOUNDARY A final boundary was missing. This is not a fatal error.

ERROR_UNEXPECTED_EOF The parser reached the end of the data (end of file) when it was not expecting it. This is not a fatal error.

ERROR_UNKNOWN_BOUNDARY The media type of a message or body part is "multipart" but the parser could not determine the boundary that separates the body parts. This is not a fatal error.

ERROR_BAD_HEADER_FIELD While parsing the header fields of a message or body part, the parser encountered an error. This error can happen, for example, if the blank line that separates the headers and body is missing.

Parameters:

clientData pointer to client data

errorCode enumerated value indicating an error that occurred during parsing

errorText text description of the error, suitable for writing to an error log

void Event ( void * clientData,

int event,

const void * eventData

)

Notifies the client of a parse event.
The events are described in the table below. The constants are defined in the include file xmime/MimeParser.h.

Constant Description

EVENT_BEGIN_MESSAGE Beginning of the message

EVENT_END_MESSAGE End of the message

EVENT_BEGIN_HEADERS Beginning of the headers in a message or body part

EVENT_END_HEADERS End of the headers in a message or body part

EVENT_BEGIN_SIMPLE_BODY Beginning of a non-multipart body

EVENT_END_SIMPLE_BODY End of a non-multipart body

EVENT_BEGIN_MESSAGE_BODY Beginning of an encapsulated message (MIME type "message/RFC822"

EVENT_END_MESSAGE_BODY End of an encapsulated message (MIME type "message/RFC822"

EVENT_BEGIN_MULTIPART_BODY Beginning of a multipart body

EVENT_END_MULTIPART_BODY End of a multipart body

EVENT_BEGIN_BODY_PART Beginning of a body part within a multipart body

EVENT_END_BODY_PART End of a body part within a multipart body

The events are always paired. For every "begin" event, there is a paired "end" event. The events also nest properly. (This is similar to the way XML begin and end tags nest properly.)
Only one event has associated data. If the event is EVENT_BEGIN_MULTIPART_BODY, then the eventData parameter points to a string that contains the boundary that separates the body parts.

Parameters:

clientData pointer to client data

event enumerated value indicating an event

eventData data associated with the event

void HeaderField ( void * clientData,

const char * fieldName,

size_t fieldNameOffset,

size_t fieldNameLength,

const char * fieldBody,

size_t fieldBodyOffset,

size_t fieldBodyLength

)

Notifies the client of a header field in the MIME message.
In many cases, the fieldName and fieldBody parameters point to the same array that was provided to the parser as an argument to the MimeParser_parseBuffer() function. The parser tries to avoid buffer-to-buffer copies whenever possible in order to achieve a performance boost. Important: Your code must not assume that the array is the same.

Parameters:

clientData opaque pointer to client data

fieldName pointer to a char array containing a parsed header field name

fieldNameOffset offset in the array of the beginning of the header field name

fieldNameLength length of the header field name

fieldBody pointer to a char array containing a parsed header field body

fieldBodyOffset offset in the array of the beginning of the header field body

fieldBodyLength length of the header field body


Data Structures
struct	MimeParserVtable
	Table of callback functions for MimeParser. More...
Typedefs
typedef MimeParserVtable	MimeParserVtable
	Table of callback functions for MimeParser.
Functions
void	Event (void clientData, int event, const void eventData)
	Notifies the client of a parse event.
void	HeaderField (void clientData, const char fieldName, size_t fieldNameOffset, size_t fieldNameLength, const char *fieldBody, size_t fieldBodyOffset, size_t fieldBodyLength)
	Notifies the client of a header field in the MIME message.
void	Bytes (void clientData, const char buffer, size_t offset, size_t length)
	Conveys byte data to client.
void	Error (void clientData, int errorCode, const char errorText)
	Notifies the client of an error that occurred during parsing.