CamelMimeParser

CamelMimeParser —

Synopsis




struct      CamelMimeParser;
enum        camel_mime_parser_state_t;
CamelMimeParser* camel_mime_parser_new      (void);
int         camel_mime_parser_errno         (CamelMimeParser *parser);
int         camel_mime_parser_init_with_fd  (CamelMimeParser *parser,
                                             int fd);
int         camel_mime_parser_init_with_stream
                                            (CamelMimeParser *parser,
                                             CamelStream *stream);
CamelStream* camel_mime_parser_stream       (CamelMimeParser *parser);
int         camel_mime_parser_fd            (CamelMimeParser *parser);
void        camel_mime_parser_scan_from     (CamelMimeParser *parser,
                                             gboolean scan_from);
void        camel_mime_parser_scan_pre_from (CamelMimeParser *parser,
                                             gboolean scan_pre_from);
int         camel_mime_parser_set_header_regex
                                            (CamelMimeParser *parser,
                                             char *matchstr);
camel_mime_parser_state_t camel_mime_parser_step
                                            (CamelMimeParser *parser,
                                             char **buf,
                                             size_t *buflen);
void        camel_mime_parser_unstep        (CamelMimeParser *parser);
void        camel_mime_parser_drop_step     (CamelMimeParser *parser);
camel_mime_parser_state_t camel_mime_parser_state
                                            (CamelMimeParser *parser);
void        camel_mime_parser_push_state    (CamelMimeParser *mp,
                                             camel_mime_parser_state_t newstate,
                                             const char *boundary);
int         camel_mime_parser_read          (CamelMimeParser *parser,
                                             const char **databuffer,
                                             int len);
CamelContentType* camel_mime_parser_content_type
                                            (CamelMimeParser *parser);
const char* camel_mime_parser_header        (CamelMimeParser *parser,
                                             const char *name,
                                             int *offset);


Description

Details

struct CamelMimeParser

struct CamelMimeParser {
	CamelObject parent;

	struct _CamelMimeParserPrivate *priv;
};


enum camel_mime_parser_state_t

typedef enum _camel_mime_parser_state_t {
	CAMEL_MIME_PARSER_STATE_INITIAL,
	CAMEL_MIME_PARSER_STATE_PRE_FROM,       /* data before a 'From' line */
	CAMEL_MIME_PARSER_STATE_FROM,           /* got 'From' line */
	CAMEL_MIME_PARSER_STATE_HEADER,         /* toplevel header */
	CAMEL_MIME_PARSER_STATE_BODY,           /* scanning body of message */
	CAMEL_MIME_PARSER_STATE_MULTIPART,      /* got multipart header */
	CAMEL_MIME_PARSER_STATE_MESSAGE,        /* rfc822 message */
	
	CAMEL_MIME_PARSER_STATE_PART,           /* part of a multipart */
	
	CAMEL_MIME_PARSER_STATE_END = 8,        /* bit mask for 'end' flags */
	
	CAMEL_MIME_PARSER_STATE_EOF = 8,        /* end of file */
	CAMEL_MIME_PARSER_STATE_PRE_FROM_END,   /* pre from end */
	CAMEL_MIME_PARSER_STATE_FROM_END,       /* end of whole from bracket */
	CAMEL_MIME_PARSER_STATE_HEADER_END,     /* dummy value */
	CAMEL_MIME_PARSER_STATE_BODY_END,       /* end of message */
	CAMEL_MIME_PARSER_STATE_MULTIPART_END,  /* end of multipart  */
	CAMEL_MIME_PARSER_STATE_MESSAGE_END,    /* end of message */
} camel_mime_parser_state_t;


camel_mime_parser_new ()

CamelMimeParser* camel_mime_parser_new      (void);

Create a new CamelMimeParser object.

Returns : A new CamelMimeParser widget.

camel_mime_parser_errno ()

int         camel_mime_parser_errno         (CamelMimeParser *parser);

parser :
Returns :

camel_mime_parser_init_with_fd ()

int         camel_mime_parser_init_with_fd  (CamelMimeParser *parser,
                                             int fd);

Initialise the scanner with an fd. The scanner's offsets will be relative to the current file position of the file descriptor. As a result, seekable descritors should be seeked using the parser seek functions.

parser :
fd : A valid file descriptor.
Returns : Returns -1 on error.

camel_mime_parser_init_with_stream ()

int         camel_mime_parser_init_with_stream
                                            (CamelMimeParser *parser,
                                             CamelStream *stream);

Initialise the scanner with a source stream. The scanner's offsets will be relative to the current file position of the stream. As a result, seekable streams should only be seeked using the parser seek function.

parser :
stream :
Returns : -1 on error.

camel_mime_parser_stream ()

CamelStream* camel_mime_parser_stream       (CamelMimeParser *parser);

