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