Traffic Server Software Developers Kit

INKReturnCode INKHttpTxnCacheLookupStatusGet (INKHttpTxn txnp, int *lookup_status)

INKHttpTxn txnp is the ongoing transaction.

int *lookup_status is set to the lookup status.

Obtains the status of the current cache lookup for the ongoing transaction txnp in the lookup_status variable.

This function should only be called from INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK.

The possible status values returned in lookup_status are:

• INK_CACHE_LOOKUP_MISS - Document was not in the cache; it will be fetched from the OS.
• INK_CACHE_LOOKUP_HIT_STALE - Document was present in the cache but stale. A fresher version will be fetched from the OS (IMS request).
• INK_CACHE_LOOKUP_HIT_FRESH - Document was present in the cache and is fresh. Document will be served from the cache.
• INK_CACHE_LOOKUP_SKIPPED - Traffic Server didn't perform a cache lookup as the request was not cacheable (this can happen when the URL looks dynamic or the request is marked as noncacheable).

INK_SUCCESS if the API is called successfully.

INK_ERROR if an error occurs while calling the API or if an argument is invalid.

INKReturnCode INKHttpTxnCachedReqGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

INKHttpTxn txnp is the ongoing transaction.

int *lookup_status is set to the lookup status.

Obtains the status of the current cache lookup for the ongoing transaction txnp in the lookup_status variable.

This function should only be called from INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK.

The possible status values returned in lookup_status are:

• INK_CACHE_LOOKUP_MISS - Document was not in the cache; it will be fetched from the OS.
• INK_CACHE_LOOKUP_HIT_STALE - Document was present in the cache but stale. A fresher version will be fetched from the OS (IMS request).
• INK_CACHE_LOOKUP_HIT_FRESH - Document was present in the cache and is fresh. Document will be served from the cache.
• INK_CACHE_LOOKUP_SKIPPED - Traffic Server didn't perform a cache lookup because the request was not cacheable (this can happen when the URL looks dynamic or the request is marked as noncacheable).

INK_SUCCESS if the API is called successfully.

INK_ERROR if an error occurs while calling the API or if an argument is invalid.

int INKHttpTxnCachedRespGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

Retrieves the cached response header from the HTTP transaction txnp and stores the cached response header in bufp, at location hdr_loc.

Call after SEND_RESPONSE_HDR_HOOK.

	Caution
	Do not modify any cached response headers returned by INKHttpTxnCachedRespGet; the underlying data structure is read-only. Release the returned hdr_loc with a call to INKHandleMLocRelease.

If the cached response header does not exist, then INKHttpTxnCachedRespGet returns 0.

Otherwise, it returns 1.

int INKHttpTxnClientIncomingPortGet (INKHttpTxn txnp)

Returns the port on which the HTTP transaction txnp was received. This is not the destination port in the UR; it is the proxy port to which the client browser is pointed.

Call after TXN_START_HOOK.

The port number in host byte order.

Returns -1 if an error occurred.

unsigned int INKHttpTxnClientIPGet (INKHttpTxn txnp)

Returns the IP address of the client for the HTTP transaction txnp.

INKHttpTxnClientIPGet returns the IP address in network byte order.

Call after TXN_START_HOOK.

The client IP address.

Returns 0 if an error occurred.

INKReturnCode INKHttpTxnClientRemotePortGet(INKHttpTxn txnp, int *port)

INKHttpTxn txnp is an HTTP transaction.

int *port is set to the client’s remote port value (port number used by the client when creating a socket connection with the proxy for the transaction txnp) in network byte order.

Obtains the port number of the remote host for the specified HTTP transaction. The port number is returned in network byte order.

	Note
	This is an exception to the rule that port numbers are retrieved in host byte order.

The proxy port on which the connection was accepted can be retrieved using INKHttpTxnClientIncomingPortGet.

INK_SUCCESS if the API is called successfully.

INK_ERROR if an error occurs while calling the API or if an argument is invalid.

int INKHttpTxnClientReqGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

Retrieves the client request header from the HTTP transaction txnp. INKHttpTxnClientReqGet stores the client request header in bufp, at location hdr_loc.

Call after READ_REQUEST_HDR_HOOK.

Release the returned hdr_loc with a call to INKHandleMLocRelease.

If the client request header does not exist or if there is an error, then INKHttpTxnClientReqGet returns 0.

Otherwise, 1 is returned.

int INKHttpTxnClientRespGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

