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 ['"firstname.lastname@example.org" <email@example.com>'].