A message header structure is used to store a collection of header
lines. The stored header lines can be output by
PMDFwriteHeader to one or more messages being enqueued,
and altered with
A header structure can be created in one of two ways:
PMDFreadHeader. In this case,
PMDFreadHeadercreates a header structure, reads header lines into it, and then returns a pointer to the structure. The structure can then be used with any of the other header routines.
PMDFaddHeaderLineto add a header line to a non-existent header structure. In this case, pass a value of zero to
PMDFaddHeaderLinefor the header argument.
PMDFaddHeaderLinewill allocate and initialize the header structure, add the specified header line to it, and then return the address of the header structure in the header argument.
PMDFdisposeHeader. This releases the memory allocated to the structure.
The header structure is an array of pointers to header line structures
whose format is described below. Each entry in the array describes a
particular type of header line. The
HL_ constants defined
in the API include files are indices into this array.9 For
instance, suppose that the message header of Example 1-1 is read with
PMDFreadHeader and stored in a header structure pointed at
by the pointer variable
HEADER. Then the header structure
would appear as shown in Figure 1-1.
Figure 1-1 Sample Header Structure
After reading in a message header with
program can "probe" to see which header lines were specified
in that message header. This is done by checking to see if the
corresponding entry in the header structure array is zero (null) or
not. For instance, if
HEADER[HL_REPLY_TO] is zero, then no
Reply-to: header line was present in the message header.
From C, the ith entry in a header structure would be
referenced using the syntax
display_header_linesin Examples 1-8 and 1-9 illustrates how to walk through a header structure.
The format of a header line structure is shown in Figure 1-1. (There are actually four header line structures shown in that figure.) Each header line structure has three fields, which are as follows:
LINEA pointer to the header line. The header line is a null-terminated character string of length
LINE_LENGTHbytes. The quotes shown surrounding each header line in Figure 1-1 are not part of the header line; they are used to indicate that a character string is being depicted.
LINE_LENGTHA signed longword (4 bytes) containing the length of the character string pointed at by
LINE. This length does not include the null terminator at the end of the string.
NEXT_LINEA pointer to any additional header line structures describing header lines of the same type. When zero, indicates that no additional header lines of the same type exist.
NEXT_LINE field is the mechanism which enables more
than one header line of a given type (e.g.,
etc.) to be stored in a header structure. For instance, if two
Comments: header lines are stored in a header structure,
then the first one is accessed with
HEADER[HL_x]is of type
HL_x. The order in which the header lines appear in the linked list are the order in which they were added to the header structure: the first header line in the list is the first one added, the second one is the second one added, and so on. Header lines added to a structure by
PMDFreadLineare added in the order that they are read from a message header. Thus, the first
Received:line in a header is the first one added by
PMDFreadLine, the second
Received:line the second one added, and so forth.
9 These constants are defined in the