Traffic Server Software Developers Kit

INKMLoc INKHttpHdrClone (INKMBuffer dest_bufp, INKMBuffer src_bufp, INKMLoc src_hdr)

Copies the contents of the HTTP header located at src_hdr within the marshal buffer src_bufp to the marshal buffer located at dest_bufp. If the HTTP header located at the src_hdr is an HTTP request header, then make sure that it has a valid method, url, protocol, and version. If the HTTP header located at the src_hdr is a HTTP response header, then make sure that it has a valid protocol, version, status, and reason.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

Release the returned handle with a call to INKHandleMLocRelease.

Returns the INKMLoc location of the copied header.

INK_ERROR_PTR if an error occurs.

INKReturnCode INKHttpHdrCopy (INKMBuffer dest_bufp, INKMLoc dest_hdr_loc, INKMBuffer src_bufp, INKMLoc src_hdr_loc)

Copies the contents of the HTTP header located at src_hdr_loc within the marshal buffer src_bufp to the HTTP header located at dest_hdr_loc within the marshal buffer dest_bufp. INKHttpHdrCopy works correctly even if src_bufp and dest_bufp point to different marshal buffers. Make sure that the destination HTTP header exists (has been created) before copying into it. INKHttpHdrCopy automatically makes sure the types for the source and destination HTTP headers match; if the destination type is not equal to the source type, then INKHttpHdrCopy calls INKHttpHdrTypeSet. Do not call INKHttpHdrTypeSet on the destination header after using INKHttpHdrCopy.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

	Note
	INKHttpHdrCopy appends the port number to the domain of the URL portion of the header. For example, http://www.dianes-goanaut.com appears as http://www.dianes-goanaut.com:80/ in the destination buffer.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

INKMLoc INKHttpHdrCreate (INKMBuffer bufp)

Creates a new HTTP header with the marshal buffer bufp. When newly-created, the HTTP header is assigned an INKHttpType value of INK_HTTP_TYPE_UNKNOWN. You can change the type after creating the header using INKHttpHdrTypeSet, but you can only change the type once. You cannot modify the type after setting it.

Release with a call to INKHandleMLocRelease.

A pointer to the new HTTP header.

INKReturnCode INKHttpHdrDestroy (INKMBuffer bufp, INKMLoc hdr_loc)

Destroys the HTTP header located at hdr_loc within the marshal buffer bufp.

	Caution
	Do not forget to use INKHandleMLocRelease to release the handle hdr_loc.

INK_SUCCESS if the operation completes successfully.

INK_ERROR_PTR if an error occurs.

int INKHttpHdrLengthGet (INKMBuffer bufp, INKMLoc hdr_loc)

Calculates the length of the HTTP header located at hdr_loc within the marshal buffer bufp if it was returned as a string. This is the length of the HTTP header in its unparsed form and is also the number of bytes that will be added to the IO buffer by a call to INKHttpHdrPrint.

The header could be a request header, response header, or a standalone header that you have created. Be sure to call this function appropriately. For example: if you want the length of a request header, then call this function after READ_REQUEST_HDR_HOOK.

The length of the specified HTTP header.

INK_ERROR if an error occurs.

const char* INKHttpHdrMethodGet (INKMBuffer bufp, INKMLoc hdr_loc, int *length)

Retrieves the method from the HTTP header located at hdr_loc within the marshal buffer bufp. The length of the returned string is placed in the length argument. If length is NULL, then no attempt is made to dereference it.

It is an error to try to retrieve the method from an HTTP header that is not of type INK_HTTP_TYPE_REQUEST.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

Release with a call to INKHandleStringRelease.

A pointer to the method portion of the specified HTTP request header.

INK_ERROR_PTR if an error occurs.

INKReturnCode INKHttpHdrMethodSet (INKMBuffer bufp, INKMLoc hdr_loc, const char *value, int length)

