[
https://issues.apache.org/jira/browse/TS-4703?focusedWorklogId=28794&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-28794
]
ASF GitHub Bot logged work on TS-4703:
--------------------------------------
Author: ASF GitHub Bot
Created on: 12/Sep/16 16:44
Start Date: 12/Sep/16 16:44
Worklog Time Spent: 10m
Work Description: Github user jpeach commented on a diff in the pull
request:
https://github.com/apache/trafficserver/pull/1007#discussion_r78408588
--- Diff: doc/reference/api/TSClientProtocolStack.en.rst ---
@@ -0,0 +1,79 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed
+ with this work for additional information regarding copyright
+ ownership. The ASF licenses this file to you under the Apache
+ License, Version 2.0 (the "License"); you may not use this file
+ except in compliance with the License. You may obtain a copy of
+ the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
+ permissions and limitations under the License.
+
+
+.. 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.
--- End diff --
Can you please line wrap this to something reasonable? 80 - 100?
Issue Time Tracking
-------------------
Worklog Id: (was: 28794)
Time Spent: 4h 50m (was: 4h 40m)
> Adds an API call to retrieve transaction protocol
> -------------------------------------------------
>
> Key: TS-4703
> URL: https://issues.apache.org/jira/browse/TS-4703
> Project: Traffic Server
> Issue Type: Improvement
> Components: TS API
> Reporter: Petar Penkov
> Assignee: Susan Hinrichs
> Fix For: 7.0.0
>
> Time Spent: 4h 50m
> Remaining Estimate: 0h
>
> It would be useful if there was a way to retrieve the underlying protocol for
> a given transaction through the tsapi at the very least for plugin logging
> purposes. This can be achieved with a very simple method since this
> information is already available internally.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
