TSHttpHookAdd

Synopsis

#include <ts/ts.h>

void TSHttpHookAdd(TSHttpHookID id, TSCont contp)

void TSHttpSsnHookAdd(TSHttpSsn ssnp, TSHttpHookID id, TSCont contp)

void TSHttpTxnHookAdd(TSHttpTxn txnp, TSHttpHookID id, TSCont contp)

Description

Hooks are points in Apache Traffic Server transaction HTTP processing where plugins can step in and do some work. Registering a plugin function for callback amounts to adding the function to a hook. You can register your plugin to be called back for every single transaction, or for specific transactions only.

HTTP transaction hooks are set on a global basis using the function TSHttpHookAdd(). This means that the continuation specified as the parameter to TSHttpHookAdd() is called for every transaction. TSHttpHookAdd() is typically called from TSPluginInit() or TSRemapInit().

A session consists of a single client connection to Traffic Server. A session can consist of several transactions in succession. The session starts when the client connection opens, and ends when the connection closes. TSHttpSsnHookAdd() adds contp to the end of the list of HTTP transaction hooks specified by id. This means that contp is called back for every transaction within the session, at the point specified by the hook ID. Since contp is added to a session, it is not possible to call TSHttpSsnHookAdd() from the plugin initialization routine; the plugin needs a handle to an HTTP session.

A transaction consists of a single HTTP request from a client and the response that Traffic Server sends to that client. A transaction begins when Traffic Server receives a request, and ends when Traffic Server sends the response. TSHttpTxnHookAdd() 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 TSHttpTxnHookAdd() from the plugin initialization routine but only when the plugin has a handle to an HTTP transaction.

Return values

None. Adding hooks is always successful.

Examples

The following example demonstrates how to add global, session and transaction hooks:

#include <ts/ts.h>

static int
handler(TSCont contp, TSEvent event, void *edata)
{
    TSHttpSsn ssnp;
    TSHttpTxn txnp;

    switch (event){
    case TS_EVENT_HTTP_SSN_START:
        ssnp = (TSHttpSsn) edata;
        // Add a session hook ...
        TSHttpSsnHookAdd(ssnp, TS_HTTP_TXN_START_HOOK, contp);
        TSHttpSsnReenable(ssnp, TS_EVENT_HTTP_CONTINUE);
        return 0;
    case TS_EVENT_HTTP_TXN_START:
        txnp = (TSHttpTxn) edata;
        // Add a transaction hook ...
        TSHttpTxnHookAdd(ssnp, TS_HTTP_READ_REQUEST_HDR_HOOK, contp);
        TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
        return 0;
    default:
         break;
    }

    return 0;
}

void
TSPluginInit (int argc, const char *argv[])
{
    TSCont contp;
    contp = TSContCreate(handler, NULL);
    TSHttpHookAdd(TS_HTTP_SSN_START_HOOK, contp);
}

See also

TSAPI(3ts), TSContCreate(3ts)