trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From iga...@apache.org
Subject 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/
Date Sun, 06 Feb 2011 01:36:10 GMT
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**
+
+![HTTP Request/Response and Header Structure](/images/sdk/http_header_struct.jpg) 
+
+The figure below shows example HTTP request and response headers.
+
+**Figure 10.2. Examples of HTTP Request and Response Headers**
+
+![Examples of HTTP Request and Response Headers](/images/sdk/http_headers.jpg)
+
+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**
+
+![Marshal Buffers and Header Locations](/images/sdk/marshall_buffers.jpg)
+
+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.
+
+
+   
+   
+   [![](images/docbook/ts75.png)](/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");
+	}
+
+
+



Mime
View raw message