.\" 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 "TSCLIENTPROTOCOLSTACK" "3ts" "Nov 02, 2023" "9.2" "Apache Traffic Server"
.SH NAME
TSClientProtocolStack \- TSClientProtocolStack API function
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <ts/ts.h>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP  TSHttpTxnClientProtocolStackGet(\fI\%TSHttpTxn\fP  txnp, int  count, char  const  **result, int  *actual) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP  TSHttpTxnServerProtocolStackGet(\fI\%TSHttpTxn\fP  txnp, int  count, const  char  **result, int  *actual) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP  TSHttpSsnClientProtocolStackGet(\fI\%TSHttpSsn\fP  ssnp, int  count, char  const  **result, int  *actual) 
.UNINDENT
.INDENT 0.0
.TP
.B char  const  *TSHttpTxnClientProtocolStackContains(\fI\%TSHttpTxn\fP  txnp) 
.UNINDENT
.INDENT 0.0
.TP
.B const  char  *TSHttpTxnServerProtocolStackContains(\fI\%TSHttpTxn\fP  txnp, char  const  *tag) 
.UNINDENT
.INDENT 0.0
.TP
.B char  const  *TSHttpSsnClientProtocolStackContains(\fI\%TSHttpSsn\fP  ssnp) 
.UNINDENT
.INDENT 0.0
.TP
.B char  const  *TSNormalizedProtocolTag(char  const  *tag) 
.UNINDENT
.INDENT 0.0
.TP
.B char  const  *TSRegisterProtocolTag(char  const  *tag) 
.UNINDENT
.SH DESCRIPTION
.sp
These functions are used to explore the protocol stack of either the client (user agent) or origin server connection to
Traffic Server\&. The functions \fI\%TSHttpTxnClientProtocolStackGet()\fP and
\fI\%TSHttpSsnClientProtocolStackGet()\fP can be used to retrieve the entire protocol stack for the
user agent connection. The \fI\%TSHttpTxnServerProtocolStackGet()\fP can be used
to retrieve the entire protocol stack for
the origin server connection. \fI\%TSHttpTxnClientProtocolStackContains()\fP,
\fI\%TSHttpSsnClientProtocolStackContains()\fP, and
\fI\%TSHttpTxnServerProtocolStackContains()\fP  will check for a specific
protocol \fItag\fP being present in the stack.
.sp
Each protocol is represented by tag which is a null terminated string. A particular tag will always
be returned as the same character pointer and so protocols can be reliably checked with pointer
comparisons. \fI\%TSNormalizedProtocolTag()\fP will return this character pointer for a specific
\fItag\fP\&. A return value of \fBNULL\fP indicates the provided \fItag\fP is not registered as
a known protocol tag. \fI\%TSRegisterProtocolTag()\fP registers the \fItag\fP and then returns its
normalized value. This is useful for plugins that provide custom protocols for user agents.
.sp
The protocols are ordered from higher level protocols to the lower level ones on which the higher
operate. For instance a stack might look like \(dqhttp/1.1,tls/1.2,tcp,ipv4\(dq. For
\fI\%TSHttpTxnClientProtocolStackGet()\fP, \fI\%TSHttpSsnClientProtocolStackGet()\fP, and \fI\%TSHttpTxnServerProtocolStackGet()\fP these values
are placed in the array \fIresult\fP\&. \fIcount\fP is the maximum number of elements of
\fIresult\fP that may be modified by the function call. If \fIactual\fP is not \fBNULL\fP then
the actual number of elements in the protocol stack will be returned. If this is equal or less than
\fIcount\fP then all elements were returned. If it is larger then some layers were omitted from
\fIresult\fP\&. If the full stack is required \fIactual\fP can be used to resize \fIresult\fP to
be sufficient to hold all of the elements and the function called again with updated \fIcount\fP
and \fIresult\fP\&. In practice the maximum number of elements is almost certain to be less
than 10 which therefore should suffice. These functions return \fBTS_SUCCESS\fP on success and
\fBTS_ERROR\fP on failure which should only occur if \fItxnp\fP or \fIssnp\fP are invalid.
.sp
The \fI\%TSHttpTxnClientProtocolStackContains()\fP, \fI\%TSHttpSsnClientProtocolStackContains()\fP, and \fI\%TSHttpTxnServerProtocolStackContains()\fP
functions are provided for the convenience when only the presence of a protocol is of interest, not
its location or the presence of other protocols. These functions return \fBNULL\fP if the protocol
\fItag\fP is not present, and a pointer to the normalized tag if it is present. The strings are
matched with an anchor prefix search, as with debug tags. For instance if \fItag\fP is \(dqtls\(dq then it
will match \(dqtls/1.2\(dq or \(dqtls/1.3\(dq. This makes checking for TLS or IP more convenient. If more precision
is required the entire protocol stack can be retrieved and processed more thoroughly.
.sp
The protocol tags defined by Traffic Server\&.
.TS
center;
|l|l|.
_
T{
Protocol
T}	T{
Tag
T}
_
T{
HTTP/1.1
T}	T{
http/1.1
T}
_
T{
HTTP/1.0
T}	T{
http/1.0
T}
_
T{
HTTP/2
T}	T{
h2
T}
_
T{
WebSocket
T}	T{
ws
T}
_
T{
TLS 1.3
T}	T{
tls/1.3
T}
_
T{
TLS 1.2
T}	T{
tls/1.2
T}
_
T{
TLS 1.1
T}	T{
tls/1.1
T}
_
T{
TLS 1.0
T}	T{
tls/1.0
T}
_
T{
TCP
T}	T{
tcp
T}
_
T{
UDP
T}	T{
udp
T}
_
T{
IPv4
T}	T{
ipv4
T}
_
T{
IPv6
T}	T{
ipv6
T}
_
T{
QUIC
T}	T{
quic
T}
_
.TE
.SS Examples
.sp
The example below is excerpted from \fIexample/plugins/c\-api/protocol_stack/protocol_stack.cc\fP
in the Traffic Server source distribution. It demonstrates how to
use \fI\%TSHttpTxnClientProtocolStackGet()\fP and \fI\%TSHttpTxnClientProtocolStackContains()\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
static int
proto_stack_cb(TSCont contp ATS_UNUSED, TSEvent event, void *edata)
{
  TSHttpTxn txnp = static_cast<TSHttpTxn>(edata);
  const char *results[10];
  int count = 0;
  TSDebug(PLUGIN_NAME, \(dqProtocols:\(dq);
  TSHttpTxnClientProtocolStackGet(txnp, 10, results, &count);
  for (int i = 0; i < count; i++) {
    TSDebug(PLUGIN_NAME, \(dq\et%d: %s\(dq, i, results[i]);
  }
  const char *ret_tag = TSHttpTxnClientProtocolStackContains(txnp, \(dqh2\(dq);
  TSDebug(PLUGIN_NAME, \(dqStack %s HTTP/2\(dq, ret_tag != nullptr ? \(dqcontains\(dq : \(dqdoes not contain\(dq);
  TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
  return 0;
}

.ft P
.fi
.UNINDENT
.UNINDENT
.SH COPYRIGHT
2023, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.