NAME

       TSHttpArgs - TSHttpArgs API function

SYNOPSIS

       NOTE:
          This  set  of API is obsoleted as of ATS v9.0.0, and will be removed with ATS v10.0.0!  For details of
          the new APIs, see TSUserArgs.

          #include <ts/ts.h>

       TSReturnCode TSHttpTxnArgIndexReserve(const char *name, const char *description, int *arg_idx)

       TSReturnCode TSHttpTxnArgIndexNameLookup(const char *name, int *arg__idx, const char **description)

       TSReturnCode TSHttpTxnArgIndexLookup(int arg_idx, const char **name, const char **description)

       TSReturnCode TSHttpSsnArgIndexReserve(const char *name, const char *description, int *arg_idx)

       TSReturnCode TSHttpSsnArgIndexNameLookup(const char *name, int *arg__idx, const char **description)

       TSReturnCode TSHttpSsnArgIndexLookup(int arg_idx, const char **name, const char **description)

       void TSHttpTxnArgSet(TSHttpTxn txnp, int arg_idx, void *arg)

       void *TSHttpTxnArgGet(TSHttpTxn txnp, int arg_idx)

       void TSHttpSsnArgSet(TSHttpSsn ssnp, int arg_idx, void *arg)

       void *TSHttpSsnArgGet(TSHttpSsn ssnp, int arg_idx)

DESCRIPTION

       Traffic Server sessions and transactions provide a fixed array of void  pointers  that  can  be  used  by
       plugins  to  store  information.  This  can  be  used  to  avoid  creating  a  per session or transaction
       continuations to hold data, or to communicate between plugins as the values in the array are  visible  to
       any plugin which can access the session or transaction. The array values are opaque to Traffic Server and
       it  will  not dereference nor release them. Plugins are responsible for cleaning up any resources pointed
       to by the values or, if the values are simply values, there is no need for  the  plugin  to  remove  them
       after the session or transaction has completed.

       To  avoid  collisions  between plugins a plugin should first reserve an index in the array. A transaction
       based plugin argument is reserved by calling TSHttpTxnArgIndexReserve(). A session base  plugin  argument
       is reserved by calling TSHttpSsnArgIndexReserve(). Both functions have the arguments

       name   An identifying name for the plugin that reserved the index. Required.

       description
              An optional description of the use of the arg. This can be nullptr.

       arg_idx
              A  pointer  to  an int. If an index is successfully reserved, the int pointed at by this is set to
              the reserved index. It is not modified if the call is unsuccessful.

       The functions return TS_SUCCESS if an index was reserved, TS_ERROR if not (most likely because all of the
       indices have already been reserved).  Generally this will be a file or library scope global which is  set
       at    plugin    initialization.    This    function    is    used    in    the   example   remap   plugin
       example/plugins/c-api/remap/remap.cc. The index is stored in the plugin global arg_index. Transaction and
       session plugin argument indices are reserved independently.

       To   look   up   the   owner   of    a    reserved    index    use    TSHttpTxnArgIndexNameLookup()    or
       TSHttpSsnArgIndexNameLookup()  for transaction and session plugin argument respectively. If name is found
       as an owner, the function returns TS_SUCCESS and arg_index is updated with the index reserved under  that
       name.  If  description is not NULL then the character pointer to which it points will be updated to point
       at the description for that reserved index. This enables communication between plugins where  plugin  "A"
       reserves  an  index  under a well known name and plugin "B" locates the index by looking it up under that
       name.

       The owner of a reserved index can be found with  TSHttpTxnArgIndexLookup()  or  TSHttpSsnArgIndexLookup()
       for  transaction  and  session  plugin arguments respectively. If arg_index is reserved then the function
       returns TS_SUCCESS and the pointers referred to by name and description are updated. name must point at a
       valid character pointer but description can be NULL in which case it is ignored.

       Manipulating the array is simple. TSHttpTxnArgSet() sets the array slot at arg_idx  for  the  transaction
       txnp  to  the  value  arg.  Note  this  sets  the  value  only  for  the  specific transaction. Similarly
       TSHttpSsnArgSet()  sets  the  value  for  a  session  argument.  The  values  can   be   retrieved   with
       TSHttpTxnArgGet()  for transactions and TSHttpSsnArgGet() for sessions, which return the specified value.
       Values that have not been set are NULL.

       NOTE:
          Session arguments persist for the entire session, which means potentially across all  transactions  in
          that session.

       NOTE:
          Following arg index reservations is conventional, it is not enforced.

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                   TSHTTPARGS(3ts)