Traffic Server Software Developers Kit

The Traffic Server API MIME header functions enable you to retrieve and modify information about HTTP MIME fields.

An HTTP request or response consists of a header, body, and trailer. The HTTP header consists of a request (or response) line and a MIME header. A MIME header is composed of zero or more MIME fields. A MIME field is composed of a field name, a colon, and zero or more field values (the values in a field are separated by commas). In the example below: Foo is the MIME field name, bar is the first MIME field value, and car is the second MIME field value.

Foo: bar, car

The following is an augmented Backus-Naur Form (BNF) for the form of a MIME header - it specifies exactly what was described above. A header consists of zero or more fields that consist of a name, a separating colon, and zero or more values. A name or value is simply a string of tokens that is potentially zero length; a token is any character except certain control characters and separators (such as colons).

MIME-header = *MIME-field
MIME-field = field-name ":" #field-value
field-name = *token
field-value = *token

For the purposes of retrieving a field, field names are not case-sensitive; ergo, the field names Foo, foo and fOO are all equivalent.

The MIME header data structure is a parsed version of a standard Internet MIME header. The MIME header data structure is similar to the URL data structure (see URLs). The actual data is stored in a marshal buffer and the MIME header functions operate on a marshal buffer and a location (INKMLoc) within the buffer.

After a call to INKMimeHdrFieldDestroy, INKMimeHdrFieldRemove, or INKUrlDestroy is made, you must deallocate the INKMLoc handle with a call to INKHandleMLocRelease. You do not need to deallocate a NULL handles. For example: if you called INKMimeHdrFieldValueStringGet to get the value of the content type field and the field does not exist, then it returns INK_NULL_MLOC. In such a case, you wouldn't need to deallocate the handle with a call to INKHandleMLocRelease.

The location (INKMLoc) in the following MIME header functions can be either a HTTP header location or a MIME header location. If an HTTP header location is passed to these function, then the system locates the MIME header associated with this HTTP header and then executes the corresponding MIME header operations specified by the functions (see the example in the description of INKMimeHdrCopy).

MIME headers may contain more than one MIME field with the same name. While previous versions of Traffic Server joined multiple fields with the same name into one field with composite values, this behavior comes at a performance cost and causes compatability issues with older clients and servers. Future versions of Traffic Server will cease coalescing duplicate fields. Correctly-behaving plugins should check for the presence of duplicate fields, and iterate over the duplicate fields, by using INKMimeHdrFieldNextDup.

To facilitate fast comparisons and to reduce storage size, Traffic Server defines several pre-allocated field names. These field names correspond to field names found in HTTP and NNTP headers.

The header field names above are defined in InkAPI.h as const char* strings. When Traffic Server sets the name portion of a header field (or any portion for that matter), it makes a quick check to see if the new value is one of the known values. If it is, then it stores a pointer into a global table instead of storing the known value in the marshal buffer. The header field names listed above are also pointers into this table, which allows simple pointer comparison of the value returned from INKMimeHdrFieldNameGet with one of the values listed above. It is also recommended that you use the above values when referring to one of the known header field names to avoid the possibility of a spelling error.

Traffic Server adds one important feature to MIME fields that you may not know about: Traffic Server does not print a MIME field if the field name begins with the '@' symbol. For example: a plugin can add the field "@My-Field" to a header. Even though Traffic Server never sends that field out in a request to an origin server or in a response to a client, it can be printed in Traffic Server logs by defining a custom log config file that explicitly logs such fields. This provides a useful mechanism for plugins to store information about an object in one of the MIME headers associated with the object.

The MIME header functions are listed below: