> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs
> <shinr...@network-geographics.com> wrote:
>
>
>
> On 9/9/2016 12:01 PM, James Peach wrote:
>>> 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 was assuming that something was being returned via the tag argument since
> we are passing in a pointer to a pointer.
It takes a nul-terminated array of tags right?
>
>>
>>> 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.
>>>>
>>>>
>>>>
>>>
>
>
