This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new 395a742  Doc: Add documentation for MIME header plugin API functions.
395a742 is described below

commit 395a74291324d328919bebea8f09628c59be8a0c
Author: Alan M. Carroll <a...@apache.org>
AuthorDate: Fri Aug 4 19:12:27 2017 -0500

    Doc: Add documentation for MIME header plugin API functions.
---
 .../api/functions/TSMimeHdrFieldAppend.en.rst       | 21 +++++++--------------
 .../api/functions/TSMimeHdrFieldCreate.en.rst       | 18 +++++++++++++++++-
 2 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst 
b/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
index 24038da..7690fa8 100644
--- a/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
+++ b/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
@@ -31,17 +31,10 @@ Synopsis
 Description
 ===========
 
-Returns the :c:type:`TSMLoc` location of a specified MIME field from
-within the MIME header located at :arg:`hdr`.
-
-The retrieved_str parameter specifies which field to retrieve.  For
-each MIME field in the MIME header, a pointer comparison is done
-between the field name and retrieved_str.  This is a much quicker
-retrieval function than :c:func:`TSMimeHdrFieldFind` since it obviates
-the need for a string comparison.  However, retrieved_str must be one
-of the predefined field names of the form ``TS_MIME_FIELD_XXX``
-for the call to succeed.  Release the returned :c:type:`TSMLoc` handle
-with a call to :c:func:`TSHandleMLocRelease`.
-
-.. XXX The above is surely from the documentation of another function. Confirm
-       and remove from here (or relocate to the appropriate function's doc).
+Attaches a MIME :arg:`field` to a header. The header is represented by the 
:arg:`bufp` and :arg:`hdr`
+arguments which should have been obtained by a call to 
:func:`TSHttpTxnClientReqGet` or similar. If
+the field in :arg:`field` was created by calling 
:func:`TSMimeHdrFieldCreateNamed` the same
+:arg:`bufp` and :arg:`hdr` passed to that should be passed to this function.
+
+Returns :code:`TS_SUCCESS` if the :arg:`field` was attached to the header, 
:code:`TS_ERROR` if it
+was not. Fields cannot be attached to read only headers.
diff --git a/doc/developer-guide/api/functions/TSMimeHdrFieldCreate.en.rst 
b/doc/developer-guide/api/functions/TSMimeHdrFieldCreate.en.rst
index de5c74a..8373a07 100644
--- a/doc/developer-guide/api/functions/TSMimeHdrFieldCreate.en.rst
+++ b/doc/developer-guide/api/functions/TSMimeHdrFieldCreate.en.rst
@@ -26,7 +26,23 @@ Synopsis
 
 `#include <ts/ts.h>`
 
-.. function:: TSReturnCode TSMimeHdrFieldCreate(TSMBuffer bufp, TSMLoc hdr, 
TSMLoc * locp)
+.. function:: TSReturnCode TSMimeHdrFieldCreate(TSMBuffer bufp, TSMLoc hdr, 
TSMLoc * out)
+.. function:: TSReturnCode TSMimeHdrFieldCreateNamed(TSMBuffer bufp, TSMLoc 
hdr, const char * name, int name_len, TSMLoc * out)
 
 Description
 ===========
+
+These functions create MIME fields in a MIME header. The header is specified 
by the combination of
+the buffer :arg:`bufp` and a location :arg:`hdr`. The header must be either 
created such as by
+:func:`TSMimeHdrCreate` or be an existing header found via a function such as 
:func:`TSHttpTxnClientReqGet`.
+
+:func:`TSMimeHdrFieldCreate` creates a completely empty field which must be 
named before being used
+in a header, usually via :func:`TSMimeHdrFieldNameSet`. It is almost always 
more convenient to use
+:func:`TSMimeHdrFieldCreateNamed` which combines these two steps, creating the 
field and then
+setting the name to :arg:`name`.
+
+For both functions a reference to the new field is returned via arg:`out`.
+
+The field created is not in a header even though it is in the same buffer. It 
can be added to a
+header with :func:`TSMimeHdrFieldAppend`. The field also has no value, only a 
name. If a value is
+needed it must be added explicitly with a function such as 
:func:`TSMimeHdrFieldValueIntSet`.

-- 
To stop receiving notification emails like this one, please contact
['"commits@trafficserver.apache.org" <commits@trafficserver.apache.org>'].

Reply via email to