NAME

       TSUserArgs - TSUserArgs API function

SYNOPSIS

          #include <ts/ts.h>

          typedef enum {
            TS_USER_ARGS_TXN,   ///< Transaction based.
            TS_USER_ARGS_SSN,   ///< Session based
            TS_USER_ARGS_VCONN, ///< VConnection based
            TS_USER_ARGS_GLB,   ///< Global based
            TS_USER_ARGS_COUNT  ///< Fake enum, # of valid entries.
          } TSUserArgType;

       TSReturnCode  TSUserArgIndexReserve(TSUserArgType  type,  const  char  *name,  const  char
       *description, int *arg_idx)

       TSReturnCode TSUserArgIndexNameLookup(TSUserArgType type, const char *name, int  *arg_idx,
       const char **description)

       TSReturnCode  TSUserArgIndexLookup(TSUserArgType  type,  int  arg_idx,  const char **name,
       const char **description)

       void TSUserArgSet(void *data, int arg_idx, void *arg)

       void *TSUserArgGet(void *data, int arg_idx)

DESCRIPTION

       Traffic Server sessions, transactions, virtual connections and globally  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
       plugin can reserve a slot of a particular type  by  calling  TSUserArgIndexReserve().  The
       arguments are:

       type   The type for which the plugin intend to reserve a slot. See TSUserArgType above.

       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 TSUserArgIndexNameLookup(), with the
       appropriate type.  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 TSUserArgIndexLookup(). 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. TSUserArgSet() sets the array slot at arg_idx,  for  the
       particular  type  based  on the provide data pointer. The values can be retrieved with the
       value from TSUserArgGet(). Values that have not been set are  NULL.  Note  that  both  the
       setter  and  the  getter  are  context sensitive, based on the type (or value) of the data
       pointer:

                              ┌──────────┬──────────────────────────────────┐
                              │data type │ Semantics                        │
                              ├──────────┼──────────────────────────────────┤
                              │TSHttpTxn │ The implicit context  is  for  a │
                              │          │ transaction (TS_USER_ARGS_TXN)   │
                              ├──────────┼──────────────────────────────────┤
                              │TSHttpSsn │ The  implicit  context  is for a │
                              │          │ transaction (TS_USER_ARGS_SSN)   │
                              ├──────────┼──────────────────────────────────┤
                              │TSVConn   │ The implicit context  is  for  a │
                              │          │ transaction (TS_USER_ARGS_VCONN) │
                              ├──────────┼──────────────────────────────────┤
                              │nullptr   │ The  implicit  context is global │
                              │          │ (TS_USER_ARGS_GLB)               │
                              └──────────┴──────────────────────────────────┘

       Note that neither TSUserArgSet() nor TSUserArgGet()  has  any  type  safety  on  the  data
       parameters, being a void* pointer.

       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

       2022, dev@trafficserver.apache.org