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;

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:

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:

Note that neither TSUserArgSet() nor TSUserArgGet() has any type safety on the data parameters, being a void* pointer.

NOTE:

NOTE:

COPYRIGHT

2023, dev@trafficserver.apache.org