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

       2024, dev@trafficserver.apache.org