Sets the method in the HTTP header located at hdr_loc within the marshal buffer bufp. If length is -1, then it is assumed the 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 INKHttpHdrMethodSet. It is an error to try to set the method in an HTTP header that is not of type INK_HTTP_TYPE_REQUEST.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

INKReturnCode INKHttpHdrPrint (INKMBuffer bufp, INKMLoc hdr_loc, INKIOBuffer iobufp)

Formats the HTTP header located at hdr_loc within the marshal buffer bufp into the IO buffer iobufp. See IO buffers for information about allocating an IO buffer and retrieving data from within one.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

const char* INKHttpHdrReasonGet (INKMBuffer bufp, INKMLoc hdr_loc, int *length)

Retrieves the reason phrase from the HTTP header located at hdr_loc within the marshal buffer bufp. The length of the returned string is placed in the length argument. It is an error to try to retrieve the reason phrase from an HTTP header that is not of type INK_HTTP_TYPE_RESPONSE.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

	Note
	The returned string is not guaranteed to be null-terminated.

Release with a call to INKHandleStringRelease.

Pointer to the reason phrase in the specified HTTP header.

INK_ERROR_PTR if an error occurs.

const char* INKHttpHdrReasonLookup (INKHttpStatus status)

Returns the default reason phrase for the status code status.

INKHttpHdrReasonLookup returns a string that is null-terminated. It should not be freed or released; it's a global shared value.

Pointer to the default reason phrase for the specified Traffic Server status code.

INK_ERROR_PTR if an error occurs.

INKReturnCode INKHttpHdrReasonSet (INKMBuffer bufp, INKMLoc hdr_loc, const char *value, int length)

Sets the reason phrase in the HTTP header located at hdr_loc within the marshal buffer bufp. 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 INKHttpHdrReasonSet. It is an error to try to set the reason phrase in an HTTP header that is not of type INK_HTTP_TYPE_RESPONSE.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if the operation does not complete successfully.

INKHttpStatus INKHttpHdrStatusGet (INKMBuffer bufp, INKMLoc hdr_loc)

Retrieves the status code from the HTTP header located at hdr_loc within the marshal buffer bufp. It is an error to try and retrieve the status code from an HTTP header that is not of type INK_HTTP_TYPE_RESPONSE. INKHttpStatus is an enumerated type.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

The status code from the specified HTTP header.

INK_ERROR if an error occurs.

Values of INKHttpStatus are the following:

