MIME headers and fields can be components of request headers,
response headers, or standalone headers created within your plugin.
Make sure you call the MIME header functions appropriately. For
example: if you want to clone a MIME header field within a request
header, then call INKMimeHdrFieldClone
after
READ_REQUEST_HDR_HOOK
.
The Traffic Server MIME header functions are described below.
Appends a field in a MIME header.
INKReturnCode INKMimeHdrFieldAppend (INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
)
Appends the MIME field located at field within the
marshal buffer
into the MIME header located at
bufp
within the
marshal buffer
url_loc
.bufp
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Copies a MIME field to a marshal buffer and returns the
INKMLoc
location of the copied field.
INKMLoc INKMimeHdrFieldClone (INKMBuffer
dest_bufp
, INKMLoc
dest_hdr
, INKMBuffer
src_bufp
, INKMLoc
src_hdr
, INKMLoc
src_field
)
Copies the contents of the MIME field located at
within the
marshal buffer
src_field
to a MIME
header located at
src_bufp
within the
marshal buffer
dest_hdr
.dest_bufp
The INKMLoc
location of the copied
field. Release the returned handle with a call to
INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Copies a MIME field from one specified location to another specified location.
INKReturnCode INKMimeHdrFieldCopy (INKMBuffer
dest_bufp
, INKMLoc
dest_hdr
, INKMLoc
dest_field
, INKMBuffer
src_bufp
, INKMLoc
src_hdr
, INKMLoc
src_field
)
Copies the contents of the MIME field located at
within the
marshal buffer
src_field
to the MIME
field located at
src_bufp
within the
marshal buffer
dest_field
.
dest_bufp
INKMimeHdrFieldCopy
works correctly even
if
and
src_bufp
point to
different marshal buffers.dest_bufp
Note | |
---|---|
You must first create the destination MIME field before you can copy into it. |
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Copies MIME field values from one location to another.
INKReturnCode INKMimeHdrFieldCopyValues
(INKMBuffer
dest_bufp
, INKMLoc
dest_hdr
, INKMLoc
dest_field
, INKMBuffer
src_bufp
, INKMLoc
src_hdr
, INKMLoc
src_field
)
Copies the values contained within the MIME field
located at
within the marshal buffer
src_field
to the MIME
field located at
src_bufp
within the
marshal buffer
dest_field
.
dest_bufp
INKMimeHdrFieldCopyValues
works correctly
even if
and
src_bufp
point to
different marshal buffers.
dest_bufp
INKMimeHdrFieldCopyValues
does not copy
the field’s name.
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Creates a new MIME field within a specified marshal buffer.
INKMLoc INKMimeHdrFieldCreate (INKMBuffer
bufp
, INKMLoc
hdr
)
Creates a new MIME field with the marshal buffer
.bufp
The location of the new MIME field. Release with a call
to INKHandleMLocRelease
.
Deletes a specified MIME field from a marshal buffer.
void INKMimeHdrFieldDestroy (INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
)
Destroys the MIME field located at
within the MIME
header located at field
within the marshal buffer
hdr
.bufp
After the call to
INKMimeHdrFieldDestroy
, you must release
the INKMLoc
handle
with a call to
field
INKHandleMLocRelease
.
Calculates the length of a string representation in a specified MIME field.
int INKMimeHdrFieldLengthGet (INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
)
Calculates the length of the MIME field located at
within the marshal buffer
field
if it was
returned as a string. This is the length of the MIME field in
its unparsed form.bufp
The calculated length of a string representation of the specified MIME field.
INK_ERROR
if there is an error.
Gets the name and name length of a specified MIME field.
const char* INKMimeHdrFieldNameGet (INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
, int
*length
)
Returns the name of the field located at
within the
marshal buffer field
.
bufp
INKMimeHdrFieldNameGet
places the length
of the returned string in the
argument.length
A pointer to the name of the specified field within the
specified MIME header. Release the returned string with a call
to INKHandleStringRelease
.
INK_ERROR_PTR
if an error occurs.
Note | |
---|---|
The returned string is not guaranteed to be null-terminated. |
Sets the name for a specified MIME field.
INKReturnCode INKMimeHdrFieldNameSet (INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
, const char
*name
, int
length
)
Sets the name of the field located at
within the
marshal buffer field
to
the string bufp
. If
name
is -1, then
length
INKMimeHdrFieldNameSet
assumes the name
is null-terminated. Otherwise, the length of the string
is taken to be
name
.
length
INKMimeHdrFieldNameSet
copies the string
to within
, so it
is okay to modify or delete
bufp
after calling
name
INKMimeHdrFieldNameSet
. When possible, use the INK_MIME_FIELD_XXX
tokens
for
. name
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Returns the next MIME field after a specified MIME field in a MIME header.
INKMLoc INKMimeHdrFieldNext (INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
)
Conceptually, MIME fields are listed in a MIME
header (see Guide to Traffic Server HTTP Header System).
INKMimeHdrFieldNext
returns the location
of the next
in
the list, after the field located at
field
within the
marshal buffer field
.
If the next field is not found, then a bufp
NULL
pointer is
returned.
The location of the MIME field following the specified
MIME field within the specified MIME header. Release the
returned INKMLoc
with a call to
INKHandleMLocRelease
(see the code
example below).
INK_ERROR_PTR
if an error occurs.
An example of a loop through each MIME field of an HTTP header is featured below:
field_loc = INKMimeHdrFieldGet (hdr_bufp, hdr_loc, 0); while (field_loc) { /* Temp variable used only for the loop */ INKMLoc next_field_loc; /* Do your job with the field here */ /* Get the next field and release the current one */ next_field_loc = INKMimeHdrFieldNext (hdr_bufp, hdr_loc, field_loc); INKHandleMLocRelease(hdr_bufp, hdr_loc, field_loc); field_loc = next_field_loc; }
Returns the next duplicate MIME field after a specified MIME field in a MIME header.
INKMLoc INKMimeHdrFieldNextDup (INKMBuffer bufp,
INKMLoc hdr, INKMLoc field)
MIME headers can 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.
Your plugins should check for the presence of duplicate
fields and iterate over duplicate fields via
INKMimeHdrFieldNextDup. INKMimeHdrFieldNextDup
returns the location of the next duplicate field in the list
after the field located at
within the
marshal buffer field
.
If the next field is not found, then a bufp
NULL
pointer is
returned.
The location of the next duplicate MIME field that
follows the specified field within the specified MIME header.
Release with a call to
INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Appends a string to a specified value in a MIME field.
INKReturnCode INKMimeHdrFieldValueAppend
(INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
, int
idx
, const char
*value
, int
length
)
is the
marshal buffer containing the MIME field.bufp
is the
location of the parent object within the marshal buffer
hdr
from which
bufp
was
retrieved.field
is the
location of the MIME field to be appended.field
is the index
of the field value to be appended. For example: in the MIME
field idx
Foo: bar
, car
the index of the value bar
is
0
and the index of car
is 1
.
is the
string that will be appended to the MIME field value
value
at
.idx
is the
length of the string length
value
to be appended.
Appends the string stored in
to a specific
value in the MIME field located at
value
within the
marshal buffer field
.
The effect of bufp
INKMimeHdrFieldValueAppend
is as if the previous value was retrieved, the string
was appended to
it, and this new string was stored back in the MIME field at
the same position. The
value
parameter
specifies which value in the field to append to. If
idx
is not between 0
and idx
INKMimeHdrFieldValuesCount
(
) - 1,
then no operation is performed.bufp, hdr, field
INK_SUCCESS
if the string is successfully
appended.
INK_ERROR
if the hook is not added.
Gets the date value from a MIME field.
INKReturnCode INKMimeHdrFieldValueDateGet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, time_t
*value
)
Retrieves a date
from within the
MIME field located at
value
within the
marshal buffer field
.
All values are stored as strings within the MIME field.
bufp
INKMimeHdrFieldValueDateGet
parses the
string
to return
an integer date representation.value
The date
from the specified MIME header.value
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Inserts a date value into a MIME field.
INKReturnCode INKMimeHdrFieldValueDateInsert
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, time_t
value
)
Inserts the date
into the MIME
field located at value
within the marshal buffer
field
. All values are
stored as strings within the MIME field.
bufp
INKMimeHdrFieldValueDateInsert
simply
formats the date into a string and then calls
INKMimeHdrFieldValueInsert
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Sets a date value in a MIME field.
INKReturnCode INKMimeHdrFieldValueDateSet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, time_t
value
)
Sets a value in the MIME field located at
within the
marshal buffer field
to
the date bufp
. All
values are stored as strings within the MIME field.
value
INKMimeHdrFieldValueDateSet
simply
formats the date into a string and then calls
INKMimeHdrFieldValueStringSet
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Deletes a specified value from a MIME field.
INKReturnCode INKMimeHdrFieldVcoalueDelete
(INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
, int
idx
)
Removes and deletes a value from the MIME field located
at
within the
marshal buffer field
.
The bufp
parameter
specifies which value should be deleted. If
idx
is not between 0
and idx
INKMimeHdrFieldValuesCount
(
) - 1,
then no operation is performed.bufp, hdr, field
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Gets an integer field value in a MIME field.
INKReturnCode INKMimeHdrFieldValueIntGet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, int
*value
)
Retrieves an integer value from within the MIME field
located at
within the marshal buffer
field
. The
bufp
parameter
specifies which value within the field to retrieve. The fields
are numbered from 0 to
idx
INKMimeHdrFieldValuesCount
(
) -
1. If bufp, hdr, field
does not lie
within that range, then idx
INKMimeHdrFieldValueIntGet
returns (int) 0
.
All values are stored as strings within the MIME field; INKMimeHdrFieldValueIntGet
parses the
string
to return
an integer.value
The integer value from the specified MIME field.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Inserts an integer value into a MIME field.
INKReturnCode INKMimeHdrFieldValueIntInsert
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
value
, int
idx
)
Inserts the integer
into the MIME
field located at value
within the marshal buffer
field
. The
bufp
parameter
specifies where the inserted value should be placed with respect
to the other values already in the MIME field. If
idx
is 0, then the
value is prepended to the list of values in the field.
Increasing values of
idx
places the value
farther down the list of values. If
idx
is -1, then the
idx
is appended to
the list of values. Normal usage is to specify -1 for
value
so that the value
is appended to the list of values. All values are stored as
strings within the MIME field.
idx
INKMimeHdrFieldValueIntInsert
simply
formats the integer into a string and then calls
INKMimeHdrFieldValueInsert
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Sets an integer value within a MIME field.
INKReturnCode INKMimeHdrFieldValueIntSet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, int
value
)
Sets a value in the MIME field located at
within the
marshal buffer field
.
The bufp
parameter
specifies which value in the field to change. If
idx
is not between 0
and idx
INKMimeHdrFieldValuesCount
(
) - 1, then no operation is
performed. All values are stored as strings within the MIME
field. bufp, hdr,
field
INKMimeHdrFieldValueIntSet
simply
formats the integer into a string and then calls
INKMimeHdrFieldValueSet
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while
calling the API or if an argument is invalid.
Gets a specified field value from a MIME header.
INKReturnCode INKMimeHdrFieldValueStringGet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, const char
**value
, int
*value_len
)
Retrieves a string
from within the
MIME value
within the
marshal buffer field
.
The bufp
parameter
specifies which field to retrieve. The fields are numbered
from 0 to idx
INKMimeHdrFieldValuesCount
(
) -
1. If bufp, hdr, field
does not lie
within that range, then idx
NULL
is returned. The
length of the returned string is placed in the
argument. If
value_len
is
value_len
NULL
, then no attempt is made to dereference
it.
A pointer to the specified field
in the MIME
header. Release with a call to
value
INKHandleStringRelease
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Inserts a value into a specified location within a MIME field.
INKReturnCode INKMimeHdrFieldValueStringInsert
(INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
, int
idx
, const char
*value
, int
length
)
Inserts the string
into the MIME
field located at value
within the marshal buffer
field
. If
bufp
is -1, then
len
INKMimeHdrFieldValueStringInsert
assumes
that
is
null-terminated. Otherwise, the length of the string
value
is taken to be
value
.
length
INKMimeHdrFieldValueStringInsert
copies
the string to within
, so it is okay to
modify or delete bufp
after calling
value
INKMimeHdrFieldValueStringSet
. The
parameter
specifies where the inserted value should be placed with respect
to the other values already in the MIME field. If
idx
is 0, then
idx
INKMimeHdrFieldValueStringInsert
prepends
the value to the list of values in the field. Increasing
values of
place
the value farther down the list of values. If
idx
is -1,
then idx
INKMimeHdrFieldValueStringInsert
appends
the value to the list of values. Normal usage is to specify -1
for idx
so that the value is appended to the list
of values.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Sets a value in a MIME field.
INKReturnCode INKMimeHdrFieldValueStringSet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, const char
*value
, int
len
)
Sets a value in the MIME field located at
within the
marshal buffer field
to
the string bufp
. If
value
is -1, then it is
assumed that len
is
null-terminated. Otherwise, the length of the string
value
is taken to be
value
. The string is
copied to within len
,
so it is okay to modify or delete
bufp
after calling
value
INKMimeHdrFieldValueStringSet
. The
parameter
specifies which value in the field to change. If
idx
is not between 0
and idx
INKMimeHdrFieldValuesCount
(
) - 1,
then no operation will be performed. If
bufp, hdr, field
is set to -1, then
all the MIME field values are returned. idx
Suppose
the MIME field is MyField: value1
,
value2
, value3
. If
INKMimeHdrFieldGet
is called with
set to -1, then it will
return a pointer to “idx
value1
, value2
,
value3
”.
Note | |
---|---|
As with other MIME header manipulation APIs, the string is not null-terminated. |
Gets an unsigned integer field value in a MIME field.
INKReturnCode INKMimeHdrFieldValueUintGet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, unsigned int
*value
)
Retrieves an unsigned integer
from within the
MIME field located at
value
within the
marshal buffer field
.
The bufp
parameter
specifies which field to retrieve. The fields are numbered
from 0 to idx
INKMimeHdrFieldValuesCount
(
) -
1. If bufp, hdr, field
does not lie
within that range, then
idx
INKMimeHdrFieldValueGetUnit
returns
(unsigned int) 0
. All values are stored as strings within the
MIME field. INKMimeHdrFieldValueUintGet
parses the string
to return an
unsigned integer.value
It is not possible to determine if
INKMimeHdrFieldValueUintGet
is returning
an unsigned int
value in error. If you need to check for
errors in MIME header field values, then you can fetch the header
as a string and examine it (see the example below).
The unsigned integer value
from the
specified MIME field.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
The example below contains sample code that fetches MIME headers from marshal buffers into strings using INKMimeHdrFieldValueGet
instead. The context of this example is that the plugin is processing an HTTP transaction and has access to a transaction.
static void handle_string (INKHttpTxn txnp, INKCont contp) { INKMBuffer bufp; INKMLoc hdr_loc; INKMLoc field; int len; char* output_string; const char* value; /* Fetch the transaction's client request header into a marshal buffer. */ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) { INKError ("couldn't retrieve client request header\n"); goto done; } field=INKMimeHdrFieldFind(bufp, hdr_loc, INK_MIME_FIELD_CONTENT_LENGTH); if (!field) { INKError ("Content-Length field not found.\n"); INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc); goto done; } /* Obtain the value of the content length (normally an * unsigned int) as a string. */ value=INKMimeHdrFieldValueGet (bufp, hdr_loc, field, 0, &len); if ((!value) || (len<=0))} INKHandleMLocRelease (bufp, hdr_loc, field); INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc); goto done; } /* Allocate the string with an extra byte for the string terminator. */ output_string = (char*) INKmalloc(len + 1); /* Copy the value. */ strncpy (output_string, value, len); /* Terminate the string */ output_string[len] = '\0'; /* Now that you have the MIME fields as a string, you can do whatever you want to do with it. For example: you can print it or make sure it's an unsigned integer, either by using the atol C function or by scanning each ASCII character. */ INKDebug("my-plugin", "%s", output_string); /* Release handles and allocated memory. */ INKHandleStringRelease (bufp, field, value);
Inserts an unsigned integer value into a MIME field.
INKReturnCode INKMimeHdrFieldValueUIntInsert
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, unsigned int
value
, int
idx
)
Inserts the unsigned integer
into the MIME
field located at value
within the marshal buffer
field
. The
bufp
parameter
specifies where the inserted value should be placed with respect
to other values already in the MIME field. Ifidx
is 0, then the value is prepended to the
list of values in the field. Increasing values of idx
simply places the
value farther down on the list of values. If
idx
is -1, then the
value is appended to the list of values. Normal usage is
to specify -1 for idx
so that the value will be appended to the existing list of values. All
values are stored as strings within the MIME field.
idx
INKMimeHdrFieldValueUIntInsert
simply
formats the unsigned integer into a string and then calls
INKMimeHdrFieldValueStringInsert
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Sets a value in a MIME field to a specified unsigned integer.
INKReturnCode INKMimeHdrFieldValueUintSet
(INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
, int
idx
, unsigned int
value
)
Sets a value in the MIME field located at
within the
marshal buffer field
to
the unsigned integer
bufp
. The
value
parameter
specifies which value in the field to change. If
idx
is not between 0
and idx
INKMimeHdrFieldValuesCount
(
) - 1,
then no operation is performed. All values are stored as
strings within the MIME field.
bufp, hdr, field
INKMimeHdrFieldValueUintSet
simply
formats the unsigned integer into a string and then calls
INKMimeHdrFieldValueStringSet
.
INK_SUCCESS
if the API is called
successfully.
INK_ERROR
if an error occurs while calling
the API or if an argument is invalid.
Clears all values in a MIME field.
INKReturnCode INKMimeHdrFieldValuesClear
(INKMBuffer
bufp
, INKMLoc
hdr
, INKMLoc
field
)
Removes and destroys all values within the MIME
field located at
within the marshal buffer
field
.bufp
Make sure you release any corresponding
INKMLoc
or string handles via
INKHandleMLocRelease
or
INKHandleStringRelease
.
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Counts the values in a MIME field.
int INKMimeHdrFieldValuesCount (INKMBuffer bufp,
INKMLoc hdr, INKMLoc field)
Retrieves a count of the number of values in the MIME
field located at
within the marshal buffer
field
.bufp
The number of values in the specified MIME field.
INK_ERROR
if an error occurs.
Copies a MIME header and returns the location of the copied header.
INKMLoc INKMimeHdrClone(INKMBuffer
dest_bufp
, INKMBuffer
src_bufp
, INKMLoc
src_hdr_loc
)
Copies the contents of the MIME header located at
within the
marshal buffer
src_hdr_loc
to the
marshal buffer
src_bufp
.dest_bufp
The INKMLoc
location of the copied
header. Release the returned handle with a call to
INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Copies a MIME header to a specified MIME header location.
INKReturnCode INKMimeHdrCopy (INKMBuffer
dest_bufp
, INKMLoc
dest_hdr_loc
, INKMBuffer
src_bufp
, INKMLoc
src_hdr_loc
)
Copies the contents of the MIME header located at
within the
marshal buffer
src_hdr_loc
to the MIME
header located at
src_bufp
within
the marshal buffer
dest_hdr_loc
.
dest_bufp
INKMimeHdrCopy
works correctly even if
and
src_bufp
point to
different marshal buffers.dest_bufp
Note | |
---|---|
Make sure the destination marshal buffer and destination MIME header location have been created before copying (see the example below). |
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
static void copyResponseMimeHdr (INKCont pCont, INKHttpTxn pTxn) { INKMBuffer respHdrBuf, tmpBuf; INKMLoc respHttpHdrLoc, tmpMimeHdrLoc; if ( !INKHttpTxnClientRespGet (pTxn, &respHdrBuf, &respHttpHdrLoc) ) { INKError ("couldn't retrieve client response header\n"); INKHandleMLocRelease (respHdrBuf, INK_NULL_MLOC, respHttpHdrLoc); goto done; } tmpBuf = INKMBufferCreate (); tmpMimeHdrLoc = INKMimeHdrCreate(tmpBuf); INKMimeHdrCopy(tmpBuf, tmpMimeHdrLoc, respHdrBuf, respHttpHdrLoc); INKHandleMLocRelease (tmpBuf, INK_NULL_MLOC, tmpMimeHdrLoc); INKHandleMLocRelease (respHdrBuf, INK_NULL_MLOC, respHttpHdrLoc); INKMBufferDestroy(tmpBuf); done: INKHttpTxnReenable(pTxn, INK_EVENT_HTTP_CONTINUE); }
Creates a MIME header.
INKMLoc INKMimeHdrCreate (INKMBuffer
bufp
)
Creates a new MIME header within the marshal buffer
.bufp
Location of the newly-created MIME header. Release with
a call to INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Destroys a MIME header.
INKReturnCode INKMimeHdrDestroy (INKMBuffer
bufp
, INKMLoc
hdr_loc
)
Destroys the MIME header located at
within the
marshal buffer
hdr_loc
.bufp
Release the INKMLoc
handle
with a call to
hdr_loc
INKHandleMLocRelease
.
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Finds specific fields in a MIME header.
INKMLoc INKMimeHdrFieldFind (INKMBuffer
bufp
, INKMLoc
loc
, const char*
name
, int
length
)
Retrieves a MIME field from within the MIME header
located at
within
the marshal buffer
loc
. The
bufp
and
name
parameters
specify which field to retrieve. For each MIME field in the
MIME header, a case-insensitive string comparison is done
between the field name and
length
. The
name
parameter
specifies the length of the string that
length
points to. If
name
is -1, then
length
is assumed to be
null-terminated. If the requested field cannot be found, then 0
is returned.name
The location of the retrieved MIME header. Release with
a call to INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Gets a field in a MIME header.
INKMLoc INKMimeHdrFieldGet (INKMBuffer
bufp
, INKMLoc
hdr_loc
, int
idx
)
Retrieves a MIME field from within the MIME header
located at
within the marshal buffer
hdr_loc
. The
bufp
parameter
specifies which field to retrieve. The fields are numbered
from 0 to idx
INKMimeHdrFieldsCount
(
) - 1.
If bufp, hdr_loc
does not lie
within that range, then 0 is returned.idx
The location of the MIME field from within the MIME
header. Release with a call to
INKHandleMLocRelease
.
INK_ERROR_PTR
if an error occurs.
Removes a field in a MIME header.
INKReturnCode INKMimeHdrFieldRemove (INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKMLoc
field
)
Removes the MIME header located at
within the
marshal buffer field
from the MIME header located at
bufp
within the
marshal buffer hdr_loc
.
If the specified field cannot be found in the list of fields
associated with the header, then nothing is done.bufp
After the call to
INKMimeHdrFieldDestroy
, you must release
the INKMLoc
handle field with a call to
INKHandleMLocRelease
.
Note | |
---|---|
Removing the MIME field doesn't destroy the field - it
only detaches it and hides it from the printed output.The
field can be reattached by calling
|
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Clears all the fields in a MIME header.
INKReturnCode INKMimeHdrFieldsClear (INKMBuffer
bufp
, INKMLoc
hdr_loc
)
Removes and destroys all MIME fields in the MIME
header located at
within the
marshal buffer
hdr_loc
.bufp
Make sure that you release any corresponding
INKMLoc
or string handles using
INKHandleMLocRelease
or
INKHandleStringRelease
.
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Counts the fields in a MIME header.
int INKMimeHdrFieldsCount (INKMBuffer
bufp
, INKMLoc
hdr_loc
)
Obtains a count of the number of MIME fields within the
MIME header located at
within the
marshal buffer
hdr_loc
.bufp
The number of fields within the specified MIME header.
INK_ERROR
if an error occurs.
Gets the length of a MIME header.
int INKMimeHdrLengthGet (INKMBuffer
bufp
, INKMLoc
hdr_loc
)
Calculates the length of the MIME header located at
within the
marshal buffer hdr_loc
if
it was returned as a string. This is the length of the MIME
header in its unparsed form.bufp
The length of the specified MIME header.
INK_ERROR
if an error occurs.
Parses a MIME header.
int INKMimeHdrParse (INKMimeParser
parser
, INKMBuffer
bufp
, INKMLoc
hdr_loc
, const char
**start
, const char
*end
)
Parses a MIME header. The MIME header must have already
been allocated, and both
and
bufp
must point
within that header. The
hdr_loc
argument points
to the current position of the buffer being parsed and the
start
argument points to
one byte after the end of the buffer. Upon return,
end
is modified to
point past the last character parsed. It is possible to parse
a MIME header a single byte at a time using repeated calls to
start
INKMimeHdrParse
. As long as an error does
not occur, the INKMimeHdrParse
function consumes that
single byte and asks for more.
INK_PARSE_ERROR
if an error occurs.
INK_PARSE_DONE
when a
\r\n\r\n
pattern is encountered, indicating the
end of the header.
INK_PARSE_CONT
if
parsing of the header stopped because the end of the buffer
was reached.
Clears a MIME header parser so it can be reused.
INKReturnCode INKMimeParserClear (INKMimeParser
parser
)
Clears the specified MIME
so it can be
used again.parser
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.
Creates a parser for MIME headers.
INKMimeParser INKMimeParserCreate
(void)
Creates a MIME parser. The parser’s data structure
contains information about the header being parsed. A single
MIME parser can be used multiple times, but not
simultaneously. Before being used again, the parser must be
cleared by calling INKMimeParserClear
.
A pointer to the newly-created MIME parser.
INK_ERROR_PTR
if an error occurs.
Destroys a MIME header parser.
INKReturnCode INKMimeParserDestroy (INKMimeParser
parser
)
Destroys the specified MIME
and frees the
associated memory.parser
INK_SUCCESS
if the parser is successfully
destroyed.
INK_ERROR
if an error occurs.
Prints a MIME header to an IO buffer.
INKReturnCode INKMimeHdrPrint (INKMBuffer
bufp
, INKMLoc
hdr_loc
, INKIOBuffer
iobufp
)
Formats the MIME header located at
within the
marshal buffer hdr_loc
into the IO buffer
bufp
. See IO Buffers for information about allocating an IO
buffer and retrieving data from within one.iobufp
INK_SUCCESS
if successful.
INK_ERROR
if an error occurs.