doc: convert TSMBufferCreate(3) to sphinx
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/4b14cee2 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/4b14cee2 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/4b14cee2 Branch: refs/heads/3.3.x Commit: 4b14cee2f6b68e9579ef3d2ed9b206e798da5b9f Parents: cdddf8b Author: James Peach <[email protected]> Authored: Thu Aug 1 10:29:16 2013 -0700 Committer: James Peach <[email protected]> Committed: Thu Aug 1 10:29:16 2013 -0700 ---------------------------------------------------------------------- doc/conf.py | 1 + doc/reference/api/TSMBufferCreate.en.rst | 95 +++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4b14cee2/doc/conf.py ---------------------------------------------------------------------- diff --git a/doc/conf.py b/doc/conf.py index f8b7ad8..922ee96 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -219,6 +219,7 @@ man_pages = [ ('reference/api/TSHttpTxnMilestoneGet.en', 'TSHttpTxnMilestoneGet', u'Get a specified milestone timer value for the current transaction', None, u'3ts'), ('reference/api/TSIOBufferCreate.en', 'TSIOBufferCreate', u'Traffic Server IO buffer API', None, u'3ts'), ('reference/api/TSInstallDirGet.en', 'TSInstallDirGet', u'Return Traffic Server installation directories', None, u'3ts'), + ('reference/api/TSMBufferCreate.en', 'TSMBufferCreate', u'Traffic Server marshall buffer API', 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/4b14cee2/doc/reference/api/TSMBufferCreate.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSMBufferCreate.en.rst b/doc/reference/api/TSMBufferCreate.en.rst new file mode 100644 index 0000000..600e570 --- /dev/null +++ b/doc/reference/api/TSMBufferCreate.en.rst @@ -0,0 +1,95 @@ +.. 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. + +.. default-domain:: c + +=============== +TSMBufferCreate +=============== + +Synopsis +======== + +`#include <ts/ts.h>` + +.. function:: TSMBuffer TSMBufferCreate(void) +.. function:: TSReturnCode TSMBufferDestroy(TSMBuffer bufp) +.. function:: TSReturnCode TSHandleMLocRelease(TSMBuffer bufp, TSMLoc parent, TSMLoc mloc) + +Description +=========== + +The marshal buffer or :type:`TSMBuffer` is a heap data structure that stores +parsed URLs, MIME headers and HTTP headers. You can allocate new objects +out of marshal buffers, and change the values within the marshal buffer. +Whenever you manipulate an object, you require the handle to the object +(:type:`TSMLoc`) and the marshal buffer containing the object (:type:`TSMBuffer`). + +Any marshal buffer fetched by :func:`TSHttpTxn*Get` will be used by other parts +of the system. Be careful not to destroy these shared, transaction marshal buffers. + +:func:`TSMBufferCreate` creates a new marshal buffer and initializes +the reference count. :func:`TSMBufferDestroy` Ignores the reference +count and destroys the marshal buffer bufp. The internal data buffer +associated with the marshal buffer is also destroyed if the marshal +buffer allocated it. + +:func:`TSHandleMLocRelease` Releases the :type:`TSMLoc` mloc created +from the :type:`TSMLoc` parent. If a :type:`TSMLoc` is obtained from +a transaction, it does not have a parent :type:`TSMLoc`. Use the +the constant :data:`TS_NULL_MLOC` as its parent. + +Return values +============= + +:func:`TSMBufferDestroy` and :func:`TSHandleMLocRelease` return +:data:`TS_SUCCESS` on success, or :data:`TS_ERROR` on failure. +:func:`TSMBufferCreate` returns the new :type:`TSMBuffer`. + +Examples +======== + +:: + + #include <ts/ts.h> + + static void + copyResponseMimeHdr (TSCont pCont, TSHttpTxn pTxn) + { + TSMBuffer respHdrBuf, tmpBuf; + TSMLoc respHttpHdrLoc, tmpMimeHdrLoc; + + if (!TSHttpTxnClientRespGet(pTxn, &respHdrBuf, &respHttpHdrLoc)) { + TSError("couldn't retrieve client response header0); + TSHandleMLocRelease(respHdrBuf, TS_NULL_MLOC, respHttpHdrLoc); + goto done; + } + + tmpBuf = TSMBufferCreate(); + tmpMimeHdrLoc = TSMimeHdrCreate(tmpBuf); + TSMimeHdrCopy(tmpBuf, tmpMimeHdrLoc, respHdrBuf, respHttpHdrLoc); + TSHandleMLocRelease(tmpBuf, TS_NULL_MLOC, tmpMimeHdrLoc); + TSHandleMLocRelease(respHdrBuf, TS_NULL_MLOC, respHttpHdrLoc); + TSMBufferDestroy(tmpBuf); + + done: + TSHttpTxnReenable(pTxn, TS_EVENT_HTTP_CONTINUE); + } + +See also +======== + +:manpage:`TSAPI(3ts)`