typedef enum
{
    INK_HTTP_STATUS_NONE                          = 0,

    INK_HTTP_STATUS_CONTINUE                      = 100,
    INK_HTTP_STATUS_SWITCHING_PROTOCOL            = 101,

    INK_HTTP_STATUS_OK                            = 200,
    INK_HTTP_STATUS_CREATED                       = 201,
    INK_HTTP_STATUS_ACCEPTED                      = 202,
    INK_HTTP_STATUS_NON_AUTHORITATIVE_INFORMATION = 203,
    INK_HTTP_STATUS_NO_CONTENT                    = 204,
    INK_HTTP_STATUS_RESET_CONTENT                 = 205,
    INK_HTTP_STATUS_PARTIAL_CONTENT               = 206,

    INK_HTTP_STATUS_MULTIPLE_CHOICES              = 300,
    INK_HTTP_STATUS_MOVED_PERMANENTLY             = 301,
    INK_HTTP_STATUS_MOVED_TEMPORARILY             = 302,
    INK_HTTP_STATUS_SEE_OTHER                     = 303,
    INK_HTTP_STATUS_NOT_MODIFIED                  = 304,
    INK_HTTP_STATUS_USE_PROXY                     = 305,

    INK_HTTP_STATUS_BAD_REQUEST                   = 400,
    INK_HTTP_STATUS_UNAUTHORIZED                  = 401,
    INK_HTTP_STATUS_PAYMENT_REQUIRED              = 402,
    INK_HTTP_STATUS_FORBIDDEN                     = 403,
    INK_HTTP_STATUS_NOT_FOUND                     = 404,
    INK_HTTP_STATUS_METHOD_NOT_ALLOWED            = 405,
    INK_HTTP_STATUS_NOT_ACCEPTABLE                = 406,
    INK_HTTP_STATUS_PROXY_AUTHENTICATION_REQUIRED = 407,
    INK_HTTP_STATUS_REQUEST_TIMEOUT               = 408,
    INK_HTTP_STATUS_CONFLICT                      = 409,
    INK_HTTP_STATUS_GONE                          = 410,
    INK_HTTP_STATUS_LENGTH_REQUIRED               = 411,
    INK_HTTP_STATUS_PRECONDITION_FAILED           = 412,
    INK_HTTP_STATUS_REQUEST_ENTITY_TOO_LARGE      = 413,
    INK_HTTP_STATUS_REQUEST_URI_TOO_LONG          = 414,
    INK_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE        = 415,

    INK_HTTP_STATUS_INTERNAL_SERVER_ERROR         = 500,
    INK_HTTP_STATUS_NOT_IMPLEMENTED               = 501,
    INK_HTTP_STATUS_BAD_GATEWAY                   = 502,
    INK_HTTP_STATUS_SERVICE_UNAVAILABLE           = 503,
    INK_HTTP_STATUS_GATEWAY_TIMEOUT               = 504,
    INK_HTTP_STATUS_HTTPVER_NOT_SUPPORTED         = 505
} INKHttpStatus;

INKReturnCode INKHttpHdrStatusSet (INKMBuffer bufp, INKMLoc hdr_loc, INKHttpStatus status)

Sets the status code in the HTTP header located at hdr_loc within the marshal buffer bufp. It is an error to try and set the status code in an HTTP header that is not of type INK_HTTP_TYPE_RESPONSE.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

INKHttpType INKHttpHdrTypeGet (INKMBuffer bufp, INKMLoc hdr_loc)

Retrieves the type of the HTTP header located at hdr_loc within the marshal buffer bufp. INKHttpType is an enumerated type.

typedef enum
{
    INK_HTTP_TYPE_UNKNOWN,
    INK_HTTP_TYPE_REQUEST,
    INK_HTTP_TYPE_RESPONSE
} INKHttpTyp

The type of the specified HTTP header.

INK_ERROR if there is error.

INKReturnCode INKHttpHdrTypeSet (INKMBuffer bufp, INKMLoc hdr_loc, INKHttpType type)

Sets the type of the HTTP header located at hdr_loc within the marshal buffer bufp to type. Use INKHttpHdrTypeSet only after you create an HTTP header. The INKHttpHdrCreate function automatically assigns the new header a type of INK_HTTP_TYPE_UNKNOWN. You would only use INKHttpHdrTypeSet to change the type of a header from INK_HTTP_TYPE_UNKNOWN to either INK_HTTP_TYPE_REQUEST or INK_HTTP_TYPE_RESPONSE. You can only change the type once and you cannot modify the type after setting it.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

INKMLoc INKHttpHdrUrlGet (INKMBuffer bufp, INKMLoc req_hdr_loc)

Retrieves the URL from the HTTP header located at req_hdr_loc within the marshal buffer bufp. It is an error to try to retrieve the URL from an HTTP header that is not of type INK_HTTP_TYPE_REQUEST.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

Release with a call to INKHandleMLocRelease. When you release the handle created by INKHttpHdrUrlGet, the parent should be req_hdr_loc.

The URL from the specified HTTP header.

INK_ERROR_PTR if there is an error.

INKReturnCode INKHttpHdrUrlSet (INKMBuffer bufp, INKMLoc hdr_loc, INKMLoc url)

Sets the URL in the HTTP header located at hdr_loc within the marshal buffer bufp. It is an error to try to set the URL in an HTTP header that is not of type INK_HTTP_TYPE_REQUEST.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

