.\" 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 "TSVCONNARGS" "3ts" "Jan 06, 2024" "9.2" "Apache Traffic Server"
.SH NAME
TSVConnArgs \- TSVConnArgs 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 <ts/ts.h>
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP TSVConnArgIndexReserve(const char *name, const char *description, int *arg_idx) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP TSVConnArgIndexNameLookup(const char *name, int *arg_idx, const char **description) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP TSVConnArgIndexLookup(int arg_idx, const char **name, const char **description) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSVConnArgSet(\fI\%TSVConn\fP vc, int arg_idx, void *arg) 
.UNINDENT
.INDENT 0.0
.TP
.B void *TSVConnArgGet(\fI\%TSVConn\fP vc, int arg_idx) 
.UNINDENT
.SH DESCRIPTION
.sp
Virtual connection objects (API type \fI\%TSVConn\fP) support an array of \fBvoid *\fP 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.
.sp
To avoid collisions between plugins a plugin should first \fIreserve\fP an index in the array by calling
\fI\%TSVConnArgIndexReserve()\fP passing it an identifying name, a description, and a pointer to an
integer which will get the reserved index. The function returns \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. Note the reservation is by convention \- nothing stops a plugin from interacting with
a \fBTSVConn\fP arg it has not reserved.
.sp
To look up the owner of a reserved index use \fI\%TSVConnArgIndexNameLookup()\fP\&. If the \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 \fBnullptr\fP then it will be updated
with 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\%TSVConnArgIndexLookup()\fP\&. If \fIarg_index\fP is
reserved then the function returns \fBTS_SUCCESS\fP and \fIname\fP and \fIdescription\fP are
updated. \fIname\fP must point at a valid character pointer but \fIdescription\fP can be
\fBnullptr\fP\&.
.sp
Manipulating the array is simple. \fI\%TSVConnArgSet()\fP sets the array slot at \fIarg_idx\fP for
the \fIvc\fP to the value \fIarg\fP\&. Note this sets the value only for the specific
\fI\%TSVConn\fP\&. The values can be retrieved with \fI\%TSVConnArgGet()\fP which returns the
specified value. Values that have not been set are \fBnullptr\fP\&.
.SH HOOKS
.sp
Although these can be used from any hook that has access to a \fI\%TSVConn\fP it will generally be
the case that \fI\%TSVConnArgSet()\fP will be used in early intervention hooks and
\fI\%TSVConnArgGet()\fP in session / transaction hooks. Cleanup should be done on the
\fBTS_VCONN_CLOSE_HOOK\fP\&.
.sp
Appendix
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This is originally from \fI\%Issue 2388\fP\&. It
has been extended based on discussions with Kees and Leif Hedstrom at the ATS summit.
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2024, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.