Traffic Server Software Developers Kit

void INKMimeFieldCopy (INKMBuffer dest_bufp, INKMLoc dest_offset, INKMBuffer src_bufp, INKMLoc src_offset)

Copies the contents of the MIME field located at src_offset within the marshal buffer src_bufp to the MIME field located at dest_offset within the marshal buffer dest_bufp. INKMimeFieldCopy works correctly even if src_bufp and dest_bufp point to different marshal buffers.

	Note
	You must first create the destination MIME field before you copy into it.

void INKMimeFieldCopyValues (INKMBuffer dest_bufp, INKMLoc dest_offset, INKMBuffer src_bufp, INKMLoc src_offset)

Copies the values contained within the MIME field located at src_offset within the marshal buffer src_bufp to the MIME field located at dest_offset within the marshal buffer dest_bufp. INKMimeFieldCopyValues works correctly even if src_bufp and dest_bufp point to different marshal buffers. INKMIMEFieldCopyValues does not copy the field’s name.

INKMLoc INKMimeFieldCreate (INKMBuffer bufp)

Creates a new MIME field with the marshal buffer bufp. Returns the offset location of the new MIME field.

Release the created INKMLoc with a call to INKHandleMLocRelease.

void INKMimeFieldDestroy (INKMBuffer bufp,INKMLoc offset)

Destroys the MIME field located at offset within the marshal buffer bufp.

Release the handle with a call to INKHandleMLocRelease.

int INKMimeFieldLengthGet (INKMBuffer bufp,INKMLoc offset)

Calculates the length of the MIME field located at offset within the marshal buffer bufp if it was returned as a string. This is the length of the MIME field in its unparsed form.

const char* INKMimeFieldNameGet (INKMBuffer bufp,INKMLoc offset, int *length)

Returns the name of the field located at offset within the marshal buffer bufp. INKMimeFieldNameGet places the length of the returned string in the length argument. If length is NULL then no attempt is made to de-reference it.

Release the returned string with a call to INKHandleStringRelease.

void INKMimeFieldNameSet (INKMBuffer bufp,INKMLoc offset, const char *name, int length)

Sets the name of the field located at offset within the marshal buffer bufp to the string name. If length is -1, then INKMimeFieldNameSet assumes that name is null-terminated. Otherwise, the length of the string name is taken to be length. INKMimeFieldNameSet copies the string to within bufp, so it is okay to modify or delete name after calling INKMimeFieldNameSet.

INKMLoc INKMimeFieldNext (INKMBuffer bufp,INKMLoc offset)

Conceptually, there are a list of MIME fields in a MIME header (see About HTTP Headers). INKMimeFieldNext returns the location of the next field in the list after the field located at offset within the marshal buffer bufp.

Release the returned INKMLoc with a call to INKHandleMLocRelease.

INKMLoc INKMimeFieldNext (INKMBuffer bufp,INKMLoc offset)

Conceptually, there are a list of MIME fields in a MIME header (see About HTTP Headers). INKMimeFieldNext returns the location of the next field in the list after the field located at offset within the marshal buffer bufp.

Release the returned INKMLoc with a call to INKHandleMLocRelease.

void INKMimeFieldValueDelete (INKMBuffer bufp,INKMLoc offset, int idx)

Removes and deletes a value from the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies which value should be deleted. If idx is not between 0 and INKMimeFieldValuesCount (bufp, offset) - 1, then no operation will be performed.

const char* INKMimeFieldValueGet (INKMBuffer bufp, INKMLoc offset, int idx, int *length)

Retrieves a string value from within the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeFieldValuesCount (bufp, offset) - 1. If idx does not lie within that range, then NULL will be returned. The length of the returned string is placed in the length argument. If length is NULL, then no attempt is made to dereference it.

Release the returned string with a call to INKHandleStringRelease.

time_t INKMimeFieldValueGetDate (INKMBuffer bufp, INKMLoc offset, int idx)

Retrieves a date value from within the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeFieldValuesCount (bufp, offset) - 1. If idx does not lie within that range, thrn INKMimeFieldValueGetDate returns (time_t) 0. All values are stored as strings within the MIME field. INKMimeFieldValueGetDate parses the string value to return an integer date representation.

int INKMimeFieldValueGetInt (INKMBuffer bufp, INKMLoc offset, int idx)

