You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2013/02/14 19:19:33 UTC
git commit: Add man page for TSHttpParser
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 <jp...@apache.org>
Authored: Thu Feb 14 10:19:05 2013 -0800
Committer: James Peach <jp...@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);