Provided by: trafficserver-dev_9.2.3+ds-1+deb12u1build4_amd64 
NAME
TSClientProtocolStack - TSClientProtocolStack API function
SYNOPSIS
#include <ts/ts.h>
TSReturnCode TSHttpTxnClientProtocolStackGet(TSHttpTxn txnp, int count, char const **result, int *actual)
TSReturnCode TSHttpTxnServerProtocolStackGet(TSHttpTxn txnp, int count, const char **result, int *actual)
TSReturnCode TSHttpSsnClientProtocolStackGet(TSHttpSsn ssnp, int count, char const **result, int *actual)
char const *TSHttpTxnClientProtocolStackContains(TSHttpTxn txnp)
const char *TSHttpTxnServerProtocolStackContains(TSHttpTxn txnp, char const *tag)
char const *TSHttpSsnClientProtocolStackContains(TSHttpSsn ssnp)
char const *TSNormalizedProtocolTag(char const *tag)
char const *TSRegisterProtocolTag(char const *tag)
DESCRIPTION
These functions are used to explore the protocol stack of either the client (user agent) or origin server
connection to Traffic Server. The functions TSHttpTxnClientProtocolStackGet() and
TSHttpSsnClientProtocolStackGet() can be used to retrieve the entire protocol stack for the user agent
connection. The TSHttpTxnServerProtocolStackGet() can be used to retrieve the entire protocol stack for
the origin server connection. TSHttpTxnClientProtocolStackContains(),
TSHttpSsnClientProtocolStackContains(), and TSHttpTxnServerProtocolStackContains() will check for a
specific protocol tag being present in the stack.
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.
TSNormalizedProtocolTag() will return this character pointer for a specific tag. A return value of NULL
indicates the provided tag is not registered as a known protocol tag. TSRegisterProtocolTag() registers
the tag and then returns its normalized value. This is useful for plugins that provide custom protocols
for user agents.
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 "http/1.1,tls/1.2,tcp,ipv4". For
TSHttpTxnClientProtocolStackGet(), TSHttpSsnClientProtocolStackGet(), and
TSHttpTxnServerProtocolStackGet() these values are placed in the array result. count is the maximum
number of elements of result that may be modified by the function call. If actual is not NULL then the
actual number of elements in the protocol stack will be returned. If this is equal or less than count
then all elements were returned. If it is larger then some layers were omitted from result. If the full
stack is required actual can be used to resize result to be sufficient to hold all of the elements and
the function called again with updated count and result. In practice the maximum number of elements is
almost certain to be less than 10 which therefore should suffice. These functions return TS_SUCCESS on
success and TS_ERROR on failure which should only occur if txnp or ssnp are invalid.
The TSHttpTxnClientProtocolStackContains(), TSHttpSsnClientProtocolStackContains(), and
TSHttpTxnServerProtocolStackContains() 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
NULL if the protocol tag 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 tag is "tls" then
it will match "tls/1.2" or "tls/1.3". 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.
The protocol tags defined by Traffic Server.
┌──────────┬──────────┐
│Protocol │ Tag │
├──────────┼──────────┤
│HTTP/1.1 │ http/1.1 │
├──────────┼──────────┤
│HTTP/1.0 │ http/1.0 │
├──────────┼──────────┤
│HTTP/2 │ h2 │
├──────────┼──────────┤
│WebSocket │ ws │
├──────────┼──────────┤
│TLS 1.3 │ tls/1.3 │
├──────────┼──────────┤
│TLS 1.2 │ tls/1.2 │
├──────────┼──────────┤
│TLS 1.1 │ tls/1.1 │
├──────────┼──────────┤
│TLS 1.0 │ tls/1.0 │
├──────────┼──────────┤
│TCP │ tcp │
├──────────┼──────────┤
│UDP │ udp │
├──────────┼──────────┤
│IPv4 │ ipv4 │
├──────────┼──────────┤
│IPv6 │ ipv6 │
├──────────┼──────────┤
│QUIC │ quic │
└──────────┴──────────┘
Examples
The example below is excerpted from example/plugins/c-api/protocol_stack/protocol_stack.cc in the Traffic
Server source distribution. It demonstrates how to use TSHttpTxnClientProtocolStackGet() and
TSHttpTxnClientProtocolStackContains()
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, "Protocols:");
TSHttpTxnClientProtocolStackGet(txnp, 10, results, &count);
for (int i = 0; i < count; i++) {
TSDebug(PLUGIN_NAME, "\t%d: %s", i, results[i]);
}
const char *ret_tag = TSHttpTxnClientProtocolStackContains(txnp, "h2");
TSDebug(PLUGIN_NAME, "Stack %s HTTP/2", ret_tag != nullptr ? "contains" : "does not contain");
TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
return 0;
}
COPYRIGHT
2024, dev@trafficserver.apache.org