Retrieves an integer value from within the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies which value within the field to retrieve. The fields are numbered from 0 to INKMimeFieldValuesCount (bufp, offset) - 1. If idx does not lie within that range, then INKMimeFieldValueGetInt returns (int) 0. All values are stored as strings within the MIME field. INKMimeFieldValueGetInt parses the string value to return an integer.

unsigned int INKMimeFieldValueGetUint (INKMBuffer bufp, INKMLoc offset, int idx)

Retrieves an unsigned integer value from within the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeFieldValuesCount (bufp, offset) - 1. If idx does not lie within that range, then INKMimeFieldValueGetUnit returns (unsigned int) 0. All values are stored as strings within the MIME field. INKMimeFieldValueGetUint parses the string value to return an unsigned integer.

INKMLoc INKMimeFieldValueInsertDate (INKMBuffer bufp,INKMLoc offset, time_t value, int idx)

Inserts the date value into the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put 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 further down 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 is appended to the list of values. All values are stored as strings within the MIME field. INKMimeFieldValueInsertDate simply formats the date into a string and then calls INKMimeFieldValueInsert.

Release the returned INKMLoc with a call to INKHandleMLocRelease.

INKMLoc INKMimeFieldValueInsertInt (INKMBuffer bufp,INKMLoc offset, int value, int idx)

Inserts the integer value into the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put 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 further down 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 is appended to the list of values. All values are stored as strings within the MIME field. INKMimeFieldValueInsertInt simply formats the integer into a string and then calls INKMimeFieldValueInsert.

Release the returned INKMLoc with a call to INKHandleMLocRelease.

INKMLoc INKMimeFieldValueInsertUint (INKMBuffer bufp,INKMLoc offset, unsigned int value, int idx)

Inserts the unsigned integer value into the MIME field located at offset within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put with respect to the other values already in the MIME field. If idx is 0, then the value will be prepended to the list of values in the field. Increasing values of idx will place the value further down the list of values. If idx is -1, then the value will be appended to the list of values. Normal usage is to specify -1 for idx so that the value will be appended to the list of values. All values are stored as strings within the MIME field. INKMimeFieldValueInsertUint simply formats the unsigned integer into a string and then calls INKMimeFieldValueInsert.

Release the returned INKMLoc with a call to INKHandleMLocRelease.

void INKMimeFieldValuesClear (INKMBuffer bufp, INKMLoc offset)

Removes and destroys all of the values within the MIME field located at offset within the marshal buffer bufp.

int INKMimeFieldValuesCount (INKMBuffer bufp, INKMLoc offset)

Returns a count of the number of values in the MIME field located at offset within the marshal buffer bufp.

void INKMimeFieldValueSet (INKMBuffer bufp, INKMLoc offset, int idx, const char *value, int length)

Sets a value in the MIME field located at offset within the marshal buffer bufp to the string value. If length is -1, then it is assumed that value is null-terminated. Otherwise, the length of the string value is taken to be length. The string is copied to within bufp, so it is okay to modify or delete value after calling INKMimeFieldValueSet. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeFieldValuesCount (bufp, offset) - 1, then no operation will be performed.

void INKMimeFieldValueSetDate (INKMBuffer bufp,INKMLoc offset, int idx, time_t value)

Sets a value in the MIME field located at offset within the marshal buffer bufp to the data value. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeFieldValuesCount (bufp, offset) - 1 then no operation will be performed. All values are stored as strings within the MIME field. INKMimeFieldValueSetDate simply formats the date into a string and then calls INKMimeFieldValueSet.

Traffic Server 3.0

void INKMimeFieldValueSetInt (INKMBuffer bufp,INKMLoc offset, int idx, int value)

Sets a value in the MIME field located at offset within the marshal buffer bufp to the integer value. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeFieldValuesCount (bufp, offset) - 1, then no operation will be performed. All values are stored as strings within the MIME field. INKMimeFieldValueSetInt simply formats the integer into a string and then calls INKMimeFieldValueSet.

void INKMimeFieldValueSetUint (INKMBuffer bufp,INKMLoc offset, int idx, unsigned int value)

Sets a value in the MIME field located at offset within the marshal buffer bufp to the unsigned integer value. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeFieldValuesCount (bufp, offset) - 1, then no operation will be performed. All values are stored as strings within the MIME field. INKMimeFieldValueSetUint simply formats the unsigned integer into a string and then calls INKMimeFieldValueSet.

