TSHttpHookAdd

Intercept Traffic Server events.

概要

#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)

解説

フックは Apache Traffic Server の HTTP 処理の中でプラグインが入り込み何かできる場所です。コールバックのためのプラグインの関数を登録することはフックに関数を追加することと同じです。一つずつすべてのトランザクション、もしくは特定のトランザクションのみにコールバックされるプラグインを登録することができます。

HTTP transaction and session 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() must only be called from TSPluginInit() or TSRemapInit(). Continuations set on a global hook will run before any continuations set on the session/transaction hook with the same hook ID.

TSHttpSsnHookAdd() adds contp to the end of the list of HTTP session 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. Continuations set on a session hook will run before any continuations set on the transaction hook with the same hook ID. This fucnction can be called from handler functions of continuations on a global per-session hook, including for the session hook with the same ID.

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. This fucnction can be called from handler functions of continuations on a global or session per-transaction hook, including the for transaction hook with the same ID.

A single continuation can be attached to multiple hooks at the same time. It is good practice to conserve resources by reusing hooks in this way when possible.

When a continuation on a hook is triggered, the name of the event passed to the continuation function depends on the name of the hook. The naming convention is that, for hook TS_xxx_HOOK, the event passed to the continuation function will be TS_EVENT_xxx. For example, when a continuation attached to TS_HTTP_READ_REQUEST_HDR_HOOK is triggered, the event passed to the continuation function will be TS_EVENT_HTTP_READ_REQUEST_HDR.

When a continuation is triggered by a hook, the actual type of the event data (the void pointer passed as the third parameter to the continuation function) is determined by which hook it is. For example, for the hook ID TS_HTTP_TXN_CLOSE_HOOK, the event data is of type TSHttpTxn. This is the case regardless of whether the continuation was added to the hook using TSHttpTxnHookAdd(), TSHttpSsnHookAdd() or TSHttpHookAdd(). If the event data is of type TSHttpTxn, TSHttpSsn or TSVConn, the continuation function can assume the mutex of the indicated event data object is locked. (But the continuation function must not unlock it.)

Return Values

無し。フックの追加は常に成功します。

例

次の例はどのようにグローバル、セッション、トランザクションフックを追加するかを紹介しています。

#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(txnp, TS_HTTP_READ_REQUEST_HDR_HOOK, contp);
        TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
        return 0;
    case TS_EVENT_HTTP_READ_REQUEST_HDR:
        txnp = (TSHttpTxn) edata;
        // ...
        TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
        return 0;
    default:
         break;
    }

    return 0;
}

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

For more example code using hooks, see the test_hooks plugin in tests/tools/plugins (used by the test_hooks.test.py Gold test).

参照

TSAPI(3ts), TSContCreate(3ts), TSLifecycleHookAdd(3ts)