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 PMDFaddHeaderLine or PMDFdeleteHeaderLine.

A header structure can be created in one of two ways:

1. While dequeuing a message, the header lines of that message can be read into a header structure with PMDFreadHeader. In this case, PMDFreadHeader creates 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.
2. By calling PMDFaddHeaderLine to add a header line to a non-existent header structure. In this case, pass a value of zero to PMDFaddHeaderLine for the header argument. PMDFaddHeaderLine will 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.

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.⁹ 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 PMDFreadHeader, a 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 (*hdr)[i]; e.g.,

(*hdr)[HL_DATE]->line

From Pascal, use hdr^[i]; e.g.,

hdr^[HL_DATE]^.line

The routine display_header_lines in 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:

LINE

A pointer to the header line. The header line is a null-terminated character string of length LINE_LENGTH bytes. 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_LENGTH

A 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_LINE

A 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.

The NEXT_LINE field is the mechanism which enables more than one header line of a given type (e.g., Received:, Comments:, Keywords:, 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_COMMENTS]->LINE

and the second one with

HEADER[HL_COMMENTS]->NEXT_LINE->LINE

Each entry in the header structure array is actually a pointer to a linked list of header lines. Each header line in a given list is of the type corresponding to the index in the header structure array. That is, each header line in the linked list 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 PMDFreadLine are 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.