const char* INKMimeHdrFieldValueGet (INKMBuffer bufp, INKMLoc hdr_loc, INKMLoc field, int idx, int *value_len_ptr)

Retrieves a string value from within the MIME field located at field within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1. If idx does not lie within that range then NULL will be returned. The length of the returned string is placed in the value_len_ptr argument. If value_len_ptr is NULL, then no attempt is made to dereference it.

This API has been deprecated by INKMimeHdrFieldValueStringGet.

A pointer to the specified field value in the MIME header. Release with a call to INKHandleStringRelease.

time_t INKMimeHdrFieldValueGetDate (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx)

Retrieves a date value from within the MIME field located at field within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeHdrFieldValuesCount (bufp, hdr, field) -1. If idx does not lie within that range, then INKMimeHdrFieldValueGetDate returns (time_t) 0. All values are stored as strings within the MIME field. INKMimeHdrFieldValueGetDate parses the string value to return an integer date representation.

This API has been deprecated by INKMimeHdrFieldValueDateGet.

The date value from the specified MIME header.

int INKMimeHdrFieldValueGetInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx, int *value_len-ptr)

Retrieves an integer value from within the MIME field located at field within the marshal buffer bufp. The idx parameter specifies which value within the field to retrieve. The fields are numbered from 0 to INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1. If idx does not lie within that range, then INKMimeHdrFieldValueGetInt returns (int) 0. All values are stored as strings within the MIME field. INKMimeHdrFieldValueGetInt parses the string value to return an integer.

This API has been deprecated by INKMimeHdrFieldValueIntGet.

The interger value from the specified MIME field.

unsigned int INKMimeHdrFieldValueGetUInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx)

Retrieves an unsigned integer value from within the MIME field located at field within the marshal buffer bufp. The idx parameter specifies which field to retrieve. The fields are numbered from 0 to INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1. If idx does not lie within that range, then INKMimeHdrFieldValueGetUnit returns (unsigned int) 0. All values are stored as strings within the MIME field. INKMimeHdrFieldValueGetUInt parses the string value to return an unsigned integer.

It is not possible to determine if INKMimeHdrFieldValueGetUInt is returning an unsigned int value in error. If you need to check for errors in MIME header field values, you can fetch the header as a string and examine it. Here is some 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.

This API has been deprecated by INKMimeHdrFieldValueUIntGet.

The unsigned integer value from the specified MIME field.

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=INKMimeHdrFieldRetrieve(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, 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);

INKMLoc INKMimeHdrFieldValueInsert (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, const char *value, int length, int idx)

Inserts the string value into the MIME field located at field within the marshal buffer bufp. If length is -1, then INKMimeHdrFieldValueInsert assumes that value is null-terminated. Otherwise, the length of the string value is taken to be length. INKMimeHdrFieldValueInsert copies the string to within bufp, so it is okay to modify or delete value after calling INKMimeHdrFieldValueSet. The idx parameter specifies where the inserted value should be put with respect to the other values already in the MIME field. If idx is 0, then INKMimeHdrFieldValueInsert prepends the value to the list of values in the field. Increasing values of idx place the value further down the list of values. If idx is -1, then INKMimeHdrFieldValueInsert 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.

This API has been deprecated by INKMimeHdrFieldValueStringInsert.

INKMLoc INKMimeHdrFieldValueInsertDate (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, time_t value, int idx)

Inserts the data value into the MIME field located at field within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put 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 further down 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 is appended to the list of values. All values are stored as strings within the MIME field. INKMimeHdrFieldValueInsertDate simply formats the date into a string and then calls INKMimeHdrFieldValueInsert.

	Note
	Do not use the return value (INKMLoc) of this function. Future versions will be changed to void.

This API has been deprecated by INKMimeHdrFieldValueDateInsert.

INKMLoc INKMimeHdrFieldValueInsertInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int value, int idx)

Inserts the integer value into the MIME field located at field within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put 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 further down 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 is appended to the list of values. All values are stored as strings within the MIME field. INKMimeHdrFieldValueInsertInt simply formats the integer into a string and then calls INKMimeHdrFieldValueInsert.

This API has been deprecated by INKMimeHdrFieldValueIntInsert.

