Decode a MIME formatted message.

PASCAL

status = PMDF_decode_message

(dq_context, param, flags, input_line, output_header, output_line, output_block)

C

status = PMDFdecodeMessage

(dq_context, param, flags, input_line, output_header, output_line, output_block)

int PMDFdecodeMessage(PMDF_dq **dq_context, void *param, unsigned long flags, void (*input_line)(), void (*output_header)(), void (*output_line)(), void (*output_block)())

Arguments

dq_context

Optional message dequeue context created with PMDFdequeueInitialize. If not specified, then input_line must be specified.

param

Optional parameter which will be passed to each of the supplied routines, input_line, output_header, output_line, and output_block, when they are called.

flags

Bit flags controlling the operation of PMDFdecodeMessage.

input_line

Optional address of a procedure to read each line of the message to be decoded. If not specified, then dq_context must be specified.

output_header

Address of a procedure to output either the outer message header or the header associated with a message part.

output_line

Address of a procedure to output a line of the content of a non-binary message part.

output_block

Address of a procedure to output a block of data from a binary message part.

Description

PMDFdecodeMessage can be used to decode a MIME message. Example programs illustrating the use of this routine are given in the files api_example9.pas and api_example10.c and can be found in the PMDF_ROOT:[DOC.EXAMPLES] directory on OpenVMS systems or, on UNIX and Windows systems, in the /pmdf/doc/examples directory. Each line of the message to be decoded can come from either a message currently being dequeued or from an arbitrary source. If the former, then supply the message dequeue context generated by PMDFdequeueInitialize and specify zero for the input_line argument. The message being dequeued must have its read point positioned at the start of the message's outer header. That is the position the read point will be at after the last envelope recipient address has been read with PMDFgetRecipient or after calling PMDFrewindMessage. To decode a message from an arbitrary source, specify zero for the dq_context argument, and supply with input_line the address of a procedure to call to obtain each successive line of the message. The input procedure must be of the form

int input_line(void *param, char *line, int *line_len)

When the procedure is called, param will have the value of the parameter supplied to PMDFdecodeMessage with the param argument, line will be the address of a buffer to place the message line into, and *line_len will be the maximum number of bytes which can be written to the buffer. On output, the procedure should return in *line_len the number of bytes placed into the buffer. The buffer does not need to be zero terminated. Finally the procedure should return a value of PMDF__OK if there is more data to read and PMDF__EOF if there is an error or no further data to read. The procedures referenced by output_header, output_line, and output_block have the form

int output_header(void *param, PMDF_hdr *hdr, int part, int depth, int index) int output_line(void *param, char *line, int line_len, int eol) int output_block(void *param, char *data, int data_len, int eol)

where the arguments are as follows:

param	Value passed to PMDF_decode_message for the param argument.
hdr	Pointer to a PMDF_hdr structure containing the header lines to output.
part	Will have the value 2 if the message part associated with the header is textual in nature and the value 1 if the associated part is binary in nature.
depth	Nesting depth in the MIME structure for this message part.
index	Index for this part; first message part at depth N has an index value of 1, second part at depth N has an index value of 2, etc..
line	Line of text output. This text comes from the content of a non-binary message part. The line is not null terminated.
line_len	Length in bytes of the line of message text to output.
eol	Binary. Indicates end-of-line was seen.
data	Raw binary data to output. This data comes from the content of a binary data part. The data is not null terminated and can contain nulls within it.
data_len	Length in bytes of the data to output.

The output routines should return an odd-valued result (e.g., 1, PMDF__OK) when successful, and an even-valued result otherwise (e.g., 0, PMDF__NO). When an even-valued result is returned by an output routine, PMDFdecodeMessage will abort the decode operation and return to the caller the value returned by the output routine. When the lowest bit of flags is set to 1, a message in any of the various formats which PMDF understands (e.g., RFC 1154, Pathworks, NeXT, etc.) will be first translated to MIME prior to decoding. Furthermore, if the message does not have a recognized format, but does contain embedded information encoded with UUENCODE or BINHEX, then the message will be converted to MIME prior to decoding with the encoded material placed in a separate attachment.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__BAD	Both dq_context and input_line were zero. Message not decoded.
PMDF__BADCONTEXT	Invalid dq_context supplied. Message not decoded.