Traffic Server HTTP Header System¶
No Null-Terminated Strings¶
It’s not safe to assume that string data contained in marshal buffers
(such as URLs and MIME fields) is stored in null-terminated string
copies. Therefore, your plugins should always use the length parameter
when retrieving or manipulating these strings. You cannot pass in
NULL
for string-length return values; string values returned from
marshall buffers are not null-terminated. If you need a null-terminated
value, then use TSstrndup
to automatically null-terminate a string.
The strings that come back and are not null-terminated cannot be
passed into the common str*()
routines
Note
Values returned from a marshall buffer can be NULL
, which means the
field or object requested does not exist.
For example (from the blacklist-1
sample)
char *host_string;
int host_length;
host_string = TSUrlHostGet (bufp, url_loc, &host_length);
for (i = 0; i < nsites; i++) {
if (strncmp (host_string, sites[i], host_length) == 0) {
// ...
}
See the sample plugins for additional examples.
Duplicate MIME Fields Are Not Coalesced¶
MIME headers can contain more than one MIME field with the same name. Earlier versions of Traffic Server joined multiple fields with the same name into one field with composite values. This behavior came at a performance cost and caused interoperability problems with older clients and servers. Therefore, this version of Traffic Server does not coalesce duplicate fields.
Properly-behaving plugins should check for the presence of duplicate
fields and then iterate over the duplicate fields via
TSMimeHdrFieldNextDup()
.
MIME Fields Always Belong to an Associated MIME Header¶
When using Traffic Server, you cannot create a new MIME field without an associated MIME header or HTTP header; MIME fields are always seen as part of a MIME header or HTTP header.
To use a MIME field, you must specify the MIME header or HTTP header to
which it belongs - this is called the field’s parent header. The
TSMimeField*
functions in older versions of the SDK have been
deprecated, as they do not require the parent header as inputs. The
current version of Traffic Server uses new functions, the
``TSMimeHdrField`` series, which require you to specify the location
of the parent header along with the location of the MIME field. For
every deprecated ``TSMimeField`` function, there is a new, preferred
TSMimeHdrField*
function. Therefore, you should use the
``TSMimeHdrField`` functions instead of the deprecated
``TSMimeField`` series. Examples are provided below.
Instead of:
TSMLoc TSMimeFieldCreate (TSMBuffer bufp)
You should use:
TSMLoc TSMimeHdrFieldCreate (TSMBuffer bufp, TSMLoc hdr)
Instead of:
void TSMimeFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_offset,
TSMBuffer src_bufp, TSMLoc src_offset)
You should use:
void TSMimeHdrFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_hdr,
TSMLoc dest_field, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc
src_field)
In the TSMimeHdrField*
function prototypes, the TSMLoc
field
corresponds to the TSMLoc
offset used the deprecated
TSMimeField*
functions (see the discussion of parent TSMLoc
in
the following section).
Release Marshal Buffer Handles¶
When you fetch a component object or create a new object, you get back a
handle to the object location. The handle is either an TSMLoc
for an
object location or char *
for a string location. You can manipulate
the object through these handles, but when you are finished you need to
release the handle to free up system resources.
The general guideline is to release all TSMLoc
and string handles
you retrieve. The one exception is the string returned by
TSUrlStringGet
, which must be freed by a call to TSfree
.
The handle release functions expect three arguments: the marshal buffer
containing the data, the location of the parent object, and the location
of the object to be released. The parent location is usually clear from
the creation of the TSMLoc
or string. For example, if your plugin
had the following calls:
url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
host_string = TSUrlHostGet (bufp, url_loc, &host_length);
then your plugin would have to call:
TSHandleMLocRelease (bufp, hdr_loc, url_loc);
If an TSMLoc
is obtained from a transaction, then it does not have a
parent TSMLoc
. Use the null TSMLoc
constant TS_NULL_MLOC
as
its parent. For example, if your plugin calls:
TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc);
then you must release hdr_loc
with:
TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
You need to use TS_NULL_MLOC
to release any TSMLoc
handles
retrieved by the TSHttpTxn*Get
functions.
Here’s an example using a new TSMimeHdrField
function:
TSHttpTxnServerRespGet( txnp, &resp_bufp, &resp_hdr_loc );
new_field_loc = TSMimeHdrFieldCreate (resp_bufp, resp_hdr_loc);
TSHandleMLocRelease ( resp_bufp, resp_hdr_loc, new_field_loc);
TSHandleMLocRelease ( resp_bufp, TS_NULL_MLOC, resp_hdr_loc);
See the sample plugins for many more examples.
Tip
You should release handles before reenabling the HTTP transaction.
In other words, call TSHandleMLocRelease
before TSHttpTxnReenable
.