PMDF Programmer's Reference Manual
Previous Next Contents Index

PMDFgetEnvelopeId

Obtain the envelope id associated with this message.

PASCAL

status = PMDF_get_envelope_id

(dq_context, envelope_id, envelope_id_len)

argument information
Argument Data type Access Mechanism
dq_context context pointer read/write reference
envelope_id descriptor read/write reference
envelope_id_len unsigned word write reference

C

status = PMDFgetEnvelopeId

(dq_context, envelope_id, envelope_id_len)

argument information 


int PMDFgetEnvelopeId(PMDF_dq **dq_context, 
                      char     *envelope, 
                      int      *envelope_id_len)

Arguments

dq_context

A message dequeue context created with PMDFdequeueInitialize.

envelope_id

String to receive the message's envelope id. Length must be at least ALFA_SIZE+1 bytes.

envelope_id_len

Length in bytes of the envelope id. Callers using PMDFgetEnvelopeId must, on input, supply the maximum length in bytes of envelope_id.

Description

Messages queued to PMDF often carry with them two identification strings -- "id's" for short. The first is the "message id" as seen in the message's RFC 822 "Message-id:" header line. This id is the same for all copies of a given message. The second id is the envelope id. Each copy of the message has a distinct envelope id, if it has any envelope id at all. It is important to note that not all messages can have envelope id's. Specifically, RFC 1891 forbids adding an envelope id to a message obtained via SMTP without an envelope id. As such, it is possible to find messages in PMDF's queues which have no envelope id's---these are messages which were received without an envelope id. When a message dequeue is initiated, the message and envelope id's can be obtained by calling PMDFgetEnvelopeId and PMDFgetMessageId. It is particularly important to obtain the envelope id as it should be propogated forward by channels which re-enqueue the message for subsequent processing.

Return Values

PMDF__OK Normal, successful completion.
PMDF__BADCONTEXT Illegal or corrupt context. No envelope id retrieved.
PMDF__FATERRLIB Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. No envelope id retrieved.
PMDF__INSVIRMEM Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. No envelope id retrieved.
PMDF__INVSTRDES Invalid string descriptor for envelope_id: descriptor has an invalid value in its DSC$B_CLASS field. No envelope id retrieved.
PMDF__STRTRU Supplied string was too long; value truncated to fit.

Previous Next Contents Index