Get the stream, if any, the parser has been initialised with. May be used to setup sub-streams, but should not be read from directly (without saving and restoring the seek position in between).

parser : MIME parser object
Returns : The stream from _init_with_stream(), or NULL if the parser is reading from a file descriptor or is uninitialised.

camel_mime_parser_fd ()

int         camel_mime_parser_fd            (CamelMimeParser *parser);

Return the file descriptor, if any, the parser has been initialised with.

Should not be read from unless the parser it to terminate, or the seek offset can be reset before the next parse step.

parser : MIME parser object
Returns : The file descriptor or -1 if the parser is reading from a stream or has not been initialised.

camel_mime_parser_scan_from ()

void        camel_mime_parser_scan_from     (CamelMimeParser *parser,
                                             gboolean scan_from);

Tell the scanner if it should scan "^From " lines or not.

If the scanner is scanning from lines, two additional states CAMEL_MIME_PARSER_STATE_FROM and CAMEL_MIME_PARSER_STATE_FROM_END will be returned to the caller during parsing.

This may also be preceeded by an optional CAMEL_MIME_PARSER_STATE_PRE_FROM state which contains the scanned data found before the From line is encountered. See also scan_pre_from().

parser : MIME parser object
scan_from : TRUE if the scanner should scan From lines.

camel_mime_parser_scan_pre_from ()

void        camel_mime_parser_scan_pre_from (CamelMimeParser *parser,
                                             gboolean scan_pre_from);

Tell the scanner whether we want to know abou the pre-from data during a scan. If we do, then we may get an additional state CAMEL_MIME_PARSER_STATE_PRE_FROM which returns the specified data.

parser : MIME parser object
scan_pre_from : TRUE if we want to get pre-from data.

camel_mime_parser_set_header_regex ()

int         camel_mime_parser_set_header_regex
                                            (CamelMimeParser *parser,
                                             char *matchstr);

parser :
matchstr :
Returns :

camel_mime_parser_step ()

camel_mime_parser_state_t camel_mime_parser_step
                                            (CamelMimeParser *parser,
                                             char **buf,
                                             size_t *buflen);

Parse the next part of the MIME message. If _unstep() has been called, then continue to return the same state for that many calls.

If the step is CAMEL_MIME_PARSER_STATE_BODY then the databuffer and datalength pointers will be setup to point to the internal data buffer of the scanner and may be processed as required. Any filters will have already been applied to this data.

Refer to the state diagram elsewhere for a full listing of the states an application is gauranteed to get from the scanner.

parser : MIME parser object
buf :
buflen :
Returns : The current new state of the parser is returned.

camel_mime_parser_unstep ()

void        camel_mime_parser_unstep        (CamelMimeParser *parser);

Cause the last step operation to repeat itself. If this is called repeated times, then the same step will be repeated that many times.

Note that it is not possible to scan back using this function, only to have a way of peeking the next state.

parser : MIME parser object

camel_mime_parser_drop_step ()

void        camel_mime_parser_drop_step     (CamelMimeParser *parser);

Drop the last step call. This should only be used in conjunction with seeking of the stream as the stream may be in an undefined state relative to the state of the parser.

Use this call with care.

parser : MIME parser object

camel_mime_parser_state ()

camel_mime_parser_state_t camel_mime_parser_state
                                            (CamelMimeParser *parser);

Get the current parser state.

parser : MIME parser object
Returns : The current parser state.

camel_mime_parser_push_state ()

void        camel_mime_parser_push_state    (CamelMimeParser *mp,
                                             camel_mime_parser_state_t newstate,
                                             const char *boundary);

Pre-load a new parser state. Used to post-parse multipart content without headers.

mp : MIME parser object
newstate : New state
boundary : Boundary marker for state.

camel_mime_parser_read ()

int         camel_mime_parser_read          (CamelMimeParser *parser,
                                             const char **databuffer,
                                             int len);

Read at most len bytes from the internal mime parser buffer.

Returns the address of the internal buffer in databuffer, and the length of useful data.

len may be specified as INT_MAX, in which case you will get the full remainder of the buffer at each call.

Note that no parsing of the data read through this function occurs, so no state changes occur, but the seek position is updated appropriately.

parser : MIME parser object
databuffer :
len :
Returns : The number of bytes available, or -1 on error.

camel_mime_parser_content_type ()

CamelContentType* camel_mime_parser_content_type
                                            (CamelMimeParser *parser);

Get the content type defined in the current part.

parser : MIME parser object
Returns : A content_type structure, or NULL if there is no content-type defined for this part of state of the parser.

camel_mime_parser_header ()

const char* camel_mime_parser_header        (CamelMimeParser *parser,
                                             const char *name,
                                             int *offset);

Lookup a header by name.

parser :
name : Name of header.
offset : Pointer that can receive the offset of the header in the stream from the start of parsing.
Returns : The header value, or NULL if the header is not defined.