TSVConnArgs

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.

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

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

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

void * TSVConnArgGet(TSVConn vc, int arg_idx)

Virtual connection objects (API type ) 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 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 . 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.

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 . The values can be retrieved with TSVConnArgGet() which returns the specified value. Values that have not been set are nullptr.

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

Appendix

Note