Retrieves the client response header from the HTTP transaction txnp. INKHttpTxnClientRespGet stores the client response header in bufp, at location hdr_loc.

Call after SEND_RESPONSE_HOOK.

Release the returned hdr_loc with a call to INKHandleMLocRelease.

If the client response header does not exist or if there is an error, then INKHttpTxnClientRespGet returns 0.

Otherwise, 1 is returned.

INKReturnCode INKHttpTxnErrorBodySet (INKHttpTxn txnp, char *buf, int buflength, char *mimetype)

txnp is the HTTP transaction to act upon.

buf contains the error (or response) body. The error body can be text, an HTML document, image, or another format. Before you call INKHttpTxnErrorBodySet, be sure to allocate buf using INKmalloc.

buflength is the length of the error body.

mimetype contains the format of the error body. If you want to set the mimetype to a value other than NULL, then you must allocate mimetype using INKmalloc before you call INKHttpTxnErrorBodySet.

Sets the format of the error body Traffic Server sends back when sending an error or response to a client. The error body data is stored in the buffer buf. If the error body is just plain text, then setting mimetype to NULL works fine. If the error body is HTML, then mimetype should be "text/html". If the error body is a JPEG image, then mimetype should be “image/jpeg".

	Note
	Traffic Server automatically calls INKfree to free buf when it is no longer needed; make sure that the buffer buf is allocated by a call to INKmalloc. Similarly, if you want to set mimetype to something other than NULL, then make sure that you allocate mimetype with a call to INKmalloc. Traffic Server automatically calls INKfree to free mimetype.

Call after SEND_RESPONSE_HDR_HOOK.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

INKReturnCode INKHttpTxnHookAdd (INKHttpTxn txnp, INKHttpHookID id, INKCont contp)

Adds contp to the end of the list of HTTP transaction hooks specified by id. Since contp is added to a transaction, it is not possible to call INKHttpTxnHookAdd from the plugin initialization routine unless the plugin has a handle to an HTTP transaction.

Call after HTTP_TXN_START_HOOK.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

unsigned int INKHttpTxnNextHopIPGet (INKHttpTxn txnp)

Returns the IP address of the next server from which Traffic Server attempts to retrieve the requested document, in network byte order. This IP address could be the origin server IP address or it could be the parent proxy’s IP address.

Call after SEND_REQUEST_HDR_HOOK.

Returns the IP address of the next server from which Traffic Server attempts to retrieve the request, in network byte order.

Returns 0 if an error occurred.

INKReturnCode INKHttpTxnParentProxyGet (INKHttpTxn txnp, char **hostname, int *port)

Retrieves the value set previously by INKHttpParentProxySet. Does not return values set in parent.config or records.config for the proxy.config.http.parent_proxies parameter.

This function can be called from within any transaction hook.

The hostname string returned must not be deallocated.

	Note
	If parent proxying is not enabled, then INKHttpTxnParentProxyGet returns NULL for hostname and -1 for port.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

INKReturnCode INKHttpTxnParentProxySet (INKHttpTxn txnp, char *hostname, int port)

This can be used to overwrite the value set in records.config for the parameter proxy.config.http.parent_proxies, or in the parent.config file.

Call before or within CACHE_LOOKUP_COMPLETE.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

INKReturnCode INKHttpTxnReenable (INKHttpTxn txnp, INKEvent event)

Notifies the HTTP transaction txnp that the plugin is finished processing the current hook. If INK_EVENT_HTTP_CONTINUE is specified for event, then the plugin wants the transaction to continue. If INK_EVENT_HTTP_ERROR is specified for event, then the plugin wants the transaction to be terminated; an error is then sent back to the client if no response has already been sent.

You must always reenable the HTTP transaction after each transaction event is processed. However, you should never reenable twice - this is a serious error.

When event is set to INK_EVENT_HTTP_ERROR, Traffic Server performs different processing depending on the type of hook involved.

