Provided by: trafficserver-dev_7.1.2+ds-3_amd64 
NAME
TSClientProtocolStack - TSClientProtocolStack API function
SYNOPSIS
#include <ts/ts.h>
TSReturnCode TSHttpTxnClientProtocolStackGet(TSHttpTxn txnp, int n, char const** result,
int* actual)
TSReturnCode TSHttpSsnClientProtocolStackGet(TSHttpSsn ssnp, int n, char const** result,
int* actual)
char const* TSHttpTxnClientProtocolStackContains(TSHttpTxn txnp)
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 the client (user agent)
connection to Traffic Server. The functions TSHttpTxnClientProtocolStackGet() and
TSHttpSsnClientProtocolStackGet() can be used to retrieve the entire protocol stack for
the user agent connection. TSHttpTxnClientProtocolStackContains() and
TSHttpSsnClientProtocolStackContains() 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() and TSHttpSsnClientProtocolStackGet() 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 will 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 occurr if txnp or ssnp are invalid.
The TSHttpTxnClientProtocolStackContains() and TSHttpSsnClientProtocolStackContains()
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/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 = (TSHttpTxn)edata;
const char *results[10];
int count = 0;
TSDebug(DEBUG_TAG, "Protocols:");
TSHttpTxnClientProtocolStackGet(txnp, 10, results, &count);
for (int i = 0; i < count; i++) {
TSDebug(DEBUG_TAG, "\t%d: %s", i, results[i]);
}
const char *ret_tag = TSHttpTxnClientProtocolStackContains(txnp, "h2");
TSDebug(DEBUG_TAG, "Stack %s HTTP/2", ret_tag != nullptr ? "contains" : "does not contain");
TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
return 0;
}
COPYRIGHT
2018, dev@trafficserver.apache.org