trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject git commit: Add man page for TSHttpParser
Date Thu, 14 Feb 2013 18:19:33 GMT
Updated Branches:
  refs/heads/master d77229440 -> eba0282f8


Add man page for TSHttpParser


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/eba0282f
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/eba0282f
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/eba0282f

Branch: refs/heads/master
Commit: eba0282f8cf721ed903249823b9400373ae1aba8
Parents: d772294
Author: James Peach <jpeach@apache.org>
Authored: Thu Feb 14 10:19:05 2013 -0800
Committer: James Peach <jpeach@apache.org>
Committed: Thu Feb 14 10:19:05 2013 -0800

----------------------------------------------------------------------
 doc/Makefile.am              |    1 +
 doc/sdk/TSHttpParserCreate.3 |  128 +++++++++++++++++++++++++++++++++++++
 proxy/api/ts/ts.h.in         |   68 ++++++++++----------
 3 files changed, 162 insertions(+), 35 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/eba0282f/doc/Makefile.am
----------------------------------------------------------------------
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2afb98a..256aefb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -83,6 +83,7 @@ man3_MANS = \
   sdk/TSAPI.3 \
   sdk/TSDebug.3 \
   sdk/TSHttpHookAdd.3 \
+  sdk/TSHttpParserCreate.3 \
   sdk/TSIOBufferCreate.3 \
   sdk/TSInstallDirGet.3 \
   sdk/TSMBufferCreate.3 \

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/eba0282f/doc/sdk/TSHttpParserCreate.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSHttpParserCreate.3 b/doc/sdk/TSHttpParserCreate.3
new file mode 100644
index 0000000..f517045
--- /dev/null
+++ b/doc/sdk/TSHttpParserCreate.3
@@ -0,0 +1,128 @@
+.\"  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 .\"
+.Dd February 14, 2013
+.Dt TSHttpParserCreate 3ts TSAPI
+.Sh NAME
+.Nm TSHttpParserCreate,
+.Nm TSHttpHdrParseReq,
+.Nm TSHttpHdrParseResp,
+.Nm TSHttpParserClear,
+.Nm TSHttpParserDestroy
+.Nd Parse HTTP headers from memory buffers
+.Sh LIBRARY
+Apache Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+.Ft "TSHttpParser"
+.Fo TSHttpParserCreate
+.Fa "void"
+.Fc
+.Ft "TSParseResult"
+.Fo TSHttpHdrParseReq
+.Fa "TSHttpParser parser"
+.Fa "TSMBuffer bufp"
+.Fa "TSMLoc offset"
+.Fa "const char** start"
+.Fa "const char* end"
+.Fc
+.Ft "TSParseResult"
+.Fo TSHttpHdrParseResp
+.Fa "TSHttpParser parser"
+.Fa "TSMBuffer bufp"
+.Fa "TSMLoc offset"
+.Fa "const char** start"
+.Fa "const char* end"
+.Fc
+.Ft "void"
+.Fo TSHttpParserClear
+.Fa "TSHttpParser parser"
+.Fc
+.Ft "void"
+.Fo TSHttpParserDestroy
+.Fa "TSHttpParser parser"
+.Fc
+.Sh DESCRIPTION
+.Fn TSHttpParserCreate
+creates an HTTP parser object. The parser's data structure contains
+information about the header being parsed. A single HTTP parser can
+be used multiple times, though not simultaneously. Before being
+used again, the parser must be cleared by calling
+.Fn TSHttpParserClear .
+
+.Pp
+.Fn TSHttpHdrParseReq
+parses an HTTP request header. The HTTP header
+.Fa offset
+must already be created, and must reside inside the marshal buffer
+.Fa bufp .
+The
+.Fa start
+argument points to the current position of the string
+buffer being parsed and the
+.Fa end
+argument points to one byte after the end of the buffer to be parsed.
+On return,
+.Fa start
+is modified to point past the last character parsed.
+.Pp
+It is possible to parse an HTTP request header a single byte at a
+time using repeated calls to TSHttpHdrParseReq. As long as an error
+does not occur, the TSHttpHdrParseReq function will consume that
+single byte and ask for more.
+.Fn TSHttpHdrParseReq
+should be called after
+.Fa TS_HTTP_READ_REQUEST_HDR_HOOK .
+
+.Pp
+.Fn TSHttpHdrParseResp
+operates in the same manner as
+.Fn TSHttpHdrParseReq
+except it parses an HTTP response header. It should be called after
+.Fa TS_HTTP_READ_RESPONSE_HDR_HOOK .
+
+.Pp
+.Fn TSHttpParserDestroy
+clears the specified HTTP parser so it may be used again.
+.Pp
+.Fn TSHttpParserDestroy
+destroys the TSHttpParser object pointed to by
+.Fa parser .
+The 
+.Fa parser
+pointer must not be NULL.
+.Fn 
+.Sh RETURN VALUES
+.Fn TSHttpHdrParseReq
+and
+.Fn TSHttpHdrParseResp
+both return a TSParseResult value.
+.Fa TS_PARSE_ERROR
+is returned on error,
+.Fa TS_PARSE_CONT 
+is returned if parsing of the header stopped because the end of the buffer was
+reached, and
+.Fa TS_PARSE_DONE
+or
+.Fa TS_PARSE_OK
+when a \\r\\n\\r\\n pattern is encountered, indicating the end of the header.
+.Sh BUGS
+The distinction between the
+.Fa TS_PARSE_DONE
+and
+.Fa TS_PARSE_OK
+is not well-defined. Plugins should expect both status codes and treat them
+equivalently.
+.Sh SEE ALSO
+.Xr TSAPI 3ts

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/eba0282f/proxy/api/ts/ts.h.in
----------------------------------------------------------------------
diff --git a/proxy/api/ts/ts.h.in b/proxy/api/ts/ts.h.in
index 213b4e8..f1d5982 100644
--- a/proxy/api/ts/ts.h.in
+++ b/proxy/api/ts/ts.h.in
@@ -2022,6 +2022,39 @@ extern "C"
   tsapi void TSHttpParserClear(TSHttpParser parser);
   tsapi void TSHttpParserDestroy(TSHttpParser parser);
 
