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

       2023, dev@trafficserver.apache.org