> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <shinr...@network-geographics.com>
> wrote:
>
> I'd like to propose a slight tweak for TSHttpTxnClientProtocolStackContains
> and TSHttpSsnClientProtocolStackContains
>
> Replace the tag argument with two explicit input and output arguments, e.g.
>
> int TSHttpTxnClientProtocolStackContains(TSHttpTxn txnp, char const
> *contains_tag, char const **specific_tag_ptr)
The TSHttpTxnClientProtocolStackContains didn't mention anything about any
output?
>
> I think having separate arguments for input and output arguments is clearer.
> Also if I don't care about getting a pointer back to the specific tag string
> that ATS uses internally I don't have to declare additional variables to make
> this call, e.g.
>
> if (TXHttpTxnClientProtocolStackContains(txnp, "h2", NULL)) {
> // Do HTTP/2 stuff
> }
>
> On 8/20/2016 10:20 AM, Alan Carroll wrote:
>> After discussions with Leif and Bryan, here is an updated proposal. This
>> would subsume Oliver Goodman's API, which would be simply calling this and
>> looking for / passing 'ws' as the protocol tag.
>> There is an unresolved point, which is the exact stack returned for a HTTP/2
>> connection.
>>
>> .. include:: ../../../common.defs
>>
>> .. default-domain:: c
>>
>> TSClientProtocolStack
>> *********************
>>
>> Synopsis
>> ========
>>
>> `#include <ts/ts.h>`
>>
>> .. function:: TSReturnCode TSHttpTxnClientProtocolStackGet(TSHttpTxn txnp,
>> int n, char const** result, int* actual)
>>
>> .. function:: TSReturnCode TSHttpSsnClientProtocolStackGet(TSHttpSsn ssnp,
>> int n, char const** result, int* actual)
>>
>> .. function:: int TSHttpTxnClientProtocolStackContains(TSHttpTxn txnp, char
>> const** tag)
>>
>> .. function:: int TSHttpSsnClientProtocolStackContains(TSHttpSsn ssnp, char
>> const** tag)
>>
>> .. function:: char const* TSNormalizedProtocolTag(char const* tag)
>>
>> .. function:: char const* TSRegisterProtocolTag(char const* tag)
>>
>> Description
>> ===========
>>
>> These functions are used to explore the protocol stack of the client (user
>> agent) connection to |TS|. The functions
>> :func:`TSHttpTxnClientProtocolStackGet` and
>> :func:`TSHttpSsnClientProtocolStackGet` can be used to retrieve the entire
>> protocol stack for the user agent connection.
>> :func:`TSHttpTxnClientProtocolStackContains` and
>> :func:`TSHttpSsnClientProtocolStackContains` will check for a specific
>> protocol :arg:`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.
>> :func:`TSNormalizedProtocolTag` will return this character pointer for a
>> specific :arg:`tag`. A return value of :const:`NULL` indicates the provided
>> :arg:`tag` is not registered as a known protocol tag.
>> :func:`TSRegisterProtocolTag` registers the :arg:`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 :func:`TSHttpTxnClientProtocolStackGet` and
>> :func:`TSHttpSsnClientProtocolStackGet` these values are placed in the array
>> :arg:`result`. :arg:`count` is the maximum number of elements of
>> :arg:`result` that may be modified by the function call. If :arg:`actual` is
>> not :const:`NULL` then the actual number of elements in the protocol stack
>> will be returned. If this is equal or less than :arg:`count` then all
>> elements were returned. If it is larger then some layers were omitted from
>> :arg:`result`. If the full stack is required :arg:`actual` can be used to
>> resize :arg:`result` to be sufficient to hold all of the elements and the
>> function called again with updated :arg:`count` and :arg:`result`. In
>> practice the maximum number of elements will is almost certain to be less
>> than 10 which therefore should suffice. These functions return
>> :const:`TS_SUCCESS` on success and :const:`TS_ERROR` on failure which should
>> only occurr if :arg:`txnp` or :arg:`ssnp` are invalid.
>>
>> The :func:`TSHttpTxnClientProtocolStackContains` and
>> :func:`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 0 if the
>> protocol :arg:`tag` is not present, non-zero if it is present. The strings
>> are matched with an anchor prefix search, as with debug tags. For instance
>> if :arg:`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 |TS|.
>>
>> =========== =========
>> 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
>> TCP tcp
>> UDP udp
>> IPv4 ipv4
>> IPv6 ipv6
>> QUIC quic
>> =========== =========
>>
>> .. note::
>> What should HTTP/2 connections return as the top protocol? There are
>> several options
>> * "http/1.1,h2"
>> * "h2"
>> * "http/1.1,h2" for transctions and "h2" for sessions.
>>
>>
>>
>
>
