TS-2360: Update TSMimeHdrFieldValueStringGet docs
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/0c6c25e6 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/0c6c25e6 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/0c6c25e6 Branch: refs/heads/5.0.x Commit: 0c6c25e6cde89cdb66284b43fb8bcdfe4a009687 Parents: 51a9252 Author: James Peach <[email protected]> Authored: Tue Nov 19 21:29:52 2013 -0800 Committer: James Peach <[email protected]> Committed: Thu Nov 21 08:57:50 2013 -0800 ---------------------------------------------------------------------- doc/conf.py | 1 + .../api/TSMimeHdrFieldValueStringGet.en.rst | 47 ++++++++++---------- 2 files changed, 24 insertions(+), 24 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/0c6c25e6/doc/conf.py ---------------------------------------------------------------------- diff --git a/doc/conf.py b/doc/conf.py index 3eac055..0539bff 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -266,6 +266,7 @@ man_pages = [ ('reference/api/TSRemap.en', 'TSRemap', u'Traffic Server remap plugin entry points ', None, u'3ts'), ('reference/api/TSTrafficServerVersionGet.en', 'TSTrafficServerVersionGet', u'return Traffic Server version information', None, u'3ts'), ('reference/api/TSUrlCreate.en', 'TSUrlCreate', u'Traffic Server URL manipulation API', None, u'3ts'), + ('reference/api/TSMimeHdrFieldValueStringGet.en', 'TSMimeHdrFieldValueStringGet', u'Get HTTP MIME header values', None, u'3ts'), ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'), ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line', None, '8'), http://git-wip-us.apache.org/repos/asf/trafficserver/blob/0c6c25e6/doc/reference/api/TSMimeHdrFieldValueStringGet.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSMimeHdrFieldValueStringGet.en.rst b/doc/reference/api/TSMimeHdrFieldValueStringGet.en.rst index feec628..75453c7 100644 --- a/doc/reference/api/TSMimeHdrFieldValueStringGet.en.rst +++ b/doc/reference/api/TSMimeHdrFieldValueStringGet.en.rst @@ -36,30 +36,31 @@ Synopsis Description =========== -MIME headers and fields can be components of request headers, response -headers, or standalone headers created within your plugin. The various -functions here are all used to access header values of specific types, but it -is up to the caller to know if a header has appropriate semantics for the API -used. For all but :func:`TSMimeHdrFieldValueStringGet`, an appropriate data -conversion algorithm is applied to the header field string. - -All APIs takes an argument with the :type:`TSMBuffer` marshal buffer, and the -:type:`TSMLoc` for the location to headers. In addition, the required -:data:`field` argument is the locator of a specific header value, as returned -by e.g. :func:`TSMimeHdrFieldFind`. - -Within the header field, comma separated values can be retrieved with an index -(:data:`idx`) ranging from 0 to the max number of fields for this value; this -max is retrieved using :func:`TSMimeHdrFieldValuesCount`. An :data:`idx` value of +MIME headers and fields can be components of request headers, +response headers, or standalone headers created within a Traffic +Server plugin. The functions here are all used to access header +values of specific types, but it is up to the caller to know if a +header has appropriate semantics for the API used. For all but +:func:`TSMimeHdrFieldValueStringGet`, an appropriate data conversion +algorithm is applied to the header field string. + +All the APIs take a :type:`TSMBuffer` marshal buffer argument, and +a :type:`TSMLoc` argument indicating the location of the HTTP +headers. The required :data:`field` argument is the locator of a +specific header value, as returned by an accessor function such as +:func:`TSMimeHdrFieldFind`. + +Within the header field, comma-separated values can be retrieved with an index +(:data:`idx`) ranging from 0 to the maximum number of fields for this value; this +maximum is retrieved using :func:`TSMimeHdrFieldValuesCount`. An :data:`idx` value of ``-1`` has the semantics of retrieving the entire header value, regardless of -how many comma separated values there are. If a header is not comma separated, +how many comma-separated values there are. If a header is not comma-separated, an :data:`idx` of :data:`0` or :data:`-1` are the same, but the latter is -definitely preferred and recommended. - -For :func:`TSMimeHdrFieldValueStringGet`, an additional parameter can be -provided, which is populated with the length of the string returned. If this -argument is NULL, it is not derefenced and no length is returned. +preferred. +:func:`TSMimeHdrFieldValueStringGet` returns a pointer to the header +value, and populated :data:`value_len_ptr` with the length of the +value in bytes. The returned header value is not NUL-terminated. Return values ============= @@ -68,8 +69,6 @@ All functions returns the header value with a type matching the respective function name. Using :func:`TSMimeHdrFieldValueDateGet` on a header which does not have date-time semantics always returns :data:`0`. - - Examples ======== @@ -109,4 +108,4 @@ This examples show how to retrieve and copy a specific header. See also ======== -:manpage:`TSAPI(3ts)`, :manpage:`TSMBufferCreate(3ts)`, :manpage:`TSMimeHdrFieldValuesCount` +:manpage:`TSAPI(3ts)`, :manpage:`TSMBufferCreate(3ts)`, :manpage:`TSMimeHdrFieldValuesCount(3ts)`
