This is an automated email from the ASF dual-hosted git repository.
bneradt 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 ee7a5d8f48 TSMimeHdrFieldAppend doc/doxygen updates (#12458)
ee7a5d8f48 is described below
commit ee7a5d8f4815d456657853fa9992675177d73711
Author: Brian Neradt <[email protected]>
AuthorDate: Mon Aug 18 18:04:16 2025 -0500
TSMimeHdrFieldAppend doc/doxygen updates (#12458)
The doxygen for TSMimeHdrFieldAppend seemed to describe a non-existent
function. It seems like it had been this way going back to at least 8.x.
I updated the doxygen for it and, while at it, updated the Sphinx doc
for it as well.
---
.../api/functions/TSMimeHdrFieldAppend.en.rst | 9 +++++++
include/ts/ts.h | 29 +++++++++-------------
2 files changed, 21 insertions(+), 17 deletions(-)
diff --git a/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
b/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
index 3be3f8b197..cf7773a7a8 100644
--- a/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
+++ b/doc/developer-guide/api/functions/TSMimeHdrFieldAppend.en.rst
@@ -38,5 +38,14 @@ arguments which should have been obtained by a call to
:func:`TSHttpTxnClientReq
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.
+
+.. note::
+
+ If the field was found via :func:`TSMimeHdrFieldFind`, then this function
+ call is effectively a no-op. If a field with the same name already exists in
+ the header (that is, if :func:`TSMimeHdrFieldCreateNamed` was called for a
+ field name that already existed in the header), then the new field is added
+ as a duplicate field.
+
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/include/ts/ts.h b/include/ts/ts.h
index 42998a756f..34f77829a3 100644
--- a/include/ts/ts.h
+++ b/include/ts/ts.h
@@ -956,23 +956,18 @@ TSMLoc TSMimeHdrFieldGet(TSMBuffer bufp, TSMLoc hdr, int
idx);
TSMLoc TSMimeHdrFieldFind(TSMBuffer bufp, TSMLoc hdr, const char *name, int
length);
/**
- Returns the TSMLoc location of a specified MIME field from within
- the MIME header located at 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 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 TSMLoc handle with a call
- to TSHandleMLocRelease().
-
- @param bufp marshal buffer containing the MIME field.
- @param hdr location of the MIME header containing the field.
- @param retrieved_str specifies the field to retrieve. Must be
- one of the predefined field names of the form TS_MIME_FIELD_XXX.
- @return location of the requested MIME field. If the requested
- field cannot be found, returns 0.
+ Appends a MIME field to a header. The field is typically newly created via
+ @a TSMimeHdrFieldCreateNamed. If the field was found via @a
+ TSMimeHdrFieldFind and it existed already in the header, then this function
+ call is effectively a no-op. If the field is newly created via @a
+ TSMimeHdrFieldCreateNamed and a field with the same name already exists in
+ the header, then the new field is added as a duplicate field.
+
+ @param bufp marshal buffer containing the MIME header. Must be modifiable.
+ @param hdr location of the MIME header to append the field to.
+ @param field location of the MIME field to append to the header.
+ @return TS_SUCCESS if the field was successfully appended to the header,
+ TS_ERROR if the operation failed (e.g., if the buffer is read-only).
*/
TSReturnCode TSMimeHdrFieldAppend(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
