MIME Headers

The Traffic Server **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 contains 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 (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 example 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 contain a name, 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). For the purpose of retrieving a field, field names are not case-sensitive; therefore, the field names Foo, foo and fOO are all equivalent.

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

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; the MIME header functions operate on a marshal buffer and a location (TSMLoc) within the buffer.

After a call to TSMimeHdrFieldDestroy or TSMimeHdrFieldRemove is made, you must deallocate the TSMLoc handle with a call to TSHandleMLocRelease. You do not need to deallocate a nullptr handles. For example: if you call TSMimeHdrFieldValueStringGet to get the value of the content type field and the field does not exist, then it returns TS_NULL_MLOC. In such a case, you wouldn't need to deallocate the handle with a call to TSHandleMLocRelease.

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

Note: MIME headers may contain more than one MIME field with the same name. Previous versions of Traffic Server joined multiple fields with the same name into one field with composite values, but this behavior came at a performance cost and caused compatibility issues with older clients and servers. Hence, the current version of Traffic Server does not coalesce duplicate fields. Correctly-behaving plugins should check for the presence of duplicate fields and iterate over the duplicate fields by using TSMimeHdrFieldNextDup.

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

"Accept"
const char *TS_MIME_FIELD_ACCEPT
int TS_MIME_LEN_ACCEPT
"Accept-Charset"
const char *TS_MIME_FIELD_ACCEPT_CHARSET
int TS_MIME_LEN_ACCEPT_CHARSET
"Accept-Encoding"
const char *TS_MIME_FIELD_ACCEPT_ENCODING
int TS_MIME_LEN_ACCEPT_ENCODING
"Accept-Language"
const char *TS_MIME_FIELD_ACCEPT_LANGUAGE
int TS_MIME_LEN_ACCEPT_LANGUAGE
"Accept-Ranges"
const char *TS_MIME_FIELD_ACCEPT_RANGES
int TS_MIME_LEN_ACCEPT_RANGES
"Age"
const char *TS_MIME_FIELD_AGE
int TS_MIME_LEN_AGE
"Allow"
const char *TS_MIME_FIELDALLOW
int TS_MIME_LEN_ALLOW
"Approved"
const char *TS_MIME_FIELDAPPROVED
int TS_MIME_LEN_APPROVED
"Authorization"
const char *TS_MIME_FIELDAUTHORIZATION
int TS_MIME_LEN_AUTHORIZATION
"Bytes"
const char *TS_MIME_FIELDBYTES
int TS_MIME_LEN_BYTES
"Cache-Control"
const char *TS_MIME_FIELDCACHE_CONTROL
int TS_MIME_LEN_CACHE_CONTROL
"Client-ip"
const char *TS_MIME_FIELDCLIENT_IP
int TS_MIME_LEN_CLIENT_IP
"Connection"
const char *TS_MIME_FIELDCONNECTION
int TS_MIME_LEN_CONNECTION
"Content-Base"
const char *TS_MIME_FIELDCONTENT_BASE
int TS_MIME_LEN_CONTENT_BASE
"Content-Encoding"
const char *TS_MIME_FIELDCONTENT_ENCODING
int TS_MIME_LEN_CONTENT_ENCODING
"Content-Language"
const char *TS_MIME_FIELDCONTENT_LANGUAGE
int TS_MIME_LEN_CONTENT_LANGUAGE
"Content-Length"
const char *TS_MIME_FIELDCONTENT_LENGTH
int TS_MIME_LEN_CONTENT_LENGTH
"Content-Location"
const char *TS_MIME_FIELDCONTENT_LOCATION
int TS_MIME_LEN_CONTENT_LOCATION
"Content-MD5"
const char *TS_MIME_FIELDCONTENT_MD5
int TS_MIME_LEN_CONTENT_MD5
"Content-Range"
const char *TS_MIME_FIELDCONTENT_RANGE
int TS_MIME_LEN_CONTENT_RANGE
"Content-Type"
const char *TS_MIME_FIELDCONTENT_TYPE
int TS_MIME_LEN_CONTENT_TYPE
"Control"
const char *TS_MIME_FIELDCONTROL
int TS_MIME_LEN_CONTROL
"Cookie"
const char *TS_MIME_FIELDCOOKIE
"Date"
const char *TS_MIME_FIELDDATE
int TS_MIME_LEN_DATE
"Distribution"
const char *TS_MIME_FIELDDISTRIBUTION
int TS_MIME_LEN_DISTRIBUTION
"Etag"
const char *TS_MIME_FIELDETAG
int TS_MIME_LEN_ETAG
"Expect"
const char *TS_MIME_FIELDEXPECT
int TS_MIME_LEN_EXPECT
"Expires"
const char *TS_MIME_FIELDEXPIRES
int TS_MIME_LEN_EXPIRES
"Followup-To"
const char *TS_MIME_FIELDFOLLOWUP_TO
int TS_MIME_LEN_FOLLOWUP_TO
"From"
const char *TS_MIME_FIELDFROM
int TS_MIME_LEN_FROM
"Host"
const char *TS_MIME_FIELDHOST
int TS_MIME_LEN_HOST
"If-Match"
const char *TS_MIME_FIELDIF_MATCH
int TS_MIME_LEN_IF_MATCH
"If-Modified-Since"
const char *TS_MIME_FIELDIF_MODIFIED_SINCE
int TS_MIME_LEN_IF_MODIFIED_SINCE
"If-None-Match"
const char *TS_MIME_FIELDIF_NONE_MATCH
int TS_MIME_LEN_IF_NONE_MATCH
"If-Range"
const char *TS_MIME_FIELDIF_RANGE
int TS_MIME_LEN_IF_RANGE
"If-Unmodified-Since"
const char *TS_MIME_FIELDIF_UNMODIFIED_SINCE
int TS_MIME_LEN_IF_UNMODIFIED_SINCE
"Keep-Alive"
const char *TS_MIME_FIELDKEEP_ALIVE
int TS_MIME_LEN_KEEP_ALIVE
"Keywords"
const char *TS_MIME_FIELDKEYWORDS
int TS_MIME_LEN_KEYWORDS
"Last-Modified"
const char *TS_MIME_FIELDLAST_MODIFIED
int TS_MIME_LEN_LAST_MODIFIED
"Lines"
const char *TS_MIME_FIELDLINES
int TS_MIME_LEN_LINES
"Location"
const char *TS_MIME_FIELDLOCATION
int TS_MIME_LEN_LOCATION
"Max-Forwards"
const char *TS_MIME_FIELDMAX_FORWARDS
int TS_MIME_LEN_MAX_FORWARDS
"Message-ID"
const char *TS_MIME_FIELDMESSAGE_ID
int TS_MIME_LEN_MESSAGE_ID
"Newsgroups"
const char *TS_MIME_FIELDNEWSGROUPS
int TS_MIME_LEN_NEWSGROUPS
"Organization"
const char *TS_MIME_FIELDORGANIZATION
int TS_MIME_LEN_ORGANIZATION
"Path"
const char *TS_MIME_FIELDPATH
int TS_MIME_LEN_PATH
"Pragma"
const char *TS_MIME_FIELDPRAGMA
int TS_MIME_LEN_PRAGMA
"Proxy-Authenticate"
const char *TS_MIME_FIELDPROXY_AUTHENTICATE
int TS_MIME_LEN_PROXY_AUTHENTICATE
"Proxy-Authorization"
const char *TS_MIME_FIELDPROXY_AUTHORIZATION
int TS_MIME_LEN_PROXY_AUTHORIZATION
"Proxy-Connection"
const char *TS_MIME_FIELDPROXY_CONNECTION
int TS_MIME_LEN_PROXY_CONNECTION
"Public"
const char *TS_MIME_FIELDPUBLIC
int TS_MIME_LEN_PUBLIC
"Range"
const char *TS_MIME_FIELDRANGE
int TS_MIME_LEN_RANGE
"References"
const char *TS_MIME_FIELDREFERENCES
int TS_MIME_LEN_REFERENCES
"Referer"
const char *TS_MIME_FIELDREFERER
int TS_MIME_LEN_REFERER
"Reply-To"
const char *TS_MIME_FIELDREPLY_TO
int TS_MIME_LEN_REPLY_TO
"Retry-After"
const char *TS_MIME_FIELDRETRY_AFTER
int TS_MIME_LEN_RETRY_AFTER
"Sender"
const char *TS_MIME_FIELDSENDER
int TS_MIME_LEN_SENDER
"Server"
const char *TS_MIME_FIELDSERVER
int TS_MIME_LEN_SERVER
"Set-Cookie"
"Subject"
const char *TS_MIME_FIELDSUBJECT
int TS_MIME_LEN_SUBJECTTS_MIME_LEN_SUBJECT
"Summary"
const char *TS_MIME_FIELDSUMMARY
int TS_MIME_LEN_SUMMARY
"TE"
const char *TS_MIME_FIELDTE
int TS_MIME_LEN_TE
"Transfer-Encoding"
const char *TS_MIME_FIELDTRANSFER_ENCODING
int TS_MIME_LEN_TRANSFER_ENCODING
"Upgrade"
const char *TS_MIME_FIELDUPGRADE
int TS_MIME_LEN_UPGRADE
"User-Agent"
const char *TS_MIME_FIELDUSER_AGENT
int TS_MIME_LEN_USER_AGENT
"Vary"
const char *TS_MIME_FIELDVARY
int TS_MIME_LEN_VARY
"Via"
const char *TS_MIME_FIELDVIA
int TS_MIME_LEN_VIA
"Warning"
const char *TS_MIME_FIELDWARNING
int TS_MIME_LEN_WARNING
"Www-Authenticate"
const char *TS_MIME_FIELDWWW_AUTHENTICATE
int TS_MIME_LEN_WWW_AUTHENTICATE
"Xref"
const char *TS_MIME_FIELDXREF
int TS_MIME_LEN_XREF

The header field names above are defined in ts.h as const char* strings. When Traffic Server sets the name portion of a header field (or any portion for that matter), it quickly checks to see if the new value is one of the known values. If it is, then Traffic Server 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 enables simple pointer comparison of the value returned from TSMimeHdrFieldNameGet with one of the values listed above. It is 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 to Traffic Server logs by defining a custom log configuration 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: