Creating an rfc2045 structure

#include <rfc2045.h>

struct rfc2045 *ptr=rfc2045_alloc();
void rfc2045_parse(struct rfc2045 *ptr, const char *txt, size_t cnt);

struct rfc2045 *ptr=rfc2045_fromfd(int fd);
struct rfc2045 *ptr=rfc2045_fromfp(FILE *fp);

void rfc2045_free(struct rfc2045 *ptr);

void rfc2045_error(const char *errmsg)
{
        perror(errmsg);
        exit(0);
}

The rfc2045 structure is created from an existing message. The function rfc2045_alloc() allocates the structure, then rfc2045_parse() is called to initialize the structure based on the contents of a message. txt points to the contents of the message, and cnt contains the number of bytes in the message.

Large messages are parsed by calling rfc2045_parse() multiple number of times, each time passing a portion of the overall message. There is no need to call a separate function after the entire message is parsed -- the rfc2045 structure is created dynamically, on the fly.

rfc2045_alloc() returns NULL if there was insufficient memory to allocate the structure. The rfc2045_parse() also allocates memory, internally, however no error indication is return in the event of a memory allocation failure. Instead, the function rfc2045_error() is called, with errmsg set to "Out of memory". rfc2045_error() is also called by rfc2045_alloc() - it also calls rfc2045_error(), before returning a NULL pointer.

The rfc2045_error() function is not included in the rfc2045 library, it must be defined by the application to report the error in some appropriate way. All functions below will use rfc2045_error() to report an error condition (currently only insufficient memory is reported), in addition to returning any kind of an error indicator. Some functions do not return an error indicator, so rfc2045_error() is the only reliable way to detect a failure.

The rfc2045_fromfd() function initializes an rfc2045 structure from a file descriptor. It is equivalent to calling rfc2045_alloc(), then reading the contents of the given file descriptor, and calling rfc2045_parse(). The rfc2045_fromfp() function initializes an rfc2045 structure from a FILE.

After the rfc2045 structure is initialized, the functions described below may be used to access and work with the contents of the structure. When the rfc2045 structure is no longer needed, the function rfc2045_free() deallocates and destroys the structure.

Structure of a MIME message

struct rfc2045 {

        struct rfc2045 *parent;

        struct rfc2045 *firstpart;
        struct rfc2045 *next;
        int             isdummy;
        int             rfcviolation;
} ;

The rfc2045 structure has many fields, only some are publicly documented. A MIME message is represented by a recursive tree of linked rfc2045 structures. Each instance of the rfc2045 structure represents a single MIME section of a MIME-formatted message.

The top-level structure that represents the entire message is created by the rfc2045_alloc() function. The remaining structures are created dynamically by rfc2045_parse(). Any rfc2045 structure, except ones whose isdummy flag is set, may be used acomman for IMAP account “loginid”.

Creating an rfc2045 structure

#include <rfc2045.h>

struct rfc2045 *ptr=rfc2045_alloc();
void rfc2045_parse(struct rfc2045 *ptr, const char *txt, size_t cnt);

struct rfc2045 *ptr=rfc2045_fromfd(int fd);
struct rfc2045 *ptr=rfc2045_fromfp(FILE *fp);

void rfc2045_free(struct rfc2045 *ptr);

void rfc2045_error(const char *errmsg)
{
        perror(errmsg);
        exit(0);
}

The rfc2045 structure is created from an existing message. The function rfc2045_alloc() allocates the structure, then rfc2045_parse() is called to initialize the structure based on the contents of a message. txt points to the contents of the message, and cnt contains the number of bytes in the message.

Large messages are parsed by calling rfc2045_parse() multiple number of times, each time passing a portion of the overall message. There is no need to call a separate function after the entire message is parsed -- the rfc2045 structure is created dynamically, on the fly.

rfc2045_alloc() returns NULL if there was insufficient memory to allocate the structure. The rfc2045_parse() also allocates memory, internally, however no error indication is return in the event of a memory allocation failure. Instead, the function rfc2045_error() is called, with errmsg set to "Out of memory". rfc2045_error() is also called by rfc2045_alloc() - it also calls rfc2045_error(), before returning a NULL pointer.

The rfc2045_error() function is not included in the rfc2045 library, it must be defined by the application to report the error in some appropriate way. All functions below will use rfc2045_error() to report an error condition (currently only insufficient memory is reported), in addition to returning any kind of an error indicator. Some functions do not return an error indicator, so rfc2045_error() is the only reliable way to detect a failure.

The rfc2045_fromfd() function initializes an rfc2045 structure from a file descriptor. It is equivalent to calling rfc2045_alloc(), then reading the contents of the given file descriptor, and calling rfc2045_parse(). The rfc2045_fromfp() function initializes an rfc2045 structure from a FILE.

After the rfc2045 structure is initialized, the functions described below may be used to access and work with the contents of the structure. When the rfc2045 structure is no longer needed, the function rfc2045_free() deallocates and destroys the structure.

Structure of a MIME message

struct rfc2045 {

        struct rfc2045 *parent;

        struct rfc2045 *firstpart;
        struct rfc2045 *next;
        int             isdummy;
        int             rfcviolation;
} ;

The rfc2045 structure has many fields, only some are publicly documented. A MIME message is represented by a recursive tree of linked rfc2045 structures. Each instance of the rfc2045 structure represents a single MIME section of a MIME-formatted message.

The top-level structure that represents the entire message is created by the rfc2045_alloc() function. The remaining structures are created dynamically by rfc2045_parse(). Any rfc2045 structure, except ones whose isdummy flag is set, may be used acomman for IMAP account “loginid”.