+  /**
+      Parses an HTTP request header. The HTTP header must have already
+      been created, and must reside inside the marshal buffer bufp.
+      The start argument points to the current position of the string
+      buffer being parsed. The end argument points to one byte after the
+      end of the buffer to be parsed. On return, TSHttpHdrParseReq()
+      modifies start to point past the last character parsed.
+
+      It is possible to parse an HTTP request header a single byte at
+      a time using repeated calls to TSHttpHdrParseReq(). As long as
+      an error does not occur, the TSHttpHdrParseReq() function will
+      consume that single byte and ask for more.
+
+      @param parser parses the HTTP header.
+      @param bufp marshal buffer containing the HTTP header to be parsed.
+      @param offset location of the HTTP header within bufp.
+      @param start both an input and output. On input, it points to the
+        current position of the string buffer being parsed. On return,
+        start is modified to point past the last character parsed.
+      @param end points to one byte after the end of the buffer to be parsed.
+      @return status of the parse:
+        - TS_PARSE_ERROR means there was a parsing error.
+        - TS_PARSE_DONE means that the end of the header was reached
+          (the parser encountered a "\r\n\r\n" pattern).
+        - TS_PARSE_CONT means that parsing of the header stopped because
+          the parser reached the end of the buffer (large headers can
+          span multiple buffers).
+
+   */
+  tsapi TSParseResult TSHttpHdrParseReq(TSHttpParser parser, TSMBuffer bufp, TSMLoc offset,
const char** start, const char* end);
+
+  tsapi TSParseResult TSHttpHdrParseResp(TSHttpParser parser, TSMBuffer bufp, TSMLoc offset,
const char** start, const char* end);
+
   tsapi TSMLoc TSHttpHdrCreate(TSMBuffer bufp);
 
   /**
@@ -2057,41 +2090,6 @@ extern "C"
 
   tsapi void TSHttpHdrPrint(TSMBuffer bufp, TSMLoc offset, TSIOBuffer iobufp);
 
-  /**
-      Parses an HTTP request header. The HTTP header must have already
-      been created, and must reside inside the marshal buffer bufp.
-      The start argument points to the current position of the string
-      buffer being parsed. The end argument points to one byte after the
-      end of the buffer to be parsed. On return, TSHttpHdrParseReq()
-      modifies start to point past the last character parsed.
-
-      It is possible to parse an HTTP request header a single byte at
-      a time using repeated calls to TSHttpHdrParseReq(). As long as
-      an error does not occur, the TSHttpHdrParseReq() function will
-      consume that single byte and ask for more.
-
-      @param parser parses the HTTP header.
-      @param bufp marshal buffer containing the HTTP header to be parsed.
-      @param offset location of the HTTP header within bufp.
-      @param start both an input and output. On input, it points to the
-        current position of the string buffer being parsed. On return,
-        start is modified to point past the last character parsed.
-      @param end points to one byte after the end of the buffer to be parsed.
-      @return status of the parse:
-        - TS_PARSE_ERROR means there was a parsing error.
-        - TS_PARSE_DONE means that the end of the header was reached
-          (the parser encountered a "\r\n\r\n" pattern).
-        - TS_PARSE_CONT means that parsing of the header stopped because
-          the parser reached the end of the buffer (large headers can
-          span multiple buffers).
-
-   */
-  tsapi TSParseResult TSHttpHdrParseReq(TSHttpParser parser, TSMBuffer bufp, TSMLoc offset,
const char** start,
-                                        const char* end);
-
-  tsapi TSParseResult TSHttpHdrParseResp(TSHttpParser parser, TSMBuffer bufp, TSMLoc offset,
const char** start,
-                                         const char* end);
-
   tsapi int TSHttpHdrLengthGet(TSMBuffer bufp, TSMLoc offset);
 
   tsapi TSHttpType TSHttpHdrTypeGet(TSMBuffer bufp, TSMLoc offset);


Mime
View raw message