• INK_HTTP_TXN_START_HOOK: the transaction is stopped right away, then the client connection is closed and no response is sent back to the origin server.
• INK_HTTP_READ_REQUEST_HDR_HOOK: Traffic Server does not send a request to the origin server; it directly sends a 500 to the client.
• INK_HTTP_SEND_REQUEST_HDR_HOOK: Traffic Server opens a connection to the origin server, sends an empty request to it, and sends a 500 status message back to the client. The connection to the origin server is then closed.
• INK_HTTP_READ_RESPONSE_HDR_HOOK, INK_HTTP_SEND_RESPONSE_HOOK, INK_HTTP_OS_DNS_HOOK, INK_HTTP_READ_CACHE_HDR_HOOK, and INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK: Traffic Server receives all headers in the origin server's response, closes the connection to the origin server, and sends a 500 status message back to the client. Traffic Server does not receive the response body.
• INK_HTTP_TXN_CLOSE_HOOK: the client receives whatever answer was sent by the origin server because with this hook, the response has already been sent to the client.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

unsigned int INKHttpTxnServerIPGet (INKHttpTxn txnp)

Returns the IP address of the origin server specified by the client request in network byte order. INKHttpTxnServerIPGet returns 0 if it is called before INK_HTTP_OS_DNS_HOOK in a transaction.

Call after INK_HTTP_OS_DNS_HOOK.

Returns the origin server IP address in network byte order.

Returns 0 if an error occurred.

int INKHttpTxnServerReqGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

Retrieves the server request header from the HTTP transaction txnp. INKHttpTxnServerReqGet stores the server request header in bufp, at location hdr_loc.

Call after SEND_REQUEST_HDR_HOOK.

Release the returned hdr_loc with a call to INKHandleMLocRelease.

If the server request header does not exist or in the case of an error, then INKHttpTxnServerReqGet returns 0.

Otherwise, it returns 1.

int INKHttpTxnServerRespGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)

Retrieves the server response header from the HTTP transaction txnp. INKHttpTxnServerRespGet stores the server response header in bufp, at location hdr_loc.

Call after READ_RESPONSE_HDR_HOOK.

Release the returned hdr_loc with a call to INKHandleMLocRelease.

If the server response header does not exist or if there is an error, then INKHttpTxnServerRespGet returns 0.

Otherwise, 1 is returned.

INKHttpSsn INKHttpTxnSsnGet (INKHttpTxn txnp)

Retrieves the INKHttpSsn handle associated with the HTTP transaction txnp.

Call after TXN_START_HOOK.

The session handle associated with the specified HTTP transaction.

INK_ERROR_PTR if an error occurs.

INKReturnCode INKHttpTxnTransformedRespCache (INKHttpTxn txnp, int on)

Specifies whether the transformed document should be written to the cache. If a transformation is occurring, then the default is for the transformed copy to be written to the cache. The default maintains a rule that only a single version of a document is written to the cache for a single transaction. It is valid for that rule to be broken if you specify that both the transformed and untransformed documents be written to the cache. Calls need to be made prior to the actual transformation, (i.e. at the time of creating the transformation) rather than in the transformation.

	Note
	This function does not overwrite HTTP directives (like Cache-Control or Expires) that determine whether a document is cached. If the document can be cached, then this function determines if the transformed version should be cached. Untransformed and transformed documents are cached as HTTP alternates.

Call from within or after hook TXN_START_HOOK.

If called after hook SEND_RESPONSE_HDR, then this function will not be taken into account by Traffic Server.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.

int INKHttpTxnTransformRespGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *offset)

Retrieves the transform response header from the HTTP transaction txnp and stores the transform response header in bufp, at location offset.

Call from within your transformation, before transform data is written to the downstream vconnection.

If the transform response header does not exist, then INKHttpTxnTransformRespGet returns 0.

Otherwise, 1 is returned.

INKReturnCode INKHttpTxnUntransformedRespCache (INKHttpTxn txnp, int on)

Specifies whether the untransformed document should be written to the cache. If there is no transformation occurring, then the untransformed copy will be written to the cache (by default). If a transformation is occurring, then the untransformed copy will not be written to the cache (by default). The defaults maintain a rule that only a single version of a document is written to the cache for a single transaction. It is valid for that rule to be broken by specifying that both the transformed and untransformed document be written to the cache. Calls need to be made prior to the actual transformation (i.e. at the time of creating the transformation), rather than in the transformation.

	Note
	This function does not overwrite HTTP directives (ike Cache-Control or Expires) that determine if a document can be cached. If the document can be cached, then this function determines if the untransformed version should be cached. Untransformed and transformed documents are cached as HTTP alternates.

Call from within or after hook TXN_START_HOOK.

If called after hook SEND_RESPONSE_HDR, then Traffic Server will not take this function into account.

INK_SUCCESS if the operation completes successfully.

INK_ERROR if an error occurs.