INKMLoc INKMimeHdrFieldValueInsertUInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, unsigned int value, int idx)

Inserts the unsigned integer value into the MIME field located at field within the marshal buffer bufp. The idx parameter specifies where the inserted value should be put with respect to the other values already in the MIME field. If idx is 0 then the value will be prepended to the list of values in the field. Increasing values of idx will place the value further down the list of values. If idx is -1, then the value will be appended to the list of values. Normal usage is to specify -1 for idx so that the value will be appended to the list of values. All values are stored as strings within the MIME field. INKMimeHdrFieldValueInsertUInt simply formats the unsigned integer into a string and then calls INKMimeHdrFieldValueInsert.

This API has been deprecated by INKMimeHdrFieldValueUIntInsert.

void INKMimeHdrFieldValueSet (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx, const char *value, int length)

Sets a value in the MIME field located at field within the marshal buffer bufp to the string value. If length is -1, then it is assumed that value is null-terminated. Otherwise, the length of the string value is taken to be length. The string is copied to within bufp, so it is okay to modify or delete value after calling INKMimeHdrFieldValueSet. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1, then no operation will be performed.

This API has been deprecated by INKMimeHdrFieldValueStringSet.

void INKMimeHdrFieldValueSetDate (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx, time_t value)

Sets a value in the MIME field located at field within the marshal buffer bufp to the date value. The idx parameter specifies which value in the field to change. If the idx is not between 0 and INKMimeHdrFieldValuesCount (bufp, hdr, field) -1, then no operation will be performed. All values are stored as strings within the MIME field. INKMimeHdrFieldValueSetDate simply formats the date into a string and then calls INKMimeHdrFieldValueSet.

void INKMimeHdrFieldValueSetInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx, int value)

Sets a value in the MIME field located at field within the marshal buffer bufp to the integer value. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1, then no operation will be performed. All values are stored as strings within the MIME field. INKMimeHdrFieldValueSetInt simply formats the integer into a string and then calls INKMimeHdrFieldValueSet.

This API has been deprecated by INKMimeHdrFieldValueIntSet.

void INKMimeHdrFieldValueSetUInt (INKMBuffer bufp, INKMLoc hdr, INKMLoc field, int idx, unsigned int value)

Sets a value in the MIME field located at field within the marshal buffer bufp to the unsigned integer value. The idx parameter specifies which value in the field to change. If idx is not between 0 and INKMimeHdrFieldValuesCount (bufp, hdr, field) - 1, then no operation will be performed. All values are stored as strings within the MIME field. INKMimeHdrFieldValueSetUInt simply formats the unsigned integer into a string and then calls INKMimeHdrFieldValueSet.

This API has been deprecated by INKMimeHdrFieldValueUIntSet.

void INKMimeHdrFieldDelete (INKMBuffer bufp, INKMLoc hdr_loc, INKMLoc field)

Deletes the MIME field located at field within the MIME header located at hdr_loc in the marshal buffer bufp.

Make sure you release the INKMLoc handle field with a call to INKHandleMLocRelease.

This API has been deprecated by INKMimeHdrFieldDestroy.

void INKMimeHdrFieldInsert (INKMBuffer bufp, INKMLoc hdr_loc, INKMLoc field, int idx)

Appends the MIME field located at field within the marshal buffer bufp into the MIME header located at hdr_loc within the marshal buffer bufp. The idx parameter specifies where the inserted field should be put with respect to the other fields already in the MIME header.

This API has been deprecated by INKMimeHdrFieldAppend

INKMLoc INKMimeHdrFieldRetrieve (INKMBuffer bufp, INKMLoc hdr_loc, const char* *retrieved_str)

Retrieves a MIME field from within the MIME header located at hdr_loc within the marshal buffer bufp. The retrieved_str parameter specifies which field to retrieve. For each MIME field in the MIME header, a pointer comparison is done between the field name and retrieved_str. This is a much quicker retrieval function than INKMimeHdrFieldFind, since it obviates the need for a string comparision. However, retrieved_str must be one of the predefined field names listed above (of the form INK_MIME_FIELD_XXX) in order for the call to succeed. If the requested field cannot be found, then 0 is returned.

Release with a call to INKHandleMLocRelease.

This API has been deprecated by INKMimeHdrFieldFind.