NAME

       TSHttpHookAdd - intercept Traffic Server events

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() must only be called from TSPluginInit() or TSRemapInit().

       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.

       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.

       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

       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(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, NULL);
              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).

SEE ALSO

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

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                TSHTTPHOOKADD(3ts)