You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2011/02/06 02:36:10 UTC
svn commit: r1067571 - in
/trafficserver/site/branches/ats-cms/content/docs/trunk: ./ sdk/http-headers/
sdk/http-headers/guide-to-trafficserver-http-header-system/
sdk/mutex-guide/ sdk/sample-source-code/
Author: igalic
Date: Sun Feb 6 01:36:09 2011
New Revision: 1067571
URL: http://svn.apache.org/viewvc?rev=1067571&view=rev
Log:
Done with http-headers, mutext guide and the Sampe Source code chapters.
Modified:
trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/index.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/http-headers.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/index.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/marshal-buffers.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/mime-headers.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/urls.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/mutex-guide/index.en.mdtext
trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/sample-source-code/index.en.mdtext
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS Sun Feb 6 01:36:09 2011
@@ -60,15 +60,14 @@ cache-plugin -- igalic
http-hooks-and-transactions -- igalic
misc-interface-guide -- igalic
http-headers -- igalic
-mutex-guide
+mutex-guide -- igalic
continuations
plugin-configurations
actions-guide
io-guide
plugin-management
-preface -- igalic
-remap-plugin -- igalic
-sample-source-code
+adding-statistics
+sample-source-code --igalic
troubleshooting-tips
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,36 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+
+[Prev](../guide-to-trafficserver-http-header-system) - Guide to Traffic Server HTTP Header System
+
+MIME Fields Always Belong to an Associated MIME Header - [Next](mime-fields-always-belong-to-an-associated-mime-header)
+
+### Duplicate MIME Fields Are Not Coalesced ### {#DuplicateMIMEFieldsAreNotCoalesced}
+
+MIME headers can contain more than one MIME field with the same name. Earlier
+versions of Traffic Server joined multiple fields with the same name into one
+field with composite values. This behavior came at a performance cost and caused
+interoperability problems with older clients and servers. Therefore, this version
+of Traffic Server does not coalesce duplicate fields.
+
+Properly-behaving plugins should check for the presence of duplicate fields
+and then iterate over the duplicate fields via [`TSMimeHdrFieldNextDup`](link/to/doxygen).
+
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/index.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/index.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/index.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,56 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+
+[Prev](..) - HTTP Headers
+
+Duplicate MIME Fields Are Not Coalesced - [Next](duplicate-mime-fields-are-not-coalesced)
+
+## Guide to Traffic Server HTTP Header System ## {#GuideTSHTTPHeaderSystem}
+
+### No Null-Terminated Strings ### {#NoNull-TerminatedStrings}
+
+It's not safe to assume that string data contained in marshal buffers (such
+as URLs and MIME fields) is stored in null-terminated string copies. Therefore,
+your plugins should always use the length parameter when retrieving or manipulating
+these strings. You **cannot** pass in `NULL` for string-length return values;
+string values returned from marshall buffers are not null-terminated. If you
+need a null-terminated value, then use `TSstrndup` to automatically null-terminate
+a string. The strings that come back and are not null-terminated **cannot**
+be passed into the common `str*()` routines
+
+![[Note]](/images/docbook/note.png)
+
+**Note**
+
+Values returned from a marshall buffer can be `NULL`, which means the field
+or object requested does not exist.
+
+For example (from the `blacklist-1` sample):
+
+ :::c
+ char *host_string;
+ int host_length;
+ host_string = TSUrlHostGet (bufp, url_loc, &host_length);
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host_string, sites[i], host_length) == 0) {
+ ...
+ }
+
+See the sample plugins for additional examples.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,67 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+
+[Prev](duplicate-mime-fields-are-not-coalesced) - Duplicate MIME Fields Are Not Coalesced
+
+Release Marshal Buffer Handles - [Next](release-marshal-buffer-handles)
+
+### MIME Fields Always Belong to an Associated MIME Header ### {#MIMEFieldsAlwaysBelonganAssociatedMIMEHeader}
+
+When using Traffic Server, you cannot create a new MIME field without an associated
+MIME header or HTTP header; MIME fields are always seen as part of a MIME header
+or HTTP header.
+
+To use a MIME field, you must specify the MIME header or HTTP header to which
+it belongs - this is called the field's **parent header**. The `TSMimeField*`
+functions in older versions of the SDK have been deprecated, as they do not
+require the parent header as inputs. The current version of Traffic Server
+uses new functions, the `**TSMimeHdrField***` series, which require you to
+specify the location of the parent header along with the location of the MIME
+field. For every deprecated `TSMimeField*` function, there is a new, preferred
+`TSMimeHdrField*` function. Therefore, you should use the `**TSMimeHdrField***`
+functions instead of the deprecated `TSMimeField*` series. Examples are provided
+below.
+
+Instead of:
+
+ :::c
+ TSMLoc TSMimeFieldCreate (TSMBuffer bufp)
+
+You should use:
+
+ :::c
+ TSMLoc TSMimeHdrFieldCreate (TSMBuffer bufp, TSMLoc hdr)
+
+Instead of:
+
+ :::c
+ void TSMimeFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_offset,
+ TSMBuffer src_bufp, TSMLoc src_offset)
+
+You should use:
+
+ :::c
+ void TSMimeHdrFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_hdr,
+ TSMLoc dest_field, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc
+ src_field)
+
+In the `TSMimeHdrField*` function prototypes, the `TSMLoc` field corresponds
+to the `TSMLoc` offset used the deprecated `TSMimeField*` functions (see
+the discussion of parent `TSMLoc` in the following section).
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,82 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](mime-fields-always-belong-to-an-associated-mime-header) - MIME Fields Always Belong to an Associated MIME Header
+
+Marshall Buffers - [Next](../marshal-buffers)
+
+### Release Marshal Buffer Handles ### {#ReleaseMarshalBufferHandles}
+
+When you fetch a component object or create a new object, you get back a
+handle to the object location. The handle is either an `TSMLoc` for an object
+location or `char *` for a string location. You can manipulate the object
+through these handles, but when you are finished you need to release the
+handle to free up system resources.
+
+The general guideline is to release all `TSMLoc` and string handles you retrieve.
+The one exception is the string returned by `TSUrlStringGet`, which must be
+freed by a call to `TSfree`.
+
+The handle release functions expect three arguments: the marshal buffer containing
+the data, the location of the parent object, and the location of the object
+to be released. The parent location is usually clear from the creation of the
+`TSMLoc` or string. For example, if your plugin had the following calls:
+
+ ::::c
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ host_string = TSUrlHostGet (bufp, url_loc, &host_length);
+
+then your plugin would have to call:
+
+ ::::c
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+
+If an `TSMLoc` is obtained from a transaction, then it does not have a parent
+`TSMLoc`. Use the null `TSMLoc` constant `TS_NULL_MLOC` as its parent. For
+example, if your plugin calls:
+
+ ::::c
+ TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc);
+
+then you must release `hdr_loc` with:
+
+ ::::c
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+You need to use `TS_NULL_MLOC` to release any `TSMLoc` handles retrieved
+by the `TSHttpTxn*Get` functions.
+
+Here's an example using a new `TSMimeHdrField` function:
+
+ ::::c
+ TSHttpTxnServerRespGet( txnp, &resp_bufp, &resp_hdr_loc );
+ new_field_loc = TSMimeHdrFieldCreate (resp_bufp, resp_hdr_loc);
+ TSHandleMLocRelease ( resp_bufp, resp_hdr_loc, new_field_loc);
+ TSHandleMLocRelease ( resp_bufp, TS_NULL_MLOC, resp_hdr_loc);
+
+See the sample plugins for many more examples.
+
+![[Tip]](/images/docbook/tip.png)
+
+**Tip**
+
+You should release handles before reenabling the HTTP transaction. In other
+words, call `TSHandleMLocRelease` before `TSHttpTxnReenable`.
+
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/http-headers.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/http-headers.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/http-headers.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/http-headers.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,181 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+
+[Prev](marshal-buffers) - Marshal Buffers
+
+URLs - [Next](urls)
+
+## HTTP Headers ## {#HTTPHeaders}
+
+The Traffic Server API HTTP header functions enable you to work with HTTP header
+data stored in marshal buffers.
+
+
+The HTTP header data structure is a parsed version of the HTTP header defined
+in the HTTP protocol specification. An HTTP header is composed of a request
+or response line followed by zero or more MIME fields. In fact, an HTTP header
+is a subclass of a MIME header; all of the MIME header routines operate on
+HTTP headers.
+
+
+An HTTP **request line** is composed of a method, a URL, and version. A **response
+line** is composed of a version, status code, and reason phrase. See [About
+HTTP Headers ](../http-headers#AboutHTTPHeaders) for additional details and
+examples.
+
+To facilitate fast comparisons and reduce storage size, Traffic Server defines
+several pre-allocated method names. These names correspond to the methods defined
+in the HTTP 1.1 specification
+
+
+`TS_HTTP_METHOD_CONNECT`
+: "CONNECT"
+
+`TS_HTTP_METHOD_DELETE`
+: "DELETE"
+
+`TS_HTTP_METHOD_GE`
+: "GET"
+
+`TS_HTTP_METHOD_HEAD`
+: "HEAD"
+
+`TS_HTTP_METHOD_ICP_QUERY`
+: "ICP_QUERY"
+
+`TS_HTTP_METHOD_OPTIONS`
+: "OPTIONS"
+
+`TS_HTTP_METHOD_POST`
+: "POST"
+
+`TS_HTTP_METHOD_PURGE`
+: "PURGE"
+
+`TS_HTTP_METHOD_PUT`
+: "PUT"
+
+`TS_HTTP_METHOD_TRACE`
+: "TRACE"
+
+
+Traffic Server also defines several common values that appear in HTTP headers.
+
+`TS_HTTP_VALUE_BYTES`
+: "bytes"
+
+`TS_HTTP_VALUE_CHUNKED`
+: "chunked"
+
+`TS_HTTP_VALUE_CLOSE`
+: "close"
+
+`TS_HTTP_VALUE_COMPRESS`
+: "compress"
+
+`TS_HTTP_VALUE_DEFLATE`
+: "deflate"
+
+`TS_HTTP_VALUE_GZIP`
+: "gzip"
+
+`TS_HTTP_VALUE_IDENTITY`
+: "identity"
+
+`TS_HTTP_VALUE_KEEP_ALIVE`
+: "keep-alive"
+
+`TS_HTTP_VALUE_MAX_AGE`
+: "max-age"
+
+`TS_HTTP_VALUE_MAX_STALE`
+: "max-stale"
+
+`TS_HTTP_VALUE_MIN_FRESH`
+: "min-fresh"
+
+`TS_HTTP_VALUE_MUST_REVALIDATE`
+: "must-revalidate"
+
+`TS_HTTP_VALUE_NONE`
+: "none"
+
+`TS_HTTP_VALUE_NO_CACHE`
+: "no-cache"
+
+`TS_HTTP_VALUE_NO_STORE`
+: "no-store"
+
+`TS_HTTP_VALUE_NO_TRANSFORM`
+: "no-transform"
+
+`TS_HTTP_VALUE_ONLY_IF_CACHED`
+: "only-if-cached"
+
+`TS_HTTP_VALUE_PRIVATE`
+: "private"
+
+`TS_HTTP_VALUE_PROXY_REVALIDATE`
+: "proxy-revalidate"
+
+`TS_HTTP_VALUE_PUBLIC`
+: "public"
+
+`TS_HTTP_VALUE_S_MAX_AGE`
+: "s-maxage"
+
+
+The method names and header values above are defined in `ts.h` as `const char*`
+strings. When Traffic Server sets a method or a header value, it checks to
+make sure that the new value is one of the known values. If it is, then it
+stores a pointer into a global table (instead of storing the known value in
+the marshal buffer). The method names and header values listed above are also
+pointers into this table. This allows simple pointer comparison of the value
+returned from `TSHttpMethodGet` with one of the values listed above. It is
+also recommended that you use the above values when referring to one of the
+known schemes, since this removes the possibility of a spelling error.
+
+The **HTTP Header Functions** are listed below:
+
+* [TSHttpHdrClone](link/to/doxygen)
+* [TSHttpHdrCopy](link/to/doxygen)
+* [TSHttpHdrCreate](link/to/doxygen)
+* [TSHttpHdrDestroy](link/to/doxygen)
+* [TSHttpHdrLengthGet](link/to/doxygen)
+* [TSHttpHdrMethodGet](link/to/doxygen)
+* [TSHttpHdrMethodSet](link/to/doxygen)
+* [TSHttpHdrPrint](link/to/doxygen)
+* [TSHttpHdrReasonGet](link/to/doxygen)
+* [TSHttpHdrReasonLookup](link/to/doxygen)
+* [TSHttpHdrReasonSet](link/to/doxygen)
+* [TSHttpHdrStatusGet](link/to/doxygen)
+* [TSHttpHdrStatusSet](link/to/doxygen)
+* [TSHttpHdrTypeGet](link/to/doxygen)
+* [TSHttpHdrTypeSet](link/to/doxygen)
+* [TSHttpHdrUrlGet](link/to/doxygen)
+* [TSHttpHdrUrlSet](link/to/doxygen)
+* [TSHttpHdrVersionGet](link/to/doxygen)
+* [TSHttpHdrVersionSet](link/to/doxygen)
+* [TSHttpParserClear](link/to/doxygen)
+* [TSHttpParserCreate](link/to/doxygen)
+* [TSHttpParserDestroy](link/to/doxyge)
+* [TSHttpHdrParseReq](link/to/doxygen)
+* [TSHttpHdrParseResp](link/to/doxygen)
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/index.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/index.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/index.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,127 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](../misc-interface-guide/thread-functions) - Thread Functions
+
+Guide to Traffic Server HTTP Header System - [Next](guide-to-trafficserver-http-header-system)
+
+## HTTP Headers ## {#HTTPHeaders}
+
+This chapter explains the functions used to manipulate HTTP headers.
+
+* [About HTTP Headers](#AboutHTTPHeaders)
+* [Guide to Traffic Server HTTP Header System](guide-to-trafficserver-http-header-system)
+ * [Duplicate MIME Fields Are Not Coalesced](guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced)
+ * [MIME Fields Always Belong to an Associated MIME Header](guide-to-trafficserver-http-header-system/release-marshal-buffer-handles)
+ * [Release Marshal Buffer Handles](guide-to-trafficserver-http-header-system/release-marshal-buffer-handles)
+* [Marshal Buffers](marshal-buffers)
+* [HTTP Headers](http-headers)
+* [URLs](urls)
+* [MIME Header](MIMEHeaders.html)
+
+## About HTTP Headers ## {#AboutHTTPHeaders}
+
+An ***HTTP message*** consists of the following:
+
+* HTTP header
+* body
+* trailer
+
+The ***HTTP header*** consists of:
+
+* A request or response line
+ * An HTTP **request line** contains a method, URL, and version
+ * A **response line** contains a version, status code, and reason phrase
+* A MIME header
+
+A **MIME header** is comprised of zero or more MIME fields. A **MIME field**
+is composed of a field name, a colon, and (zero or more) field values. The
+values in a field are separated by commas. An HTTP header containing a request
+line is usually referred to as a **request**. The following example shows a
+typical request header.
+
+ ::::text
+ GET http://www.tiggerwigger.com/ HTTP/1.0
+ Proxy-Connection: Keep-Alive
+ User-Agent: Mozilla/5.0 [en] (X11; I; Linux 2.2.3 i686)
+ Host: www.tiggerwigger.com
+ Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */
+ *
+
+ Accept-Encoding: gzip
+ Accept-Language: en
+ Accept-Charset: iso-8859-1, *, utf-8
+
+The **response header** for the above request might look like the following:
+
+ ::::plain
+ HTTP/1.0 200 OK
+ Date: Fri, 13 Nov 2009 06:57:43 GMT
+ Content-Location: http://locutus.tiggerwigger.com/index.html
+ Etag: "07db14afa76be1:1074"
+ Last-Modified: Thu, 05 Nov 2009 20:01:38 GMT
+ Content-Length: 7931
+ Content-Type: text/html
+ Server: Microsoft-IIS/4.0
+ Age: 922
+ Proxy-Connection: close
+
+The following figure illustrates an HTTP message with an expanded HTTP header.
+
+**Figure 10.1. HTTP Request/Response and Header Structure**
+
+
+
+The figure below shows example HTTP request and response headers.
+
+**Figure 10.2. Examples of HTTP Request and Response Headers**
+
+
+
+The marshal buffer or `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 must require the handle to the object (`TSMLoc`) and the marshal
+buffer containing the object (`TSMBuffer`).
+
+**Figure 10.3. Marshal Buffers and Header Locations**
+
+
+
+The figure above shows the following:
+
+* The marshal buffer containing the HTTP request, `reqest_bufp`
+
+* `TSMLoc` location pointer for the HTTP header (`http_hdr_loc`)
+
+* `TSMLoc` location pointer for the request URL (`url_loc`)
+
+* `TSMLoc` location pointers for the MIME header (`mime_hdr_loc`)
+
+* `TSMLoc` location pointers for MIME fields (`fieldi_loc`)
+
+* `TSMLoc` location pointer for the next duplicate MIME field (`next_dup_loc`)
+
+The diagram also shows that an HTTP header contains pointers to the URL location
+and the MIME header location. You can obtain the URL location from an HTTP
+header using the function `TSHttpHdrUrlGet`. To work with MIME headers, you
+can pass either a MIME header location or an HTTP header location to MIME header
+functions . If you pass an HTTP header to a MIME header function, then the
+system locates the associated MIME header and executes the MIME header function
+on the MIME header location.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/marshal-buffers.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/marshal-buffers.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/marshal-buffers.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/marshal-buffers.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,66 @@
+Notice: 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.
+
+
+
+
+ [](/index.html)â¢
+
+
+# Apache Traffic Server⢠Software Developers Kit # {#ApacheTSâ¢SoftwareDevelopersKit}
+
+[Prev](guide-to-trafficserver-http-header-system/release-marshal-buffer-handles) - Release Marshal Buffers
+
+HTTP Headers - [Next](HTTP Headers)
+
+## Marshal Buffers ## {#MarshalBuffers}
+
+A **marshal buffer**, or `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 a marshal buffer. Whenever
+you manipulate an object, you require the handle to the object (`TSMLoc`)
+and the marshal buffer containing the object (`TSMBuffer`).
+
+Routines exist for manipulating the object based on these two pieces of information.
+For example, see one of the following:
+
+* [HTTP Headers](HTTPHeaders2.html)
+* [URLs](URLs.html)
+* [MIME Headers](MIMEHeaders.html)
+
+The **marshal buffer functions** enable you to create and destroy Traffic Server's
+marshal buffers, which are the data structures that hold parsed URLs, MIME
+headers, and HTTP headers.
+
+![[Caution]](/images/docbook/caution.png)
+
+**Caution**
+
+Any marshal buffer fetched by `TSHttpTxn*Get` will be used by other parts
+of the system. Be careful not to destroy these shared transaction marshal buffers
+in functions such as those below:
+
+* `[TSHttpTxnCachedReqGet](link/to/doxygen)`
+* `[TSHttpTxnCachedRespGet](link/to/doxygen)`
+* `[TSHttpTxnClientReqGet](link/to/doxygen)`
+* `[TSHttpTxnClientRespGet](link/to/doxygen)`
+* `[TSHttpTxnServerReqGet](link/to/doxygen)`
+* `[TSHttpTxnServerRespGet](link/to/doxygen)`
+* `[TSHttpTxnTransformRespGet](link/to/doxyge)`
+
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/mime-headers.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/mime-headers.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/mime-headers.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/mime-headers.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,443 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](urls) - URLs
+
+Chapter 11. Mutex Guide - [Next](../mutex-guide)
+
+## MIME Headers ## {#MIMEHeaders}
+
+The Traffic Server **MIME header functions ** enable you to retrieve and modify
+information about HTTP MIME fields.
+
+
+An HTTP request or response consists of a header, body, and trailer. The **HTTP**
+**header** contains a request (or response) line and a MIME header. A **MIME**
+**header** is composed of zero or more MIME fields. A **MIME** **field** is
+composed of a field name, a colon, and zero or more field values (values in
+a field are separated by commas).
+
+In the example below: `Foo` is the MIME field name, `bar` is the first MIME
+field value, and `car` is the second MIME field value.
+
+ :::text
+ Foo: bar, car
+
+The following example is an augmented **Backus-Naur Form** (BNF) for the form
+of a MIME header - it specifies exactly what was described above. A **header**
+consists of zero or more **fields** that contain a name, separating colon,
+and zero or more values. A **name** or **value** is simply a string of tokens
+that is potentially zero length; a **token** is any character except certain
+control characters and separators (such as colons). For the purpose of retrieving
+a field, field names are not case-sensitive; therefore, the field names `Foo`,
+`foo` and `fOO` are all equivalent.
+
+
+ :::text
+ MIME-header = *MIME-field
+ MIME-field = field-name ":" #field-value
+ field-name = *token
+ field-value = *token
+
+
+The MIME header data structure is a parsed version of a standard Internet MIME
+header. The MIME header data structure is similar to the URL data structure
+(see [URLs](urls)). The actual data is stored in a marshal buffer; the
+MIME header functions operate on a marshal buffer and a location (`TSMLoc`)
+within the buffer.
+
+After a call to `TSMimeHdrFieldDestroy`, `TSMimeHdrFieldRemove`, or `TSUrlDestroy`
+is made, you must deallocate the `TSMLoc` handle with a call to `TSHandleMLocRelease`.
+You do not need to deallocate a `NULL` handles. For example: if you call `TSMimeHdrFieldValueStringGet`
+to get the value of the content type field and the field does not exist, then
+it returns `TS_NULL_MLOC`. In such a case, you wouldn't need to deallocate
+the handle with a call to `TSHandleMLocRelease`.
+
+
+The location (`TSMLoc`) in the [MIME header functions](#MimeHeaderFxns)
+can be either an HTTP header location or a MIME header location. If an HTTP
+header location is passed to these functions, then the system locates the MIME
+header associated with that HTTP header and executes the corresponding MIME
+header operations specified by the functions (see the example in the description
+of [`TSMimeHdrCopy`](link/to/doxygen)).
+
+
+**Note:** MIME headers may contain more than one MIME field with the same name.
+Previous versions of Traffic Server joined multiple fields with the same name
+into one field with composite values, but this behavior came at a performance
+cost and caused compatability issues with older clients and servers. Hence,
+the current version of Traffic Server does not coalesce duplicate fields. Correctly-behaving
+plugins should check for the presence of duplicate fields and iterate over
+the duplicate fields by using `TSMimeHdrFieldNextDup`.
+
+To facilitate fast comparisons and reduce storage size, Traffic Server defines
+several pre-allocated field names. These field names correspond to the field
+names in HTTP and NNTP headers.
+
+
+`TS_MIME_FIELD_ACCEPT`
+: "Accept"
+: `TS_MIME_LEN_ACCEPT`
+
+`TS_MIME_FIELD_ACCEPT_CHARSET`
+: "Accept-Charset"
+: `TS_MIME_LEN_ACCEPT_CHARSET`
+
+`TS_MIME_FIELD_ACCEPT_ENCODING`
+: "Accept-Encoding"
+: `TS_MIME_LEN_ACCEPT_ENCODING`
+
+`TS_MIME_FIELD_ACCEPT_LANGUAGE`
+: "Accept-Language"
+: `TS_MIME_LEN_ACCEPT_LANGUAGE`
+
+`TS_MIME_FIELD_ACCEPT_RANGES`
+: "Accept-Ranges"
+: `TS_MIME_LEN_ACCEPT_RANGES`
+
+`TS_MIME_FIELD_AGE`
+: "Age"
+: `TS_MIME_LEN_AGE`
+
+`TS_MIME_FIELD_ALLOW`
+: "Allow"
+: `TS_MIME_LEN_ALLOW`
+
+`TS_MIME_FIELD_APPROVED`
+: "Approved"
+: `TS_MIME_LEN_APPROVED`
+
+`TS_MIME_FIELD_AUTHORIZATION`
+: "Authorization"
+: `TS_MIME_LEN_AUTHORIZATION`
+
+`TS_MIME_FIELD_BYTES`
+: "Bytes"
+: `TS_MIME_LEN_BYTES`
+
+`TS_MIME_FIELD_CACHE_CONTROL`
+: "Cache-Control"
+: `TS_MIME_LEN_CACHE_CONTROL`
+
+`TS_MIME_FIELD_CLIENT_IP`
+: "Client-ip"
+: `TS_MIME_LEN_CLIENT_IP`
+
+`TS_MIME_FIELD_CONNECTION`
+: "Connection"
+: `TS_MIME_LEN_CONNECTION`
+
+`TS_MIME_FIELD_CONTENT_BASE`
+: "Content-Base"
+: `TS_MIME_LEN_CONTENT_BASE`
+
+`TS_MIME_FIELD_CONTENT_ENCODING`
+: "Content-Encoding"
+: `TS_MIME_LEN_CONTENT_ENCODING`
+
+`TS_MIME_FIELD_CONTENT_LANGUAGE`
+: "Content-Language"
+: `TS_MIME_LEN_CONTENT_LANGUAGE`
+
+`TS_MIME_FIELD_CONTENT_LENGTH`
+: "Content-Length"
+: `TS_MIME_LEN_CONTENT_LENGTH`
+
+`TS_MIME_FIELD_CONTENT_LOCATION`
+: "Content-Location"
+: `TS_MIME_LEN_CONTENT_LOCATION`
+
+`TS_MIME_FIELD_CONTENT_MD5`
+: "Content-MD5"
+: `TS_MIME_LEN_CONTENT_MD5`
+
+`TS_MIME_FIELD_CONTENT_RANGE`
+: "Content-Range"
+: `TS_MIME_LEN_CONTENT_RANGE`
+
+`TS_MIME_FIELD_CONTENT_TYPE`
+: "Content-Type"
+: `TS_MIME_LEN_CONTENT_TYPE`
+
+`TS_MIME_FIELD_CONTROL`
+: "Control"
+: `TS_MIME_LEN_CONTROL`
+
+`TS_MIME_FIELD_COOKIE`
+: "Cookie"
+: `TS_MIME_LEN_COOKIE`
+
+`TS_MIME_FIELD_DATE`
+: "Date"
+: `TS_MIME_LEN_DATE`
+
+`TS_MIME_FIELD_DISTRIBUTION`
+: "Distribution"
+: `TS_MIME_LEN_DISTRIBUTION`
+
+`TS_MIME_FIELD_ETAG`
+: "Etag"
+: `TS_MIME_LEN_ETAG`
+
+`TS_MIME_FIELD_EXPECT`
+: "Expect"
+: `TS_MIME_LEN_EXPECT`
+
+`TS_MIME_FIELD_EXPIRES`
+: "Expires"
+: `TS_MIME_LEN_EXPIRES`
+
+`TS_MIME_FIELD_FOLLOWUP_TO`
+: "Followup-To"
+: `TS_MIME_LEN_FOLLOWUP_TO`
+
+`TS_MIME_FIELD_FROM`
+: "From"
+: `TS_MIME_LEN_FROM`
+
+`TS_MIME_FIELD_HOST`
+: "Host"
+: `TS_MIME_LEN_HOST`
+
+`TS_MIME_FIELD_IF_MATCH`
+: "If-Match"
+: `TS_MIME_LEN_IF_MATCH`
+
+`TS_MIME_FIELD_IF_MODIFIED_SINCE`
+: "If-Modified-Since"
+: `TS_MIME_LEN_IF_MODIFIED_SINCE`
+
+`TS_MIME_FIELD_IF_NONE_MATCH`
+: "If-None-Match"
+: `TS_MIME_LEN_IF_NONE_MATCH`
+
+`TS_MIME_FIELD_IF_RANGE`
+: "If-Range"
+: `TS_MIME_LEN_IF_RANGE`
+
+`TS_MIME_FIELD_IF_UNMODIFIED_SINCE`
+: "If-Unmodified-Since"
+: `TS_MIME_LEN_IF_UNMODIFIED_SINCE`
+
+`TS_MIME_FIELD_KEEP_ALIVE`
+: "Keep-Alive"
+: `TS_MIME_LEN_KEEP_ALIVE`
+
+`TS_MIME_FIELD_KEYWORDS`
+: "Keywords"
+: `TS_MIME_LEN_KEYWORDS`
+
+`TS_MIME_FIELD_LAST_MODIFIED`
+: "Last-Modified"
+: `TS_MIME_LEN_LAST_MODIFIED`
+
+`TS_MIME_FIELD_LINES`
+: "Lines"
+: `TS_MIME_LEN_LINES`
+
+`TS_MIME_FIELD_LOCATION`
+: "Location"
+: `TS_MIME_LEN_LOCATION`
+
+`TS_MIME_FIELD_MAX_FORWARDS`
+: "Max-Forwards"
+: `TS_MIME_LEN_MAX_FORWARDS`
+
+`TS_MIME_FIELD_MESSAGE_ID`
+: "Message-ID"
+: `TS_MIME_LEN_MESSAGE_ID`
+
+`TS_MIME_FIELD_NEWSGROUPS`
+: "Newsgroups"
+: `TS_MIME_LEN_NEWSGROUPS`
+
+`TS_MIME_FIELD_ORGANIZATION`
+: "Organization"
+: `TS_MIME_LEN_ORGANIZATION`
+
+`TS_MIME_FIELD_PATH`
+: "Path"
+: `TS_MIME_LEN_PATH`
+
+`TS_MIME_FIELD_PRAGMA`
+: "Pragma"
+: `TS_MIME_LEN_PRAGMA`
+
+`TS_MIME_FIELD_PROXY_AUTHENTICATE`
+: "Proxy-Authenticate"
+: `TS_MIME_LEN_PROXY_AUTHENTICATE`
+
+`TS_MIME_FIELD_PROXY_AUTHORIZATION`
+: "Proxy-Authorization"
+: `TS_MIME_LEN_PROXY_AUTHORIZATION`
+
+`TS_MIME_FIELD_PROXY_CONNECTION`
+: "Proxy-Connection"
+: `TS_MIME_LEN_PROXY_CONNECTION`
+
+`TS_MIME_FIELD_PUBLIC`
+: "Public"
+: `TS_MIME_LEN_PUBLIC`
+
+`TS_MIME_FIELD_RANGE`
+: "Range"
+: `TS_MIME_LEN_RANGE`
+
+`TS_MIME_FIELD_REFERENCES`
+: "References"
+: `TS_MIME_LEN_REFERENCES`
+
+`TS_MIME_FIELD_REFERER`
+: "Referer"
+: `TS_MIME_LEN_REFERER`
+
+`TS_MIME_FIELD_REPLY_TO`
+: "Reply-To"
+: `TS_MIME_LEN_REPLY_TO`
+
+`TS_MIME_FIELD_RETRY_AFTER`
+: "Retry-After"
+: `TS_MIME_LEN_RETRY_AFTER`
+
+`TS_MIME_FIELD_SENDER`
+: "Sender"
+: `TS_MIME_LEN_SENDER`
+
+`TS_MIME_FIELD_SERVER`
+: "Server"
+: `TS_MIME_LEN_SERVER`
+
+`TS_MIME_FIELD_SET_COOKIE`
+: "Set-Cookie"
+: `TS_MIME_LEN_SET_COOKIE`
+
+`TS_MIME_FIELD_SUBJECT`
+: "Subject"
+: `TS_MIME_LEN_SUBJECTTS_MIME_LEN_SUBJECT`
+
+`TS_MIME_FIELD_SUMMARY`
+: "Summary"
+: `TS_MIME_LEN_SUMMARY`
+
+`TS_MIME_FIELD_TE`
+: "TE"
+: `TS_MIME_LEN_TE`
+
+`TS_MIME_FIELD_TRANSFER_ENCODING`
+: "Transfer-Encoding"
+: `TS_MIME_LEN_TRANSFER_ENCODING`
+
+`TS_MIME_FIELD_UPGRADE`
+: "Upgrade"
+: `TS_MIME_LEN_UPGRADE`
+
+`TS_MIME_FIELD_USER_AGENT`
+: "User-Agent"
+: `TS_MIME_LEN_USER_AGENT`
+
+`TS_MIME_FIELD_VARY`
+: "Vary"
+: `TS_MIME_LEN_VARY`
+
+`TS_MIME_FIELD_VIA`
+: "Via"
+: `TS_MIME_LEN_VIA`
+
+`TS_MIME_FIELD_WARNING`
+: "Warning"
+: `TS_MIME_LEN_WARNING`
+
+`TS_MIME_FIELD_WWW_AUTHENTICATE`
+: "Www-Authenticate"
+: `TS_MIME_LEN_WWW_AUTHENTICATE`
+
+`TS_MIME_FIELD_XREF`
+: "Xref"
+: `TS_MIME_LEN_XREF`
+
+
+
+The header field names above are defined in `ts.h` as ` const char* ` strings.
+When Traffic Server sets the name portion of a header field (or any portion
+for that matter), it quickly checks to see if the new value is one of the known
+values. If it is, then Traffic Server stores a pointer into a global table
+instead of storing the known value in the marshal buffer. The header field
+names listed above are also pointers into this table, which enables simple
+pointer comparison of the value returned from `TSMimeHdrFieldNameGet` with
+one of the values listed above. It is recommended that you use the above values
+when referring to one of the known header field names to avoid the possibility
+of a spelling error.
+
+Traffic Server adds one important feature to MIME fields that you may not know
+about: Traffic Server does not print a MIME field if the field name begins
+with the '`@`' symbol. For example: a plugin can add the field "`@My-Field`"
+to a header. Even though Traffic Server never sends that field out in a request
+to an origin server or in a response to a client, it can be printed to Traffic
+Server logs by defining a custom log configuration file that explicitly logs
+such fields. This provides a useful mechanism for plugins to store information
+about an object in one of the MIME headers associated with the object.
+
+
+
+The MIME header functions are listed below:
+
+
+* [TSMimeHdrFieldAppend](link/to/doxygen)
+* [TSMimeHdrFieldClone](link/to/doxygen)
+* [TSMimeHdrFieldCopy](link/to/doxygen)
+* [TSMimeHdrFieldCopyValues](link/to/doxygen)
+* [TSMimeHdrFieldCreate](link/to/doxygen)
+* [TSMimeHdrFieldDestroy](link/to/doxygen)
+* [TSMimeHdrFieldLengthGet](link/to/doxygen)
+* [TSMimeHdrFieldNameGet](link/to/doxygen)
+* [TSMimeHdrFieldNameSet](link/to/doxygen)
+* [TSMimeHdrFieldNext](link/to/doxygen)
+* [TSMimeHdrFieldNextDup](link/to/doxygen)
+* [TSMimeHdrFieldValueAppend](link/to/doxygen)
+* [TSMimeHdrFieldValueAppend](link/to/doxygen)
+* [TSMimeHdrFieldValueDateGet](link/to/doxygen)
+* [TSMimeHdrFieldValueDateInsert](link/to/doxygen)
+* [TSMimeHdrFieldValueDateSet](link/to/doxygen)
+* [TSMimeHdrFieldValueInsert](link/to/doxygen)
+* [TSMimeHdrFieldValueIntGet](link/to/doxygen)
+* [TSMimeHdrFieldValueIntSet](link/to/doxygen)
+* [TSMimeHdrFieldValueStringGet](link/to/doxygen)
+* [TSMimeHdrFieldValueStringInsert](link/to/doxygen)
+* [TSMimeHdrFieldValueStringSet](link/to/doxygen)
+* [TSMimeHdrFieldValueUintGet](link/to/doxygen)
+* [TSMimeHdrFieldValueUintInsert](link/to/doxygen)
+* [TSMimeHdrFieldValueUintSet](link/to/doxygen)
+* [TSMimeHdrFieldValuesClear](link/to/doxygen)
+* [TSMimeHdrFieldValuesCount](link/to/doxygen)
+* [TSMimeHdrClone](link/to/doxygen)
+* [TSMimeHdrCopy](link/to/doxygen)
+* [TSMimeHdrCreate](link/to/doxygen)
+* [TSMimeHdrDestroy](link/to/doxygen)
+* [TSMimeHdrFieldFind](link/to/doxygen)
+* [TSMimeHdrFieldGet](link/to/doxygen)
+* [TSMimeHdrFieldRemove](link/to/doxygen)
+* [TSMimeHdrFieldsClear](link/to/doxygen)
+* [TSMimeHdrFieldsCount](link/to/doxygen)
+* [TSMimeHdrLengthGet](link/to/doxygen)
+* [TSMimeHdrParse](link/to/doxygen)
+* [TSMimeParserClear](link/to/doxygen)
+* [TSMimeParserCreate](link/to/doxygen)
+* [TSMimeParserDestroy](link/to/doxygen)
+* [TSMimeHdrPrint](link/to/doxygen)
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/urls.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/urls.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/urls.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/http-headers/urls.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,136 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](http-headers) - HTTP Headers
+
+MIME Headers - [Next](mime-headers)
+
+
+## URLs ## {#URLs}
+
+API URL functions provide access to URL data stored in marshal buffers. The
+URL functions can create, copy, retrieve or delete entire URLs; they can also
+retrieve or modify parts of URLs, such as port or scheme information.
+
+The general form of an Internet URL is:
+
+ :::text
+ scheme://user:password@host:port/stuff
+
+The URL data structure includes support for two specific types of internet
+URLs. HTTP URLs have the form:
+
+ :::text
+ http://user:password@host:port/path;params?query#fragment
+
+The URL port is stored as integer. All remaining parts of the
+URL (scheme, user, etc.) are stored as strings. Traffic Server URL functions
+are named according to the portion of the URL on which they operate. For instance,
+the function that retrieves the host portion of a URL is named `TSUrlHostGet`.
+
+To facilitate fast comparisons and reduce storage size, Traffic Server defines
+several preallocated scheme names.
+
+`TS_URL_SCHEME_FILE`
+: "file"
+: `TS_URL_LEN_FILE`
+
+`TS_URL_SCHEME_FTP`
+: "ftp"
+: `TS_URL_LEN_FTP`
+
+`TS_URL_SCHEME_GOPHER`
+: "gopher"
+: `TS_URL_LEN_GOPHER`
+
+`TS_URL_SCHEME_HTTP`
+: "http"
+: `TS_URL_LEN_HTTP`
+
+`TS_URL_SCHEME_HTTPS`
+: "https"
+: `TS_URL_LEN_HTTPS`
+
+`TS_URL_SCHEME_MAILTO`
+: "mailto"
+: `TS_URL_LEN_MAILTO`
+
+`TS_URL_SCHEME_NEWS`
+: "news"
+: `TS_URL_LEN_NEWS`
+
+`TS_URL_SCHEME_NNTP`
+: "nntp"
+: `TS_URL_LEN_NNTP`
+
+`TS_URL_SCHEME_PROSPERO`
+: "prospero"
+: `TS_URL_LEN_PROSPERO`
+
+`TS_URL_SCHEME_TELNET`
+: "telnet"
+: `TS_URL_LEN_TELNET`
+
+`TS_URL_SCHEME_WAIS`
+: "wais"
+: `TS_URL_LEN_WAIS`
+
+
+
+The scheme names above are defined in `ts.h` as `const` `char*` strings. When
+Traffic Server sets the scheme portion of the URL (or any portion for that
+matter), it quickly checks to see if the new value is one of the known values.
+If it is, then it stores a pointer into a global table (instead of storing
+the known value in the marshal buffer). The scheme values listed above are
+also pointers into this table. This allows simple pointer comparison of the
+value returned from `TSUrlSchemeGet` with one of the values listed above.
+You should use the Traffic Server-defined values when referring to one of the
+known schemes, since doing so can prevent the possibility of spelling errors.
+
+Traffic Server **URL functions** are listed below:
+
+[TSUrlClone](link/to/doxygen)
+[TSUrlCopy](link/to/doxygen)
+[TSUrlCreate](link/to/doxygen)
+[TSUrlDestroy](link/to/doxygen)
+[TSUrlPrint](link/to/doxygen)
+[TSUrlFtpTypeGet](link/to/doxygen)
+[TSUrlFtpTypeSet](link/to/doxygen)
+[TSUrlHostGet](link/to/doxygen)
+[TSUrlHostSet](link/to/doxygen)
+[TSUrlHttpFragmentGet](link/to/doxygen)
+[TSUrlHttpFragmentSet](link/to/doxygen)
+[TSUrlHttpParamsGet](link/to/doxygen)
+[TSUrlHttpParamsSet](link/to/doxygen)
+[TSUrlHttpQueryGet](link/to/doxygen)
+[TSUrlHttpQuerySet](link/to/doxygen)
+[TSUrlLengthGet](link/to/doxygen)
+[TSUrlParse](link/to/doxygen)
+[TSUrlPasswordGet](link/to/doxygen)
+[TSUrlPasswordSet](link/to/doxygen)
+[TSUrlPathGet](link/to/doxygen)
+[TSUrlPathSet](link/to/doxygen)
+[TSUrlPortGet](link/to/doxygen)
+[TSUrlPortSet](link/to/doxygen)
+[TSUrlSchemeGet](link/to/doxygen)
+[TSUrlSchemeSet](link/to/doxygen)
+[TSUrlStringGet](link/to/doxygen)
+[TSUrlUserGet](link/to/doxygen)
+[TSUrlUserSet](link/to/doxygen)
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/mutex-guide/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/mutex-guide/index.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/mutex-guide/index.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/mutex-guide/index.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,376 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](../http-headers/mime-headers) - MIME Headers
+
+Continuations - [Next](continuations)
+
+## Mutex Guide ## {#MutexGuide}
+
+Mutexes are used to lock shared data. This chapter explains how to use the
+mutex interface.
+
+[TOC]
+
+## Mutexes ## {#Mutexes}
+
+A **mutex** is the basic synchronization method used within Traffic Server
+to protect data from simultaneous access by multiple threads. A mutex acts
+as a lock that protects data in one program thread from being accessed by another
+thread.
+
+The Traffic Server API provides two functions that attempt to access and lock
+the data: `InkMutexLockTry` and `TSMutexLock`. `**TSMutexLock**` is a blocking
+call - if you use it, you can slow Traffic Server performance because transaction
+processing pauses until the mutex is unlocked. It should be used only on threads
+created by the plugin `TSContThreadCreate`. Never use it on a continuation
+handler called back by the Cache, Net, or Event Processor. Even if the critical
+section is very small, do not use it. If you need to update a flag, then set
+a variable and/or use atomic operations. If `TSMutexLock` is used in any case
+other than the one recommended above, then the result will be a serious performance
+impact.
+
+`**TSMutexLockTry**`, on the other hand, attempts to lock the mutex only if
+it is unlocked (i.e., not being used by another thread). It should be used
+in all cases other than the above mentioned `TSMutexLock` case. If the `TSMutexLockTry`
+attempt fails, then you can schedule a future attempt (which must be at least
+10 milliseconds later).
+
+In general, you should use `TSMutexLockTry` instead of `TSMutexLock`.
+
+* `InkMutexLockTry` is required if you are tying to lock Traffic Server internal
+or system resources (such as the network, cache, event processor, HTTP state
+machines, and IO buffers).
+
+* `InkMutexLockTry` is required if you are making any blocking calls (such as
+network, cache, or file IO calls).
+
+* `TSMutexLock` might _not_ be necessary if you are not making blocking calls
+and if you are only accessing local resources.
+
+The Traffic Server API uses the `TSMutex` type for a mutex. There are two
+typical uses of mutex. One use is for locking global data or data shared by
+various continuations. The other typical usage is for locking data associated
+with a continuation (i.e., data that might be accessed by other continuations).
+
+
+### Locking Global Data ### {#LockingGlobalData}
+
+The `blacklist-1.c` sample plugin implements a mutex that locks global data.
+The blacklist plugin reads its blacklisted sites from a configuration file;
+file read operations are protected by a mutex created in `TSPluginInit`. The
+`blacklist-1.c` code uses `TSMutexLockTry` instead of `InkMutexLock`. For
+more detailed information, see the [`blacklist-1.c`](../sample-source-code#Sample_blacklist-1.c)
+code; start by looking at the [`TSPluginInit`](link/to/doxygen)
+function.
+
+General guidelines for locking shared data are as follows:
+
+1. Create a mutex for the shared data with [`TSMutexCreate`](link/to/doxygen).
+
+2. Whenever you need to read or modify this data, first lock it by calling [`TSMutexLockTry`](link/to/doxygen);
+then read or modify the data.
+
+3. When you are done with the data, unlock it with [`TSMutexUnlock`](link/to/doxygen).
+If you are unlocking data accessed during the processing of an HTTP transaction,
+then you must unlock it before calling [`TSHttpTxnReenable`](link/to/doxygen).
+
+
+### Protecting a Continuation's Data ### {#ProtectingaContinuationsData}
+
+You must create a mutex to protect a continuation's data if it might be accessed
+by other continuations or processes. Here's how:
+
+1. Create a mutex for the continuation using `TSMutexCreate`.
+For example:
+
+ ::::c
+ TSMutex mutexp;
+ mutexp = TSMutexCreate ();
+
+2. When you create the continuation, specify this mutex as the continuation's mutex.
+For example:
+
+ :::c
+ TSCont contp;
+ contp = TSContCreate (handler, mutexp);
+
+
+If any other functions want to access `contp`'s data, then it is up to them
+to get `contp`'s mutex (using, for example, `TSContMutexGet`) to lock it.
+For usage, ssee the sample Protocol plugin.
+
+
+### How to Associate a Continuation With Every HTTP Transaction ### {#HowAssociateaContinuationWithEveryHTTPTransaction}
+
+There could be several reasons why you'd want to create a continuation for each HTTP transaction that calls back your plugin.
+
+Some potential scenarios are listed below.
+
+* You want to register hooks locally with the new continuation instead of registering
+them globally to the continuation plugin.
+
+* You want to store data specific to each HTTP transaction that you might need
+to reuse across various hooks.
+
+* You're using APIs (like `TSHostLookup`) that will call back the continuation with a certain event.
+
+
+### How to Add the New Continuation ### {#HowAddNewContinuation}
+
+A typical way of adding the new continuation is by registering the plugin continuation
+to be called back by HTTP transactions globally when they reach `TS_HTTP_TXN_START_HOOK`.
+Refer to the example below, which uses a transaction-specific continuation
+called `txn_contp`.
+
+ ::::c
+ void TSPluginInit(int argc, const char *argv[])
+ {
+ /* Plugin continuation */
+ TSCont contp;
+ if ((contp = TSContCreate (plugin_cont_handler, NULL)) == TS_ERROR_PTR) {
+ LOG_ERROR("TSContCreate");
+ } else {
+ if (TSHttpHookAdd (TS_HTTP_TXN_START_HOOK, contp) == TS_ERROR) {
+ LOG_ERROR("TSHttpHookAdd");
+ }
+ }
+ }
+
+In the plugin continuation handler, create the new continuation `txn_contp`
+and then register it to be called back at `TS_HTTP_TXN_CLOSE_HOOK`:
+
+ ::::c
+ static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn)edata;
+ TSCont txn_contp;
+
+ switch (event) {
+ case TS_EVENT_HTTP_TXN_START:
+ /* Create the HTTP txn continuation */
+ txn_contp = TSContCreate(txn_cont_handler, NULL);
+
+ /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */
+ if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnHookAdd");
+ }
+
+ break;
+
+ default:
+ TSAssert(!"Unexpected Event");
+ break;
+ }
+
+ if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnReenable");
+ }
+
+ return 0;
+ }
+
+
+Remember that the `txn_contp` handler must destory itself when the HTTP transaction
+is closed. If you forget to do this, then your plugin will have a memory leak.
+
+ ::::c
+ static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp;
+ switch (event) {
+ case TS_EVENT_HTTP_TXN_CLOSE:
+ txnp = (TSHttpTxn) edata;
+ TSContDestroy(txn_contp);
+ break;
+
+ default:
+ TSAssert(!"Unexpected Event");
+ break;
+ }
+
+ if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnReenable");
+ }
+
+ return 0;
+ }
+
+
+### How to Store Data Specific to Each HTTP Transaction ### {#HowStoreDataSpecificEachHTTPTransaction}
+
+For the example above, store the data in the `txn_contp` data structure - this
+means that you'll create your own data structure. Now suppose you want to store
+the state of the HTTP transaction:
+
+ ::::c
+ typedef struct {
+ int state;
+ } ContData;
+
+You need to allocate the memory and initialize this structure for each HTTP
+`txnp`. You can do that in the plugin continuation handler when it is called
+back with `TS_EVENT_HTTP_TXN_START`
+
+ ::::c
+ static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn)edata;
+ TSCont txn_contp;
+ ContData *contData;
+
+ switch (event) {
+ case TS_EVENT_HTTP_TXN_START:
+ /* Create the HTTP txn continuation */
+ txn_contp = TSContCreate(txn_cont_handler, NULL);
+
+ /* Allocate and initialize the txn_contp data */
+ contData = (ContData*) TSmalloc(sizeof(ContData));
+ contData->state = 0;
+ if (TSContDataSet(txn_contp, contData) == TS_ERROR) {
+ LOG_ERROR("TSContDataSet");
+ }
+
+ /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */
+ if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnHookAdd");
+ }
+
+ break;
+
+ default:
+ TSAssert(!"Unexpected Event");
+ break;
+ }
+
+ if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnReenable");
+ }
+
+ return 0;
+ }
+
+For accessing this data from anywhere, use TSContDataGet:
+
+ ::::c
+ TSCont txn_contp;
+ ContData *contData;
+
+ contData = TSContDataGet(txn_contp);
+ if (contData == TS_ERROR_PTR) {
+ LOG_ERROR("TSContDataGet");
+ }
+ contData->state = 1;
+
+Remember to free this memory before destroying the continuation:
+
+ ::::c
+ static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp;
+ ContData *contData;
+ switch (event) {
+ case TS_EVENT_HTTP_TXN_CLOSE:
+ txnp = (TSHttpTxn) edata;
+ contData = TSContDataGet(txn_contp);
+ if (contData == TS_ERROR_PTR) {
+ LOG_ERROR("TSContDataGet");
+ } else {
+ TSfree(contData);
+ }
+ TSContDestroy(txn_contp);
+ break;
+
+ default:
+ TSAssert(!"Unexpected Event");
+ break;
+ }
+
+ if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
+ LOG_ERROR("TSHttpTxnReenable");
+ }
+
+ return 0;
+ }
+
+
+
+### Using Locks ### {#UsingLocks}
+
+You do not need to use locks when a continuation has registered itself to be
+called back by HTTP hooks and it only uses the HTTP APIs. In the example above,
+the continuation `txn_contp` has registered itself to be called back at HTTP
+hooks and it only uses the HTTP APIs. In this case only, it's safe to access
+data shared between `txnp` and `txn_contp` without grabbing a lock. In the
+example above, `txn_contp` is created with a `NULL` mutex. This works because
+the HTTP transaction `txnp` is the only one that will call back `txn_contp`,
+and you are guaranteed that `txn_contp` will be called back only one hook at
+a time. After processing is finished, `txn_contp` will reenable `txnp`.
+
+In all other cases, you should create a mutex with the continuation. In general,
+a lock is needed when you're using iocore APIs or any other API where `txn_contp`
+is scheduled to be called back by a processor (such as the cache processor,
+the DNS processor, etc.). This ensures that `txn_contp` is called back sequentially
+and not simultaneously. In other words, you need to ensure that `txn_contp`
+will not be called back by both `txnp` and the cache processor at the same
+time, since this will result in a situation wherein you're executing two pieces
+of code in conflict.
+
+
+### Special Case: Continuations Created for HTTP Transactions ### {#SpecialCaseContinuationsCreatedforHTTPTransactions}
+
+If your plugin creates a new continuation for each HTTP transaction, then you
+probably don't need to create a new mutex for it because each HTTP transaction
+(`TSHttpTxn` object) already has its own mutex.
+
+In the example below, it's not necessary to specify a mutex for the continuation
+created in `txn_handler`:
+
+ ::::c
+ static void
+ txn_handler (TSHttpTxn txnp, TSCont contp) {
+ TSCont newCont;
+ ....
+ newCont = TSContCreate (newCont_handler, NULL);
+ //It's not necessary to create a new mutex for newCont.
+
+ ...
+
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ }
+
+ static int
+ test_plugin (TSCont contp, TSEvent event, void *edata) {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+
+ switch (event) {
+ case TS_EVENT_HTTP_READ_REQUEST_HDR:
+ txn_handler (txnp, contp);
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+The mutex functions are listed below:
+
+* [`TSMutexCreate`](link/to/doxygen)
+* [`TSMutexLock`](link/to/doxygen)
+* [`TSMutexLockTry`](link/to/doxygen)
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/sample-source-code/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/sample-source-code/index.en.mdtext?rev=1067571&r1=1067570&r2=1067571&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/sample-source-code/index.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/sample-source-code/index.en.mdtext Sun Feb 6 01:36:09 2011
@@ -0,0 +1,314 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+
+[Prev](../adding-statistics) - Adding Statistics
+
+Troubleshooting Tips - [Next](../troubleshooting-tips)
+
+## Sample Source Code ## {#SampleSourceCode}
+
+This appendix provides several source code examples. In the online formats
+of this book, function calls are linked to their references in the previous
+chapters. The following sample plugins are provided:
+
+* [blacklist-1.c](App_SampleSourceCode.html#Sample_blacklist-1.c)
+
+## blacklist-1.c ## {#blacklist-1.c}
+
+The sample blacklisting plugin included in the Traffic Server SDK is `blacklist-1.c`.
+This plugin checks every incoming HTTP client request against a list of blacklisted
+web sites. If the client requests a blacklisted site, then the plugin returns an
+`Access forbidden` message to the client.
+
+This plugin illustrates:
+
+* An HTTP transaction extension
+
+* How to examine HTTP request headers
+
+* How to use the logging interface
+
+* How to use the plugin configuration management interface
+
+ :::::c
+ /* blacklist-1.c: An example program that denies client access
+ * to blacklisted sites. This plugin illustrates
+ * how to use configuration information from the
+ * blacklist.txt configuration file.
+ *
+ * Usage:
+ * (Solaris) : blacklist-1.so
+ *
+ *
+ */
+
+ #include <stdio.h>
+ #include <string.h>
+ #include <ts/ts.h>
+
+ #define MAX_NSITES 500
+
+ static char* sites[MAX_NSITES];
+ static int nsites;
+ static TSMutex sites_mutex;
+ static TSTextLogObject log;
+
+ static void
+ handle_dns (TSHttpTxn txnp, TSCont contp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ TSError ("couldn't retrieve request url\n");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = TSUrlHostGet (bufp, url_loc, &host_length);
+ if (!host) {
+ TSError ("couldn't retrieve request hostname\n");
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ TSMutexLock(sites_mutex);
+
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ if (log) {
+ TSTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
+ } else {
+ printf ("blacklisting site: %s\n", sites[i]);
+ }
+ TSHttpTxnHookAdd (txnp,
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
+ TSMutexUnlock(sites_mutex);
+ return;
+ }
+ }
+
+ TSMutexUnlock(sites_mutex);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ handle_response (TSHttpTxn txnp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ char *url_str;
+ char *buf;
+ int url_length;
+
+ if (!TSHttpTxnClientRespGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("couldn't retrieve client response header\n");
+ goto done;
+ }
+
+ TSHttpHdrStatusSet (bufp, hdr_loc, TS_HTTP_STATUS_FORBIDDEN);
+ TSHttpHdrReasonSet (bufp, hdr_loc,
+ TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN),
+ strlen (TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN)) );
+
+ if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("couldn't retrieve client request header\n");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ TSError ("couldn't retrieve request url\n");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ buf = (char *)TSmalloc (4096);
+
+ url_str = TSUrlStringGet (bufp, url_loc, &url_length);
+ sprintf (buf, "You are forbidden from accessing \"%s\"\n", url_str);
+ TSfree (url_str);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+ TSHttpTxnErrorBodySet (txnp, buf, strlen (buf), NULL);
+
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ read_blacklist (void)
+ {
+ char blacklist_file[1024];
+ TSFile file;
+
+ sprintf (blacklist_file, "%s/blacklist.txt", TSPluginDirGet());
+ file = TSfopen(blacklist_file, "r");
+
+ TSMutexLock (sites_mutex);
+ nsites = 0;
+
+ if (file != NULL) {
+ char buffer[1024];
+
+ while (TSfgets (file, buffer, sizeof(buffer)-1) != NULL &&
+ nsites < MAX_NSITES) {
+ char* eol;
+ if ((eol = strstr(buffer, "\r\n")) != NULL) {
+ /* To handle newlines on Windows */
+ *eol = '\0';
+ } else if ((eol = strchr(buffer, '\n')) != NULL) {
+ *eol = '\0';
+ } else {
+ /* Not a valid line, skip it */
+ continue;
+ }
+ if (sites[nsites] != NULL) {
+ TSfree (sites[nsites]);
+ }
+ sites[nsites] = TSstrdup (buffer);
+ nsites++;
+ }
+
+ TSfclose (file);
+ } else {
+ TSError ("unable to open %s\n", blacklist_file);
+ TSError ("all sites will be allowed\n", blacklist_file);
+ }
+
+ TSMutexUnlock (sites_mutex);
+
+ }
+
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case TS_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = TSTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* Need at least TS 2.0 */
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ int i;
+ TSCont contp;
+ TSPluginRegistrationInfo info;
+ int error;
+
+ info.plugin_name = "blacklist-1";
+ info.vendor_name = "DsCompany";
+ info.support_email = "ts-api-support@DsCompany.com";
+
+ if (!TSPluginRegister (TS_SDK_VERSION_2_0 , &info)) {
+ TSError ("Plugin registration failed.\n");
+ }
+
+ if (!check_ts_version()) {
+ TSError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ /* create an TSTextLogObject to log blacklisted requests to */
+ log = TSTextLogObjectCreate("blacklist", TS_LOG_MODE_ADD_TIMESTAMP,
+ NULL, &error);
+ if (!log) {
+ printf("Blacklist plugin: error %d while creating log\n", error);
+ }
+
+ sites_mutex = TSMutexCreate ();
+
+ nsites = 0;
+ for (i = 0; i < MAX_NSITES; i++) {
+ sites[i] = NULL;
+ }
+
+ read_blacklist ();
+
+ contp = TSContCreate (blacklist_plugin, NULL);
+
+ TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
+
+ TSMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
+ }
+
+
+