TSHttpArgs¶
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
TSHttpTxnArgIndexReserve
(const char *name, const char *description, int *arg_idx)¶
-
TSReturnCode
TSHttpTxnArgIndexNameLookup
(const char *name, int *arg__idx, const char **description)¶
-
TSReturnCode
TSHttpTxnArgIndexLookup
(int arg_idx, const char **name, const char **description)¶
-
TSReturnCode
TSHttpSsnArgIndexReserve
(const char *name, const char *description, int *arg_idx)¶
-
TSReturnCode
TSHttpSsnArgIndexNameLookup
(const char *name, int *arg__idx, const char **description)¶
-
TSReturnCode
TSHttpSsnArgIndexLookup
(int arg_idx, const char **name, const char **description)¶
Description¶
Traffic Server sessions and transactions 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
transaction based plugin argument is reserved by calling TSHttpTxnArgIndexReserve()
. A session
base plugin argument is reserved by calling TSHttpSsnArgIndexReserve()
. Both functions have the arguments
- 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, theint
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 TSHttpTxnArgIndexNameLookup()
or
TSHttpSsnArgIndexNameLookup()
for transaction and session plugin argument respectively. 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 TSHttpTxnArgIndexLookup()
or
TSHttpSsnArgIndexLookup()
for transaction and session plugin arguments respectively. 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. TSHttpTxnArgSet()
sets the array slot at arg_idx for
the transaction txnp to the value arg. Note this sets the value only for the specific
transaction. Similarly TSHttpSsnArgSet()
sets the value for a session argument. The values can
be retrieved with TSHttpTxnArgGet()
for transactions and TSHttpSsnArgGet()
for sessions,
which return the specified value. Values that have not been set are NULL
.
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.