NAME

       TSVConnArgs - TSVConnArgs 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 TSVConnArgIndexReserve(const char *name, const char *description, int *arg_idx)

       TSReturnCode TSVConnArgIndexNameLookup(const char *name, int *arg_idx, const char **description)

       TSReturnCode TSVConnArgIndexLookup(int arg_idx, const char **name, const char **description)

       void TSVConnArgSet(TSVConn vc, int arg_idx, void *arg)

       void *TSVConnArgGet(TSVConn vc, int arg_idx)

DESCRIPTION

       Virtual connection objects (API type TSVConn) support an array of  void  *  values  that  are  controlled
       entirely  by  plugins.  These  are  not  used  in  any way by the core. This allows plugins to store data
       associated with a specific virtual connection for later retrieval by the same plugin in a different  hook
       or  by  another  plugin.  Because  the  core  does  not  interact  with  these  values any cleanup is the
       responsibility of the plugin.

       To avoid collisions between plugins a plugin should first reserve  an  index  in  the  array  by  calling
       TSVConnArgIndexReserve() passing it an identifying name, a description, and a pointer to an integer which
       will  get  the  reserved index. The function returns 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. Note the reservation is by convention -
       nothing stops a plugin from interacting with a TSVConn arg it has not reserved.

       To look up the owner of a reserved index use TSVConnArgIndexNameLookup(). If the  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 nullptr then it will be updated with 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 TSVConnArgIndexLookup(). If arg_index  is  reserved  then
       the  function  returns  TS_SUCCESS  and  name  and  description  are  updated. name must point at a valid
       character pointer but description can be nullptr.

       Manipulating the array is simple. TSVConnArgSet() sets the array slot at arg_idx for the vc to the  value
       arg.  Note  this  sets  the  value  only  for  the  specific  TSVConn.  The  values can be retrieved with
       TSVConnArgGet() which returns the specified value. Values that have not been set are nullptr.

HOOKS

       Although these can be used from any hook that has access to a TSVConn it will generally be the case  that
       TSVConnArgSet()  will  be  used  in early intervention hooks and TSVConnArgGet() in session / transaction
       hooks. Cleanup should be done on the TS_VCONN_CLOSE_HOOK.

       Appendix

       NOTE:
          This is originally from Issue 2388. It has been extended based  on  discussions  with  Kees  and  Leif
          Hedstrom at the ATS summit.

COPYRIGHT

       2025, dev@trafficserver.apache.org

9.2                                               May 22, 2025                                  TSVCONNARGS(3ts)