NAME

       TSHttpArgs - TSHttpArgs API function

SYNOPSIS

       #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(TSHttpTxn txnp, int arg_idx, void *arg)

       void *TSHttpSsnArgGet(TSHttpTxn txnp, 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/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

       2021, dev@trafficserver.apache.org