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

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                   TSUSERARGS(3ts)