.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "TSHTTPARGS" "3ts" "Jan 06, 2024" "9.2" "Apache Traffic Server" .SH NAME TSHttpArgs \- TSHttpArgs API function .SH SYNOPSIS .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 \fI\%TSUserArgs\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX #include .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpTxnArgIndexReserve(const char *name, const char *description, int *arg_idx) .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpTxnArgIndexNameLookup(const char *name, int *arg__idx, const char **description) .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpTxnArgIndexLookup(int arg_idx, const char **name, const char **description) .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpSsnArgIndexReserve(const char *name, const char *description, int *arg_idx) .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpSsnArgIndexNameLookup(const char *name, int *arg__idx, const char **description) .UNINDENT .INDENT 0.0 .TP .B \fI\%TSReturnCode\fP TSHttpSsnArgIndexLookup(int arg_idx, const char **name, const char **description) .UNINDENT .INDENT 0.0 .TP .B void TSHttpTxnArgSet(\fI\%TSHttpTxn\fP txnp, int arg_idx, void *arg) .UNINDENT .INDENT 0.0 .TP .B void *TSHttpTxnArgGet(\fI\%TSHttpTxn\fP txnp, int arg_idx) .UNINDENT .INDENT 0.0 .TP .B void TSHttpSsnArgSet(\fI\%TSHttpSsn\fP ssnp, int arg_idx, void *arg) .UNINDENT .INDENT 0.0 .TP .B void *TSHttpSsnArgGet(\fI\%TSHttpSsn\fP ssnp, int arg_idx) .UNINDENT .SH DESCRIPTION .sp 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. .sp To avoid collisions between plugins a plugin should first \fIreserve\fP an index in the array. A transaction based plugin argument is reserved by calling \fI\%TSHttpTxnArgIndexReserve()\fP\&. A session base plugin argument is reserved by calling \fI\%TSHttpSsnArgIndexReserve()\fP\&. Both functions have the arguments .INDENT 0.0 .TP .B \fIname\fP An identifying name for the plugin that reserved the index. Required. .TP .B \fIdescription\fP An optional description of the use of the arg. This can be \fBnullptr\fP\&. .TP .B \fIarg_idx\fP A pointer to an \fBint\fP\&. If an index is successfully reserved, the \fBint\fP pointed at by this is set to the reserved index. It is not modified if the call is unsuccessful. .UNINDENT .sp The functions return \fBTS_SUCCESS\fP if an index was reserved, \fBTS_ERROR\fP 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 \fI\%example/plugins/c\-api/remap/remap.cc\fP\&. The index is stored in the plugin global \fBarg_index\fP\&. Transaction and session plugin argument indices are reserved independently. .sp To look up the owner of a reserved index use \fI\%TSHttpTxnArgIndexNameLookup()\fP or \fI\%TSHttpSsnArgIndexNameLookup()\fP for transaction and session plugin argument respectively. If \fIname\fP is found as an owner, the function returns \fBTS_SUCCESS\fP and \fIarg_index\fP is updated with the index reserved under that name. If \fIdescription\fP is not \fBNULL\fP 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 \(dqA\(dq reserves an index under a well known name and plugin \(dqB\(dq locates the index by looking it up under that name. .sp The owner of a reserved index can be found with \fI\%TSHttpTxnArgIndexLookup()\fP or \fI\%TSHttpSsnArgIndexLookup()\fP for transaction and session plugin arguments respectively. If \fIarg_index\fP is reserved then the function returns \fBTS_SUCCESS\fP and the pointers referred to by \fIname\fP and \fIdescription\fP are updated. \fIname\fP must point at a valid character pointer but \fIdescription\fP can be \fBNULL\fP in which case it is ignored. .sp Manipulating the array is simple. \fI\%TSHttpTxnArgSet()\fP sets the array slot at \fIarg_idx\fP for the transaction \fItxnp\fP to the value \fIarg\fP\&. Note this sets the value only for the specific transaction. Similarly \fI\%TSHttpSsnArgSet()\fP sets the value for a session argument. The values can be retrieved with \fI\%TSHttpTxnArgGet()\fP for transactions and \fI\%TSHttpSsnArgGet()\fP for sessions, which return the specified value. Values that have not been set are \fBNULL\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Session arguments persist for the entire session, which means potentially across all transactions in that session. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Following arg index reservations is conventional, it is not enforced. .UNINDENT .UNINDENT .SH COPYRIGHT 2024, dev@trafficserver.apache.org .\" Generated by docutils manpage writer. .