You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Susan Hinrichs <sh...@network-geographics.com> on 2016/09/09 16:39:17 UTC
Re: TS-4703 && PR-829
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)
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.
>
>
>
Re: TS-4703 && PR-829
Posted by James Peach <jp...@apache.org>.
> On Sep 9, 2016, at 2:22 PM, Alan Carroll <so...@yahoo-inc.com.INVALID> wrote:
>
> 1.
So why the output array then?
>
>
> On Friday, September 9, 2016 1:19 PM, James Peach <jp...@apache.org> wrote:
>
>
>
>> On Sep 9, 2016, at 10:55 AM, Alan Carroll <so...@yahoo-inc.com.INVALID> wrote:
>>
>> No. I'm not completely sure what I meant when I wrote that (maybe it was a typo). My view on review was that it should be an in/out parameter where the tag (possibly just a prefix) is passed in and the actual tag found is passed back. Susan has convinced me it would be better to make split that in to two parameters, the second being optional (can be NULL). So the last arg becomes "char const* tag, char const** result" where
>> tag - the tag to search for, using an anchored prefix search.result - optional return value for the tag found (if NULL the found tag is not returned).
>
> How many results can you get?
>
>>
>>
>> On Friday, September 9, 2016 12:18 PM, James Peach <jp...@apache.org> wrote:
>>
>>
>>
>>> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs <sh...@network-geographics.com> wrote:
>>>
>>>
>>>
>>> On 9/9/2016 12:01 PM, James Peach wrote:
>>>>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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?
>
>
Re: TS-4703 && PR-829
Posted by Alan Carroll <so...@yahoo-inc.com.INVALID>.
1.
On Friday, September 9, 2016 1:19 PM, James Peach <jp...@apache.org> wrote:
> On Sep 9, 2016, at 10:55 AM, Alan Carroll <so...@yahoo-inc.com.INVALID> wrote:
>
> No. I'm not completely sure what I meant when I wrote that (maybe it was a typo). My view on review was that it should be an in/out parameter where the tag (possibly just a prefix) is passed in and the actual tag found is passed back. Susan has convinced me it would be better to make split that in to two parameters, the second being optional (can be NULL). So the last arg becomes "char const* tag, char const** result" where
> tag - the tag to search for, using an anchored prefix search.result - optional return value for the tag found (if NULL the found tag is not returned).
How many results can you get?
>
>
> On Friday, September 9, 2016 12:18 PM, James Peach <jp...@apache.org> wrote:
>
>
>
>> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs <sh...@network-geographics.com> wrote:
>>
>>
>>
>> On 9/9/2016 12:01 PM, James Peach wrote:
>>>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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?
Re: TS-4703 && PR-829
Posted by James Peach <jp...@apache.org>.
> On Sep 9, 2016, at 10:55 AM, Alan Carroll <so...@yahoo-inc.com.INVALID> wrote:
>
> No. I'm not completely sure what I meant when I wrote that (maybe it was a typo). My view on review was that it should be an in/out parameter where the tag (possibly just a prefix) is passed in and the actual tag found is passed back. Susan has convinced me it would be better to make split that in to two parameters, the second being optional (can be NULL). So the last arg becomes "char const* tag, char const** result" where
> tag - the tag to search for, using an anchored prefix search.result - optional return value for the tag found (if NULL the found tag is not returned).
How many results can you get?
>
>
> On Friday, September 9, 2016 12:18 PM, James Peach <jp...@apache.org> wrote:
>
>
>
>> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs <sh...@network-geographics.com> wrote:
>>
>>
>>
>> On 9/9/2016 12:01 PM, James Peach wrote:
>>>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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?
Re: TS-4703 && PR-829
Posted by Alan Carroll <so...@yahoo-inc.com.INVALID>.
No. I'm not completely sure what I meant when I wrote that (maybe it was a typo). My view on review was that it should be an in/out parameter where the tag (possibly just a prefix) is passed in and the actual tag found is passed back. Susan has convinced me it would be better to make split that in to two parameters, the second being optional (can be NULL). So the last arg becomes "char const* tag, char const** result" where
tag - the tag to search for, using an anchored prefix search.result - optional return value for the tag found (if NULL the found tag is not returned).
On Friday, September 9, 2016 12:18 PM, James Peach <jp...@apache.org> wrote:
> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs <sh...@network-geographics.com> wrote:
>
>
>
> On 9/9/2016 12:01 PM, James Peach wrote:
>>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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?
Re: TS-4703 && PR-829
Posted by James Peach <jp...@apache.org>.
> On Sep 9, 2016, at 10:15 AM, Susan Hinrichs <sh...@network-geographics.com> wrote:
>
>
>
> On 9/9/2016 12:01 PM, James Peach wrote:
>>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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.
>>>>
>>>>
>>>>
>>>
>
>
Re: TS-4703 && PR-829
Posted by Susan Hinrichs <sh...@network-geographics.com>.
On 9/9/2016 12:01 PM, James Peach wrote:
>> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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.
>
>> 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.
>>>
>>>
>>>
>>
Re: TS-4703 && PR-829
Posted by James Peach <jp...@apache.org>.
> On Sep 9, 2016, at 9:39 AM, Susan Hinrichs <sh...@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.
>>
>>
>>
>
>