int INKHttpHdrVersionGet (INKMBuffer bufp, INKMLoc hdr_loc)

Retrieves the version from the HTTP header located at hdr_loc within the marshal buffer bufp. An HTTP version is composed of a major and a minor version. Traffic Server encodes the major version in the upper 16 bits of the returned integer and the minor version in the lower 16 bits. The macros INK_HTTP_MAJOR (ver) and INK_HTTP_MINOR (ver) can be used to extract the major and minor versions, respectively.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

The HTTP version from the specified HTTP header.

INK_ERROR if there is an error.

INKReturnCode INKHttpHdrVersionSet (INKMBuffer bufp, INKMLoc hdr_loc, int ver)

Sets the version in the HTTP header located at hdr_loc within the marshal buffer bufp to ver. An HTTP version is composed of a major and a minor version. Traffic Server encodes the major version in the upper 16 bits of the returned integer and the minor version in the lower 16 bits. The macro INK_HTTP_VERSION (maj, min) can be used to encode a major and minor version into the single integer expected by INKHttpHdrVersionSet.

If it is a transaction header, then call after READ_REQUEST_HDR_HOOK.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if the operation does not complete successfully.

INKReturnCode INKHttpParserClear (INKHttpParser parser)

Clears the specified HTTP parser so it can be used again.

Call after READ_REQUEST_HDR_HOOK if it is a transaction header.

INK_SUCCESS if successful.

INK_ERROR if an error occurs.

INKHttpParser INKHttpParserCreate (void)

Creates an HTTP parser. The parser’s data structure contains information about the header being parsed. A single HTTP parser can be used multiple times, though not simultaneously. Before being used again, the parser must be cleared by calling INKHttpParserClear.

Parser structure for HTTP headers.

INK_ERROR_PTR if an error occurs.

INKReturnCode INKHttpParserDestroy (INKHttpParser parser)

Destroys the specified HTTP parser and frees the associated memory.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if the operation does not complete successfully.

int INKHttpHdrParseReq (INKHttpParser parser, INKMBuffer bufp, INKMLoc hdr_loc, const char **start, const char *end)

Parses an HTTP request header. The HTTP header hdr_loc must already be created and must reside inside the marshal buffer bufp. The start argument points to the current position of the string buffer being parsed and the end argument points to one byte after the end of the buffer to be parsed. On return, start is modified to point past the last character parsed.

It is possible to parse an HTTP request header a single byte at a time using repeated calls to INKHttpHdrParseReq. As long as an error does not occur, the INKHttpHdrParseReq function will consume that single byte and ask for more.

Call after READ_REQUEST_HDR_HOOK if it is a transaction header.

INK_PARSE_ERROR is returned if there is an error.

INK_PARSE_DONE is returned when a \r\n\r\n pattern is encountered, indicating the end of the header.

INK_PARSE_CONT is returned if parsing of the header stopped because the end of the buffer was reached.

int INKHttpHdrParseResp (INKHttpParser parser, INKMBuffer bufp, INKMLoc hdr_loc, const char **start, const char *end)

Parses an HTTP response header. The HTTP header hdr_loc must already be created and must reside inside the marshal buffer bufp. The start argument points to the current position of the string buffer being parsed and the end argument points to one byte after the end of the buffer to be parsed. On return, start is modified to point past the last character parsed.

It is possible to parse an HTTP response header a single byte at a time using repeated calls to INKHttpHdrParseResp. As long as an error does not occur, the INKHttpHdrParseResp function consumes that single byte and asks for more.

Call after READ_RESPONSE_HDR_HOOK if it is a transaction header.

INK_PARSE_ERROR is returned if there is an error.

INK_PARSE_DONE is returned when a \r\n\r\n pattern is encountered, indicating the end of the header.

INK_PARSE_CONT is returned if parsing of the header stopped because the end of the buffer was reached