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 2010/11/06 07:30:02 UTC
svn commit: r1031963 [5/13] - in /trafficserver/site/branches/ats-cms:
content/docs/trunk/sdk/ templates/
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransactionFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransactionFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransactionFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransactionFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,855 @@
+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](HTTPSessionFunctions) - Session Functions
+Initiate Connection - [Next](InitiateConnectionFunctions)
+### HTTP Transaction Functions
+
+- **[INKHttpTxnCacheLookupStatusGet](HTTPTransactionFunctions#INKHttpTxnCacheLookupStatusGet)**
+- **[INKHttpTxnCacheLookupStatusSet](HTTPTransactionFunctions#INKHttpTxnCacheLookupStatusSet)**
+- **[INKHttpTxnCachedReqGet](HTTPTransactionFunctions#INKHttpTxnCachedReqGet)**
+- **[INKHttpTxnCachedRespGet](HTTPTransactionFunctions#INKHttpTxnCachedRespGet)**
+- **[INKHttpTxnClientIncomingPortGet](HTTPTransactionFunctions#INKHttpTxnClientIncomingPortGet)**
+- **[INKHttpTxnClientIPGet](HTTPTransactionFunctions#INKHttpTxnClientIPGet%20)**
+- **[INKHttpTxnClientRemotePortGet](HTTPTransactionFunctions#INKHttpTxnClientRemotePortGet)**
+- **[INKHttpTxnClientReqGet](HTTPTransactionFunctions#INKHttpTxnClientReqGet)**
+- **[INKHttpTxnClientRespGet](HTTPTransactionFunctions#INKHttpTxnClientRespGet)**
+- **[INKHttpTxnErrorBodySet](HTTPTransactionFunctions#INKHttpTxnErrorBodySet)**
+- **[INKHttpTxnHookAdd](HTTPTransactionFunctions#INKHttpTxnHookAdd)**
+- **[INKHttpTxnNextHopIPGet](HTTPTransactionFunctions#INKHttpTxnNextHopIPGet)**
+- **[INKHttpTxnParentProxyGet](HTTPTransactionFunctions#INKHttpTxnParentProxyGet)**
+- **[INKHttpTxnParentProxySet](HTTPTransactionFunctions#INKHttpTxnParentProxySet)**
+- [**INKHttpTxnPristineUrlGet**](HTTPTransactionFunctions#INKHttpTxnPristineUrlGet)
+- **[INKHttpTxnReenable](HTTPTransactionFunctions#INKHttpTxnReenable)[](HTTPTransactionFunctions#INKHttpTxnReenable)**
+- **[INKHttpTxnServerIPGet](HTTPTransactionFunctions#INKHttpTxnServerIPGet)**
+- **[INKHttpTxnServerReqGet](HTTPTransactionFunctions#INKHttpTxnServerReqGet)**
+- **[INKHttpTxnServerRespGet](HTTPTransactionFunctions#INKHttpTxnServerRespGet)**
+- **[INKHttpTxnSetRespCacheableSet](HTTPTransactionFunctions#INKHttpTxnSetRespCacheableSet)**
+- **[INKHttpTxnSkipRww](HTTPTransactionFunctions#INKHttpTxnSkipRww)**
+- **[INKHttpTxnSsnGet](HTTPTransactionFunctions#INKHttpTxnSsnGet)**
+- **[INKHttpTxnTransformedRespCache](HTTPTransactionFunctions#INKHttpTxnTransformedRespCache)**
+- **[INKHttpTxnTransformRespGet](HTTPTransactionFunctions#INKHttpTxnTransformRespGet)**
+- **[INKHttpTxnUntransformedRespCache](HTTPTransactionFunctions#INKHttpTxnUntransformedRespCache)**
+
+#### INKHttpTxnCacheLookupStatusGet
+
+Stores the current cache lookup status for the ongoing transaction.
+Also stores the number of cache lookup operations already
+performed.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnCacheLookupStatusGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ int \**`lookup_status`*)
+
+**Arguments**
+ ~ `INKHttpTxn <i>txnp </i>` is the ongoing transaction.
+
+ `int <i>*lookup_status </i>` is set to the lookup status.
+
+**Description**
+ ~ Obtains the status of the current cache lookup for the ongoing
+ transaction `<em class="replaceable"><code>txnp` in the
+ `<em class="replaceable"><code>lookup_status` variable.
+
+ This function should only be called from
+ `INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`.
+
+ Possible status values returned in
+ `<em class="replaceable"><code>lookup_status` are:
+
+ - `INK_CACHE_LOOKUP_MISS` - Document was not in the cache, so it
+ will be fetched from the origin server.
+ - `INK_CACHE_LOOKUP_HIT_STALE` - Document was present in the
+ cache but was stale. A fresher version will be fetched from the
+ origin server (IMS request).
+ - `INK_CACHE_LOOKUP_HIT_FRESH` - Document was present in the
+ cache and was fresh. Document will be served from the cache.
+ - `INK_CACHE_LOOKUP_SKIPPED` - Traffic Server didn't perform a
+ cache lookup because the request wasn't cacheable (this can happen
+ when the URL looks dynamic or the request is marked as
+ noncacheable).
+
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if an error occurs while calling the API or if an
+ argument is invalid.
+
+
+#### INKHttpTxnCacheLookupStatusSet
+
+Sets the cache lookup status to the status that is passed in.
+
+**Prototype**
+ ~ `int INKHttpTxnCacheLookupStatusSet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ int *`lookup_status`*)
+
+**Arguments**
+ ~ `INKHttpTxn``<em class="replaceable"><code>txnp`** is the
+ ongoing transaction.
+
+ Â
+
+**Description**
+ ~ Sets the status of the current cache lookup for the ongoing
+ transaction `<em class="replaceable"><code>txnp` to whatever is
+ specified in the `<em class="replaceable"><code>lookup_status`
+ variable. Changing the status from `INK_CACHE_LOOKUP_MISS` is not
+ allowed.
+
+ ~ For example, consider the following use-case scenario: A 'stale
+ while revalidate' plugin has to serve stale data from the cache
+ while it makes a request for new data asynchronously. The plugin
+ forces the core to serve stale data by setting the cache lookup
+ status to `INK_CACHE_LOOKUP_HIT_FRESH`.
+
+ Possible status values for
+ `<em class="replaceable"><code>lookup_status` are:
+
+ - `INK_CACHE_LOOKUP_MISS` - Document was not in the cache, so it
+ will be fetched from the origin server.
+ - `INK_CACHE_LOOKUP_HIT_STALE` - Document was present in the
+ cache but was stale. A fresher version will be fetched from the
+ origin server (IMS request).
+ - `INK_CACHE_LOOKUP_HIT_FRESH` - Document was present in the
+ cache and was fresh. Document will be served from the cache.
+ - `INK_CACHE_LOOKUP_SKIPPED` - Traffic Server didn't perform a
+ cache lookup because the request was not cacheable (this can happen
+ when the URL looks dynamic or the request is marked as
+ noncacheable).
+
+
+**Returns**
+ ~ `1` if the API is called successfully.
+
+ `0` if an error occurs.
+
+
+#### INKHttpTxnCachedReqGet
+
+Gets the cached request header for a specified HTTP transaction.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnCachedReqGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`hdr_loc`*)
+
+**Arguments**
+ ~ `INKHttpTxn` `<em class="replaceable"><code>txnp` is the
+ ongoing transaction.
+
+ `int <i>*</i>`*`lookup_status`* is set to the lookup status.
+
+**Description**
+ ~ Obtains the status of the current cache lookup for the ongoing
+ transaction `<em class="replaceable"><code>txnp` in the
+ `<i>lookup_status </i>` variable.
+
+ This function should only be called from
+ `INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`.
+
+ The possible status values returned in `<i>lookup_status </i>`
+ are:
+
+ - `INK_CACHE_LOOKUP_MISS` - Document was not in the cache; it
+ will be fetched from the origin server.
+ - `INK_CACHE_LOOKUP_HIT_STALE` - Document was present in the
+ cache but was stale. A fresher version will be fetched from the
+ origin server (IMS request).
+ - `INK_CACHE_LOOKUP_HIT_FRESH` - Document was present in the
+ cache and was fresh. Document will be served from the cache.
+ - `INK_CACHE_LOOKUP_SKIPPED` - Traffic Server didn't perform a
+ cache lookup because the request was not cacheable (this can happen
+ when the URL looks dynamic or the request is marked as
+ noncacheable).
+
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if an error occurs while calling the API or if an
+ argument is invalid.
+
+
+#### INKHttpTxnCachedRespGet
+
+Gets the cached response header for a specified HTTP transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnCachedRespGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`hdr_loc`*)
+
+**Description**
+ ~ Retrieves the cached response header from the HTTP transaction
+ `<em class="replaceable"><code>txnp` and stores the cached response
+ header in `bufp`, at location
+ `<em class="replaceable"><code>hdr_loc`.
+
+ Call after `SEND_RESPONSE_HDR_HOOK`.
+
+ ![[Caution]](images/docbook/caution.png)
+ Caution
+ Do not modify any cached response headers returned by
+ `INKHttpTxnCachedRespGet`; the underlying data structure is
+ read-only. Release the returned
+ `<em class="replaceable"><code>hdr_loc` with a call to
+ `INKHandleMLocRelease`.
+
+**Returns**
+ ~ If the cached response header does not exist, then
+ `INKHttpTxnCachedRespGet` returns `0`.
+
+ Otherwise, it returns `1`.
+
+
+#### INKHttpTxnClientIncomingPortGet
+
+Gets the port on which the incoming request is received.
+
+**Prototype**
+ ~ `int INKHttpTxnClientIncomingPortGet (INKHttpTxn <em class="replaceable"><code>txnp`)
+
+**Description**
+ ~ Returns the port on which the HTTP transaction
+ `<em class="replaceable"><code>txnp` was received. This is not the
+ destination port in the URL; it is the proxy port to which the
+ client browser is pointed.
+
+ Call after `TXN_START_HOOK`.
+
+**Returns**
+ ~ The port number in host byte order.
+
+ Returns `-1` if an error occurred.
+
+
+#### INKHttpTxnClientIPGet
+
+Gets the client IP address for a specified HTTP transaction.
+
+**Prototype**
+ ~ `unsigned int INKHttpTxnClientIPGet (INKHttpTxn <em class="replaceable"><code>txnp`)
+
+**Description**
+ ~ Returns the IP address of the client for the HTTP transaction
+ `<em class="replaceable"><code>txnp`.
+
+ `INKHttpTxnClientIPGet` returns the IP address in network byte
+ order.
+
+ Call after `TXN_START_HOOK`.
+
+**Returns**
+ ~ The client IP address.
+
+ Returns `0` if an error occurred.
+
+
+#### INKHttpTxnClientRemotePortGet
+
+Gets the remote host's port number for a specified HTTP
+transaction.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnClientRemotePortGet(INKHttpTxn <em class="replaceable"><code>txnp`,
+ int \**`port`*)
+
+**Arguments**
+ ~ `INKHttpTxn`
+ `<code class="code"><em class="replaceable"><code>txnp` is an HTTP
+ transaction.
+
+ `int *``<em class="replaceable"><code>port` is set
+ to the client's remote port value (port number used by the client
+ when creating a socket connection with the proxy for the
+ transaction `<em class="replaceable"><code>txnp`) in network byte
+ order.
+
+**Description**
+ ~ Obtains the port number of the remote host for the specified
+ HTTP transaction. The port number is returned in network byte
+ order.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ This is an exception to the rule that port numbers are retrieved in
+ host byte order.
+
+ The proxy port on which the connection was accepted can be
+ retrieved using `INKHttpTxnClientIncomingPortGet`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if an error occurs while calling the API or if an
+ argument is invalid.
+
+
+#### INKHttpTxnClientReqGet
+
+Gets the client request header for a specified HTTP transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnClientReqGet (INKHttpTxn txnp, INKMBuffer *bufp, INKMLoc *hdr_loc)`
+
+**Description**
+ ~ Retrieves the client request header from the HTTP transaction
+ `<em class="replaceable"><code>txnp`. `INKHttpTxnClientReqGet`
+ stores the client request header in
+ `<em class="replaceable"><code>bufp`, at location
+ `<em class="replaceable"><code>hdr_loc`.
+
+ Call after `READ_REQUEST_HDR_HOOK`.
+
+ Release the returned `<em class="replaceable"><code>hdr_loc` with a
+ call to `INKHandleMLocRelease`.
+
+**Returns**
+ ~ If the client request header does not exist or if there is an
+ error, then `INKHttpTxnClientReqGet` returns `0`.
+
+ Otherwise, `1` is returned.
+
+
+#### INKHttpTxnClientRespGet
+
+Gets the client response header for a specified HTTP transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnClientRespGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`hdr_loc`*)
+
+**Description**
+ ~ Retrieves the client response header from the HTTP transaction
+ `<em class="replaceable"><code>txnp`. `INKHttpTxnClientRespGet`
+ stores the client response header in
+ `<em class="replaceable"><code>bufp`, at location
+ `<em class="replaceable"><code>hdr_loc`.
+
+ Call after `SEND_RESPONSE_HOOK`.
+
+ Release the returned `<em class="replaceable"><code>hdr_loc` with a
+ call to `INKHandleMLocRelease`.
+
+**Returns**
+ ~ If the client response header does not exist or if there is an
+ error, then `INKHttpTxnClientRespGet` returns `0`.
+
+ Otherwise, `1` is returned.
+
+
+#### INKHttpTxnErrorBodySet
+
+Sets the format and content of the error body (or response data)
+that Traffic Server sends to clients.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnErrorBodySet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ char \**`buf`*, int *`buflength`*, char \**`mimetype`*)
+
+**Arguments**
+ ~ `<em class="replaceable"><code>txnp` is the HTTP transaction to
+ act upon.
+
+ `<em class="replaceable"><code>buf` contains the error (or
+ response) body. The error body can be text, an HTML document,
+ image, or another format. Before you call `INKHttpTxnErrorBodySet,`
+ be sure to allocate `<em class="replaceable"><code>buf` using
+ `INKmalloc`.
+
+ `<em class="replaceable"><code>buflength` is the length of the
+ error body.
+
+ `<em class="replaceable"><code>mimetype` contains the format of the
+ error body. If you want to set the
+ `<em class="replaceable"><code>mimetype` to a value other than
+ `NULL`, then you must allocate
+ `<em class="replaceable"><code>mimetype` using `INKmalloc` before
+ you call `INKHttpTxnErrorBodySet`.
+
+**Description**
+ ~ Sets the format of the error body that Traffic Server sends
+ back when sending an error or response to a client. The error body
+ data is stored in the buffer `<em class="replaceable"><code>buf`.
+ If the error body is just plain text, then setting
+ `<em class="replaceable"><code>mimetype` to `NULL` is sufficient.
+ If the error body is HTML, then
+ `<em class="replaceable"><code>mimetype` should be "`text/html`".
+ If the error body is a JPEG image, then
+ `<em class="replaceable"><code>mimetype` should be "`image/jpeg`".
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ Traffic Server automatically calls `INKfree` to free
+ `<em class="replaceable"><code>buf` when it is no longer needed;
+ make sure that the buffer `<em class="replaceable"><code>buf` is
+ allocated by a call to `INKmalloc`. Similarly, if you want to set
+ `<em class="replaceable"><code>mimetype` to something other than
+ `NULL`, then make sure you allocate
+ `<em class="replaceable"><code>mimetype` with a call to
+ `INKmalloc`. Traffic Server automatically calls `INKfree` to free
+ `<em class="replaceable"><code>mimetype`.
+
+ Call after `SEND_RESPONSE_HDR_HOOK`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnHookAdd
+
+Adds a continuation to the list of HTTP transaction hooks for a
+specified HTTP transaction.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnHookAdd (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKHttpHookID *`id`*, INKCont *`contp`*)
+
+**Description**
+ ~ Adds `<em class="replaceable"><code>contp` to the end of the
+ list of HTTP transaction hooks specified by
+ `<em class="replaceable"><code>id`. Since
+ `<em class="replaceable"><code>contp` is added to a transaction, it
+ is not possible to call `INKHttpTxnHookAdd` from the plugin
+ initialization routine unless the plugin has a handle to an HTTP
+ transaction.
+
+ Call after `HTTP_TXN_START_HOOK`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnNextHopIPGet
+
+Gets the IP address of the next server from which Traffic Server
+tries to retrieve requested HTTP content.
+
+**Prototype**
+ ~ `unsigned int INKHttpTxnNextHopIPGet (INKHttpTxn <em class="replaceable"><code>txnp`)
+
+**Description**
+ ~ Returns the IP address of the next server from which Traffic
+ Server attempts to retrieve the requested document, in network byte
+ order. The IP address returned could be the origin server IP
+ address or it could be the parent proxy's IP address.
+
+ Call after `SEND_REQUEST_HDR_HOOK`.
+
+**Returns**
+ ~ Returns the IP address of the next server from which Traffic
+ Server attempts to retrieve the request, in network byte order.
+
+ Returns `0` if an error occurred.
+
+
+#### INKHttpTxnParentProxyGet
+
+Gets the parent proxy name and port, if parent proxying is
+enabled.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnParentProxyGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ char \*\**`hostname`*, int \**`port`*)
+
+**Description**
+ ~ Retrieves the value set previously by `INKHttpParentProxySet`.
+ Does not return values set in `parent.config` or `records.config`
+ for the `<i>proxy.config.http.parent_proxies </i>`parameter.
+
+ This function can be called from within any``transaction hook.
+
+ The `<i>hostname </i>` string returned must not be deallocated.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ If parent proxying is not enabled, then `INKHttpTxnParentProxyGet`
+ returns `NULL` for `<em class="replaceable"><code>hostname`*``*and
+ `-1` for `<i>port</i>`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnParentProxySet
+
+Sets the parent proxy name and port.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnParentProxySet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ char \**`hostname`*, int *`port`*)
+
+**Description**
+ ~ This can be used to overwrite the value set in the
+ `parent.config` file, or in `records.config` for the parameter
+ `<i>proxy.config.http.parent_proxies</i>`.
+
+ Call before or within `CACHE_LOOKUP_COMPLETE`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnPristineUrlGet
+
+Gets the pristine URL (the URL that came in from the client
+request, before remap) for a specified HTTP transaction.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnPristineUrlGet (INKHttpTxn <span class="replaceable">txnp</span>, INKMBuffer *<span class="replaceable">bufp</span>, INKMLoc *<span class="replaceable">url_loc</span>);`
+
+**Arguements**
+ ~ `INKHttpTxn <span class="replaceable">txnp </span>` is the
+ ongoing transaction.
+
+ `INKMBuffer *<span class="replaceable">bufp </span>` is the header
+ buffer pointer
+
+ `INKMLoc *<span class="replaceable">url_loc </span>` is the pointer
+ to the location where the pristine URL will be written.
+
+
+**Description**
+ ~ After remap, the URL returned by `INKHttpHdrUrlGet` may not be
+ the same as the original URL. This API provides a way to access the
+ URL that was part of the client request header.
+
+ Retrieves the pristine URL from the HTTP transaction txnp.
+ `INKHttpTxnPristineUrlGet` stores the pristine URL in bufp, at
+ location url\_loc. Call after `READ_REQUEST_HDR_HOOK`.
+
+ Release the returned url\_loc with a call to
+ `INKHandleMLocRelease`.
+
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if there is an error.
+
+**Example**
+ ~ if (INKHttpTxnPristineUrlGet(txnp, &bufp, &url_loc) == INK_SUCCESS)
+ {value = INKUrlHostGet(bufp, url_loc, &len); INKDebug (DEBUG_TAG, "Pristine Host: %s", value); INKHandleMLocRelease (bufp, INK_NULL_MLOC, url_loc);}
+ else {INKError ("INKHttpTxnPristineUrlGet returns 0.\n");
+
+
+#### INKHttpTxnReenable
+
+Tells a transaction if the processing of a particular hook has
+completed.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnReenable (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKEvent *`event`*)
+
+**Description**
+ ~ Notifies the HTTP transaction `<i>txnp </i>` that the plugin is
+ finished processing the current hook. If `INK_EVENT_HTTP_CONTINUE`
+ is specified for `<em class="replaceable"><code>event`, then the
+ plugin wants the transaction to continue. If `INK_EVENT_HTTP_ERROR`
+ is specified for `<em class="replaceable"><code>event`, then the
+ plugin wants the transaction to be terminated and an error is sent
+ back to the client (if no response has already been sent).
+
+ You must always reenable the HTTP transaction after each
+ transaction event is processed. However, you should never reenable
+ twice - this is a serious error.
+
+ When `<em class="replaceable"><code>event` is set to
+ `INK_EVENT_HTTP_ERROR`, Traffic Server performs different
+ processing depending on the type of hook involved.
+
+ - `INK_HTTP_TXN_START_HOOK`: the transaction is stopped right
+ away, then the client connection is closed and no response is sent
+ back to the origin server.
+ - `INK_HTTP_READ_REQUEST_HDR_HOOK`: Traffic Server does not send
+ a request to the origin server; it directly sends a 500 to the
+ client.
+ - `INK_HTTP_SEND_REQUEST_HDR_HOOK`: Traffic Server opens a
+ connection to the origin server, sends an empty request to it, and
+ sends a `500` status message back to the client. The connection to
+ the origin server is then closed.
+ - `INK_HTTP_READ_RESPONSE_HDR_HOOK`,
+ `INK_HTTP_SEND_RESPONSE_HOOK`, `INK_HTTP_OS_DNS_HOOK`,
+ `INK_HTTP_READ_CACHE_HDR_HOOK`, and
+ `INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`: Traffic Server receives all
+ headers in the origin server's response, closes the connection to
+ the origin server, and sends a `500` status message back to the
+ client. Traffic Server does not receive the response body.
+ - `INK_HTTP_TXN_CLOSE_HOOK`: the client receives whatever answer
+ was sent by the origin server because with this hook, the response
+ has already been sent to the clie
+
+Â
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnServerIPGet
+
+Gets the origin server IP address for a specified HTTP
+transaction.
+
+**Prototype**
+ ~ `unsigned int INKHttpTxnServerIPGet (INKHttpTxn <em class="replaceable"><code>txnp`)
+
+**Description**
+ ~ Returns the IP address of the origin server specified by the
+ client request in network byte order. `INKHttpTxnServerIPGet`
+ returns `0` if it is called before `INK_HTTP_OS_DNS_HOOK` in a
+ transaction.
+
+ Call after `INK_HTTP_OS_DNS_HOOK`.
+
+**Returns**
+ ~ Returns the origin server IP address in network byte order.
+
+ Returns `0` if an error occurred.
+
+
+#### INKHttpTxnServerReqGet
+
+Gets the server request header from a specified HTTP transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnServerReqGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`hdr_loc`*)
+
+**Description**
+ ~ Retrieves the server request header from the HTTP transaction
+ `<em class="replaceable"><code>txnp`. `INKHttpTxnServerReqGet`
+ stores the server request header in
+ `<em class="replaceable"><code>bufp`, at location
+ `<em class="replaceable"><code>hdr_loc`.
+
+ Call after `SEND_REQUEST_HDR_HOOK`.
+
+ Release the returned `<em class="replaceable"><code>hdr_loc` with a
+ call to `INKHandleMLocRelease`.
+
+**Returns**
+ ~ If the server request header does not exist or in the case of
+ an error, then `INKHttpTxnServerReqGet` returns `0`.
+
+ Otherwise, it returns `1`.
+
+
+#### INKHttpTxnServerRespGet
+
+Gets the server response header from a specified HTTP transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnServerRespGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`hdr_loc`*)
+
+**Description**
+ ~ Retrieves the server response header from the HTTP transaction
+ `<em class="replaceable"><code>txnp`. `INKHttpTxnServerRespGet`
+ stores the server response header in
+ `<em class="replaceable"><code>bufp`, at location
+ `<em class="replaceable"><code>hdr_loc`.
+
+ Call after `READ_RESPONSE_HDR_HOOK`.
+
+ Release the returned `<em class="replaceable"><code>hdr_loc` with a
+ call to `INKHandleMLocRelease`.
+
+**Returns**
+ ~ If the server response header does not exist or if there is an
+ error, then `INKHttpTxnServerRespGet` returns `0`.
+
+ Otherwise, `1` is returned.
+
+
+#### INKHttpTxnSetRespCacheableSet
+
+Makes a request/response cacheable.
+
+**Prototype**
+ ~ `void INKHttpTxnSetRespCacheableSet (INKHttpTxn <span class="replaceable">txnp</span>)`
+
+ `void INKHttpTxnSetReqCacheableSet (INKHttpTxn <span class="replaceable">txnp</span>);`
+
+**Description**
+ ~ Sets the request/response as cacheable for a given transaction
+ `<span class="replaceable"> txnp</span>`.
+
+**Returns**
+ ~ No values are returned by this function.
+
+
+#### INKHttpTxnSkipRww
+
+Turns off read while writing for a transaction.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnSkipRww (INKHttpTxn <span class="replaceable">txnp</span>)`
+
+**Description**
+ ~ ((TBD: pending additional info from developer))
+
+ ((TBD: ts-259))
+
+ ((TBD))
+
+**Returns**
+ ~ INK\_SUCCESS if successful.
+
+ INK\_ERROR if an error occurs.
+
+
+#### INKHttpTxnSsnGet
+
+Returns the session handle associated with a specific HTTP
+transaction.
+
+**Prototype**
+ ~ `INKHttpSsn INKHttpTxnSsnGet (INKHttpTxn <em class="replaceable"><code>txnp`)
+
+**Description**
+ ~ Retrieves the `INKHttpSsn` handle associated with the HTTP
+ transaction `<em class="replaceable"><code>txnp`.
+
+ Call after `TXN_START_HOOK`.
+
+**Returns**
+ ~ The session handle associated with the specified HTTP
+ transaction.
+
+ `INK_ERROR_PTR` if an error occurs.
+
+
+#### INKHttpTxnTransformedRespCache
+
+Indicates whether Traffic Server writes transformed documents to
+the cache.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnTransformedRespCache (INKHttpTxn <em class="replaceable"><code>txnp`,
+ int *`on`*)
+
+**Description**
+ ~ Specifies whether the transformed document should be written to
+ the cache. If a transformation is occurring, then the default is
+ for the transformed copy to be written to the cache. The default
+ maintains a rule that only a single version of a document is
+ written to the cache for a single transaction. It is valid for that
+ rule to be broken if you specify that both the transformed and
+ untransformed documents be written to the cache. Calls need to be
+ made prior to the actual transformation, (i.e. at the time of
+ creating the transformation) rather than in the transformation.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ This function does not overwrite HTTP directives (like
+ `Cache-Control` or `Expires`) that determine whether a document is
+ cached. If the document can be cached, then this function
+ determines if the transformed version should be cached.
+ Untransformed and transformed documents are cached as HTTP
+ alternates.
+
+ Call from within or after the hook `TXN_START_HOOK`.
+
+ If called after hook `SEND_RESPONSE_HDR`, then this function is not
+ taken into account by Traffic Server.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
+#### INKHttpTxnTransformRespGet
+
+Gets the transform response header from a specified HTTP
+transaction.
+
+**Prototype**
+ ~ `int INKHttpTxnTransformRespGet (INKHttpTxn <em class="replaceable"><code>txnp`,
+ INKMBuffer \**`bufp`*, INKMLoc \**`offset`*)
+
+**Description**
+ ~ Retrieves the transform response header from the HTTP
+ transaction `<em class="replaceable"><code>txnp` and stores the
+ transform response header in `<em class="replaceable"><code>bufp`,
+ at location `<em class="replaceable"><code>offset`.
+
+ Call from within your transformation, before transform data is
+ written to the downstream vconnection.
+
+**Returns**
+ ~ If the transform response header does not exist, then
+ `INKHttpTxnTransformRespGet` returns `0`.
+
+ Otherwise, `1` is returned.
+
+
+#### INKHttpTxnUntransformedRespCache
+
+Indicates whether Traffic Server writes untransformed documents to
+cache.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnUntransformedRespCache (INKHttpTxn <em class="replaceable"><code>txnp`,
+ int *`on`*)
+
+**Description**
+ ~ Specifies whether the untransformed document should be written
+ to the cache. If there is no transformation occurring, then the
+ untransformed copy is written to the cache (by default). If a
+ transformation is occurring, then the untransformed copy is not
+ written to the cache (by default). The default rules dictate that
+ only a single version of a document is written to the cache for a
+ single transaction. It is valid for that rule to be broken by
+ specifying that both the transformed and untransformed document be
+ written to the cache. Calls need to be made prior to the actual
+ transformation (i.e. at the time of creating the transformation),
+ rather than in the transformation.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ This function does not overwrite HTTP directives (ike
+ `Cache-Control` or `Expires`) that determine if a document can be
+ cached. If the document can be cached, then this function
+ determines if the untransformed version should be cached.
+ Untransformed and transformed documents are cached as HTTP
+ alternates.
+
+ Call from within or after hook `TXN_START_HOOK`.
+
+ If called after hook `SEND_RESPONSE_HDR`, then Traffic Server does
+ not take this function into account.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransformationPlugins.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransformationPlugins.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransformationPlugins.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTPTransformationPlugins.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,161 @@
+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](SetTransactionHook) - Setting a Transaction Hook
+The Sample Null Transform Plugin -
+[Next](SampleNullTransformPlugin)
+## Chapter 5. HTTP Transformation Plugins
+
+Transform plugins examine or transform HTTP message body content.
+For example, transform plugins can:
+
+- Append text to HTML documents
+
+- Compress images
+
+- Do virus checking (on client `POST` data or server response
+ data)
+
+- Do content-based filtering (filter out HTML documents that
+ contain certain terms or expressions)
+
+
+This chapter explains how to write transform plugins. The following
+examples are discussed in detail:
+
+- [Sample Null Transform Plugin](SampleNullTransformPlugin "The Sample Null Transform Plugin")
+
+- [Append-Transform Plugin](AppendTransformPlugin "The Append-Transform Plugin")
+- [Sample Buffered Null Transform Plugin](SampleBufferedNullTransformPlugin "The Sample Buffered Null Transform Plugin")
+
+
+## Writing Content Transform Plugins
+
+Content transformation plugins transform HTTP response content
+(such as images or HTML documents) and HTTP request content (such
+as client `POST` data). Because the data stream to be transformed
+is of variable length, these plugins must use a mechanism that
+passes data from buffer to buffer *and* checks to see if the end of
+the data stream is reached. This mechanism is provided by virtual
+connections (vconnections) and virtual IO descriptors (VIOs).
+
+A **vconnection** is an abstraction for a data pipe that allows its
+users to perform asynchronous reads and writes without knowing the
+underlying implementation. A transformation is a specific type of
+vconnection. A **transformation** connects an input data source and
+an output data sink; this feature enables it to view and modify all
+the data passing through it.
+
+Transformations can be chained together, one after the other, so
+that multiple transformations can be performed on the same content.
+The vconnection type, `INKVConn`, is actually a subclass of
+`INKCont`, which means that vconnections (and transformations) are
+continuations. Vconnections and transformations can thus exchange
+events, informing one another that data is available for reading or
+writing, or that the end of a data stream is reached.
+
+A **VIO** is a description of an IO operation that is in progress.
+Every vconnection has an associated *input VIO* and an associated
+*output VIO*. When vconnections are transferring data to one
+another, one vconnection's input VIO is another vconnection's
+output VIO. A vconnection's input VIO is also called its
+**write VIO** because the input VIO refers to a write operation
+performed on the vconnection itself. Similarly, the outpt VIO is
+also called the **read VIO**. For transformations, which are
+designed to pass data in one direction, you can picture the
+relationship between the transformation vconnection and its VIOs as
+follows:
+
+**Figure 5.1. A Transformation and its VIOs**
+
+
+Because the Traffic Server API places transformations directly in
+the response or request data stream, the transformation vconnection
+is responsible only for reading the data from the input buffer,
+transforming it, and then writing it to the output buffer. The
+upstream vconnection writes the incoming data to the
+transformation's input buffer. In the figure above,
+[A Transformation and its VIOs](HTTPTransformationPlugins#Fig_TransformationAndVIOs "Figure 5.1. A Transformation and its VIOs"),
+the input VIO describes the progress of the upstream vconnection's
+write operation on the transformation, while the output VIO
+describes the progress of the transformation's write operation on
+the output (downstream) vconnection. The **nbytes** value in the
+VIO is the total number of bytes to be written. The **ndone** value
+is the current progress, or the number of bytes that have been
+written at a specific point in time.
+
+When writing a transformation plugin, you must understand
+implementation as well as the use of vconnections. The
+*implementor's side*refers to how to implement a vconnection that
+others can use. At minimum, a transform plugin creates a
+transformation that sits in the data stream and must be able to
+handle the events that the upstream and downstream vconnections
+send to it. The *user's side*refers to how to use a vconnection to
+read or write data. At the very least, transformations output
+(write) data.
+
+### Transformations
+
+
+
+### VIOs
+
+A **VIO** or virtual IO is a description of an in progress IO
+operation. The VIO data structure is used by vconnection users to
+determine how much progress has been made on a particular IO
+operation, and to reenable an IO operation when it stalls due to
+buffer space. Vconnection implementors use VIOs to determine the
+buffer for an IO operation, how much work to do on the IO
+operation, and which continuation to call back when progress on the
+IO operation is made.
+
+The `INKVIO<a class="indexterm" name="id374498"></a>` data
+structure itself is opaque, but it might have been defined as
+follows:
+
+ typedef struct {
+ INKCont continuation;
+ INKVConn vconnection;
+ INKIOBufferReader reader;
+ INKMutex mutex;
+ int nbytes;
+ int ndone;
+ } *INKVIO;
+
+### IO Buffers
+
+The **IO buffer** data structure is the building block of the
+vconnection abstraction. An IO buffer is composed of a list of
+buffer blocks which, in turn, point to buffer data. Both the
+*buffer block* (`INKIOBufferBlock`) and *buffer data*
+(`INKIOBufferData`) data structures are reference counted so they
+can reside in multiple buffers at the same time. This makes it
+extremely efficient to copy data from one IO buffer to another
+using `INKIOBufferCopy`, since Traffic Server only needs to copy
+pointers and adjust reference counts appropriately (instead of
+actually copying any data).
+
+The IO buffer abstraction provides for a single writer and multiple
+readers. In order for the readers to have no knowledge of each
+other, they manipulate IO buffers through the`INKIOBufferReader`
+data structure. Since only a single writer is allowed, there is no
+corresponding `INKIOBufferWriter` data structure. The writer simply
+modifies the IO buffer directly.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTP_Transactions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTP_Transactions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTP_Transactions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HTTP_Transactions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,211 @@
+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](HTTPSessions) - HTTP Sessions
+Intercepting HTTP Transactions - [Next](InterceptingHTTPTx)
+## HTTP Transactions
+
+The HTTP transaction functions enable you to set up plugin
+callbacks to HTTP transactions and obtain/modify information about
+particular HTTP transactions.
+
+As described in the section on HTTP sessions, an
+**HTTP transaction** is an object defined for the lifetime of a
+single request from a client and the corresponding response from
+Traffic Server. The `<b>INKHttpTxn</b>` structure is the main
+handle given to a plugin for manipulating a transaction's internal
+state. Additionally, an HTTP transaction has a reference back to
+the HTTP session that created it.
+
+The sample code below illustrates how to register locally to a
+transaction and associate data to the transaction.
+
+ /*
+ * Simple plugin that illustrates:
+ * - how to register locally to a transaction
+ * - how to deal with data that's associated with a tranaction
+ *
+ * Note: for readability, error checking is omitted
+ */
+
+ #include <ts/ts.h>
+
+ #define DBG_TAG "txn"
+
+ /* Structure to be associated to txns */
+ typedef struct {
+ int i;
+ float f;
+ char *s;
+ } TxnData;
+
+ /* Allocate memory and init a TxnData structure */
+ TxnData *
+ txn_data_alloc()
+ {
+ TxnData *data;
+ data = INKmalloc(sizeof(TxnData));
+
+ data->i = 1;
+ data->f = 0.5;
+ data->s = "Constant String";
+ return data;
+ }
+
+ /* Free up a TxnData structure */
+ void
+ txn_data_free(TxnData *data)
+ {
+ INKfree(data);
+ }
+
+ /* Handler for event READ_REQUEST and TXN_CLOSE */
+ static int
+ local_hook_handler (INKCont contp, INKEvent event, void *edata)
+ {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ TxnData *txn_data = INKContDataGet(contp);
+ switch (event) {
+ case INK_EVENT_HTTP_READ_REQUEST_HDR:
+ /* Modify values of txn data */
+ txn_data->i = 2;
+ txn_data->f = 3.5;
+ txn_data->s = "Constant String 2";
+ break;
+
+ case INK_EVENT_HTTP_TXN_CLOSE:
+ /* Print txn data values */
+ INKDebug(DBG_TAG, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f,
+ txn_data->s);
+
+ /* Then destroy the txn cont and its data */
+ txn_data_free(txn_data);
+ INKContDestroy(contp);
+ break;
+
+ default:
+ INKAssert(!"Unexpected event");
+ break;
+ }
+
+ INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);
+ return 1;
+ }
+
+ /* Handler for event TXN_START */
+ static int
+ global_hook_handler (INKCont contp, INKEvent event, void *edata)
+ {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ INKCont txn_contp;
+ TxnData *txn_data;
+
+ switch (event) {
+ case INK_EVENT_HTTP_TXN_START:
+ /* Create a new continuation for this txn and associate data to it */
+ txn_contp = INKContCreate(local_hook_handler, INKMutexCreate());
+ txn_data = txn_data_alloc();
+ INKContDataSet(txn_contp, txn_data);
+
+ /* Registers locally to hook READ_REQUEST and TXN_CLOSE */
+ INKHttpTxnHookAdd(txnp, INK_HTTP_READ_REQUEST_HDR_HOOK, txn_contp);
+ INKHttpTxnHookAdd(txnp, INK_HTTP_TXN_CLOSE_HOOK, txn_contp);
+ break;
+
+ default:
+ INKAssert(!"Unexpected event");
+ break;
+ }
+
+ INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);
+ return 1;
+ }
+
+
+ void
+ INKPluginInit (int argc, const char *argv[])
+ {
+ INKCont contp;
+
+ /* Note that we do not need a mutex for this txn since it registers globally
+ and doesn't have any data associated with it */
+ contp = INKContCreate(global_hook_handler, NULL);
+
+ /* Register gloabally */
+ INKHttpHookAdd(INK_HTTP_TXN_START_HOOK, contp);
+ }
+
+See [Adding Hooks](AddingHooks "Adding Hooks") for background
+about HTTP transactions and HTTP hooks, as well as
+[HTTP Hooks and Transactions](HTTPHooksAndTransactions "Chapter 8. HTTP Hooks and Transactions").
+Also see the
+[HTTP Transaction State Diagram](HTTPHooksAndTransactions#Fig_HHTTPTxStateDiag "Figure 8.1. HTTP Transaction State Diagram")
+for an illustration of the steps involved in a typical HTTP
+transaction.
+
+The HTTP transaction functions are:
+
+- [INKHttpTxnCacheLookupStatusGet](HTTPTransactionFunctions#INKHttpTxnCacheLookupStatusGet "INKHttpTxnCacheLookupStatusGet")
+
+- [INKHttpTxnCachedReqGet](HTTPTransactionFunctions#INKHttpTxnCachedReqGet "INKHttpTxnCachedReqGet")
+ - Note that it is an error to modify cached headers.
+
+- [INKHttpTxnCachedRespGet](HTTPTransactionFunctions#INKHttpTxnCachedRespGet "INKHttpTxnCachedRespGet")
+ - Note that it is an error to modify cached headers.
+
+- [INKHttpTxnClientIncomingPortGet](HTTPTransactionFunctions#INKHttpTxnClientIncomingPortGet "INKHttpTxnClientIncomingPortGet")
+
+- [INKHttpTxnClientIPGet](HTTPTransactionFunctions#INKHttpTxnClientIPGet "INKHttpTxnClientIPGet")
+
+- [INKHttpTxnClientRemotePortGet](HTTPTransactionFunctions#INKHttpTxnClientRemotePortGet "INKHttpTxnClientRemotePortGet")
+
+- [INKHttpTxnClientReqGet](HTTPTransactionFunctions#INKHttpTxnClientReqGet "INKHttpTxnClientReqGet")
+ - Plugins that must read client request headers use this call to
+ retrieve the HTTP header.
+
+- [INKHttpTxnClientRespGet](HTTPTransactionFunctions#INKHttpTxnClientRespGet "INKHttpTxnClientRespGet")
+
+- [INKHttpTxnErrorBodySet](HTTPTransactionFunctions#INKHttpTxnErrorBodySet "INKHttpTxnErrorBodySet")
+
+- [INKHttpTxnHookAdd](HTTPTransactionFunctions#INKHttpTxnHookAdd "INKHttpTxnHookAdd")
+
+- [INKHttpTxnNextHopIPGet](HTTPTransactionFunctions#INKHttpTxnNextHopIPGet "INKHttpTxnNextHopIPGet")
+
+- [INKHttpTxnNextHopIPGet](HTTPTransactionFunctions#INKHttpTxnNextHopIPGet "INKHttpTxnNextHopIPGet")
+
+- [INKHttpTxnParentProxySet](HTTPTransactionFunctions#INKHttpTxnParentProxySet "INKHttpTxnParentProxySet")
+
+- [INKHttpTxnReenable](HTTPTransactionFunctions#INKHttpTxnReenable "INKHttpTxnReenable")
+
+- [INKHttpTxnServerIPGet](HTTPTransactionFunctions#INKHttpTxnServerIPGet "INKHttpTxnServerIPGet")
+
+- [INKHttpTxnServerReqGet](HTTPTransactionFunctions#INKHttpTxnServerReqGet "INKHttpTxnServerReqGet")
+
+- [INKHttpTxnServerRespGet](HTTPTransactionFunctions#INKHttpTxnServerRespGet "INKHttpTxnServerRespGet")
+
+- [INKHttpTxnSsnGet](HTTPTransactionFunctions#INKHttpTxnSsnGet "INKHttpTxnSsnGet")
+
+- [INKHttpTxnTransformedRespCache](HTTPTransactionFunctions#INKHttpTxnTransformedRespCache "INKHttpTxnTransformedRespCache")
+
+- [INKHttpTxnTransformRespGet](HTTPTransactionFunctions#INKHttpTxnTransformRespGet "INKHttpTxnTransformRespGet")
+
+- [INKHttpTxnUntransformedRespCache](HTTPTransactionFunctions#INKHttpTxnUntransformedRespCache "INKHttpTxnUntransformedRespCache")
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HeaderBasedPluginEx.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HeaderBasedPluginEx.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HeaderBasedPluginEx.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HeaderBasedPluginEx.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,86 @@
+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](ch03s02) - API Function Reference
+The Blacklist Plugin - [Next](BlacklistPlugin)
+## Chapter 4. Header-Based Plugin Examples
+
+**Table of Contents**
+
+- [The Blacklist Plugin](BlacklistPlugin)
+- - [Creating the Parent Continuation](BlacklistPlugin#CreatingParentContinuation)
+ - [Setting a Global Hook](SettingGlobalHook)
+ - [Setting Up UI Update Callbacks](SettingUpUIUpdateCallbacks)
+ - [Accessing the Transaction Being Processed](AccessingTransactionProc)
+ - [Setting Up a Transaction Hook](SettingUpTransacHook)
+ - [Working with HTTP Header Functions](WorkWHTTPHeaderFunc)
+
+
+- [The Basic Authorization Plugin](BasicAuthorizatonPlugin)
+- - [Creating the Plugin's Parent Continuation and Global Hook](BasicAuthorizatonPlugin#CreatePluginParentCont_GlHk)
+ - [Implementing the Handler and Getting a Handle to the Transaction](ImplementHandler_GetTransHandle)
+ - [Working With HTTP Headers](WorkWithHTTPHeaders)
+ - [Setting a Transaction Hook](SetTransactionHook)
+
+
+Header-based plugins read or modify the headers of HTTP messages
+that Traffic Server sends and receives. Reading this chapter will
+help you to understand the following topics:
+
+- Creating continuations for your plugins
+
+- Adding global hooks
+
+- Adding transaction hooks
+
+- Working with HTTP header functions
+
+
+The two sample plugins discussed in this chapter are
+`blacklist-1.c` and `basic-auth.c`.
+
+## Overview
+
+Header-based plugins take actions based on the contents of HTTP
+request or response headers. Examples include filtering (on the
+basis of requested URL, source IP address, or other request
+header), user authentication, or user redirection. Header-based
+plugins have the following common elements:
+
+**
+The plugin has a static parent continuation that scans all Traffic
+Server headers (either request headers, response headers, or
+both).
+
+The plugin has a global hook. This enables the plugin to check all
+transactions to determine if the plugin needs to do something.
+
+The plugin gets a handle to the transaction being processed through
+the global hook.
+
+If the plugin needs to do something to transactions in specific
+cases, then it sets up a transaction hook for a particular event.
+
+The plugin obtains client header information and does something
+based on that information.
+
+This chapter demonstrates how these components are implemented in
+SDK sample code.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostLookupFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostLookupFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostLookupFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostLookupFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,76 @@
+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](INKActionDone) - INKActionDone
+INKHostLookupResultIPGet - [Next](INKHostLookupResultIPGet)
+## Host Lookup Functions
+
+****
+[INKHostLookup](HostLookupFunctions#INKHostLookup)
+[INKHostLookupResultIPGet](INKHostLookupResultIPGet)
+### INKHostLookup
+
+Instructs Traffic Server to do a DNS lookup on a host name.
+
+**Prototype**
+ ~ `INKAction INKHostLookupResult (INKCont <em class="replaceable"><code>contp`,
+ char \**`hostname`*, int *`namelen`*)
+
+**Arguments**
+ ~ `INKCont` `<em class="replaceable"><code>contp` is the
+ continuation Traffic Server calls back when the DNS lookup occurs.
+
+ `char *``<em class="replaceable"><code>hostname` is
+ the name to look up. Null-terminated.
+
+ `int``<em class="replaceable"><code>namelen` is the length of
+ `<em class="replaceable"><code>hostname` +1 (add one to account for
+ null termination).
+
+**Description**
+ ~ Initiates a DNS lookup of
+ `<em class="replaceable"><code>hostname`. When the lookup occurs,
+ Traffic Server sends contp `INK_EVENT_DNS_LOOKUP`. If the lookup is
+ successful (IP address resolved), then the
+ `void *``<em class="replaceable"><code>data` passed to the handler
+ of the continuation `<em class="replaceable"><code>contp` is a data
+ of type `INKHostLookupResult`. You can then use
+ `INKHostLookupResultIPGet` to convert this information to an
+ unsigned `int` representing the IP address.
+
+ If the lookup fails (IP address not resolved), then the `void *`
+ `<em class="replaceable"><code>data` passed to the handler of
+ continuation `<em class="replaceable"><code>contp` is a null
+ pointer.
+
+ You have the option to cancel the action returned by
+ `INKHostLookup` by using `INKActionCancel`.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ Reentrant calls are possible; i.e., the cache can call back the
+ user (`contp`) in the same call.
+
+**Returns**
+ ~ An `INKAction` object if successful.
+
+ `INK_ERROR_PTR` if an argument is incorrect or if the API fails.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostsLookupAPI.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostsLookupAPI.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostsLookupAPI.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/HostsLookupAPI.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,32 @@
+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](ActionsGuide) - Chapter 14. Actions Guide
+Chapter 15. IO Guide - [Next](IOGuide)
+## Hosts Lookup API
+
+The hosts lookup enables plugins to ask Traffic Server to do a host
+lookup of a host name, much like a DNS lookup.
+
+The hosts lookup functions are as follows:
+
+- [`INKHostLookup`](HostLookupFunctions#INKHostLookup "INKHostLookup")
+- `<a href="INKHostLookupResultIPGet.html" title="INKHostLookupResultIPGet">INKHostLookupResultIPGet</a>`
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKActionDone.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKActionDone.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKActionDone.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKActionDone.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,61 @@
+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](ActionFunctions) - Action Functions: INKActionCancel
+Host Lookup Functions - [Next](HostLookupFunctions)
+### INKActionDone
+
+Indicates whether an action is completed.
+
+**Prototype**
+ ~ `int INKActionDone (INKAction <em class="replaceable"><code> actionp`)
+
+**Description**
+ ~ `<em class="replaceable"><code>actionp` is a completed action.
+ If a `NULL` argument is passed to `INKActionDone`, then Traffic
+ Server crashes and does not return `INK_ERROR`.
+
+ ~ **Note:** It is the programmer's responsibility to ensure that
+ a non-null value is passed to `INKActionDone`.
+
+ ![[Important]](images/docbook/important.png)
+ Important
+ Always use `INKActionDone` immediately after the call that assigns
+ the action.
+ For example:
+
+ actionp = INKContSchedule(contp, SOME_TIMEOUT_VALUE);
+ if (INKActionDone(actionp)){
+ //event has already occurred
+ }
+
+ If you call `INKActionDone``(<em class="replaceable">actionp</em>)`
+ some time later or somewhere else, then it always returns `false`
+ and therefore does not accurately reflect whether the action has
+ completed.
+
+**Returns**
+ ~ `0` if the action has not completed.
+
+ `1` if the action has completed.
+
+ `INK_ERROR` if an error has occurred.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKAssert.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKAssert.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKAssert.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKAssert.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +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](INKError) - INKError
+INKReleaseAssert - [Next](INKReleaseAssert)
+### INKAssert
+
+Enables the use of assertion in a plugin.
+
+**Prototype**
+ ~ `void INKAssert(<em class="replaceable"><code>expression`);
+
+**Arguments**
+ ~ A Boolean expression.
+
+**Description**
+ ~ In `debug` mode, causes the Traffic Server to print the file
+ name, line number, and expression before it aborts.
+
+ In `optim` mode, the expression is not removed, but the effects of
+ printing an error message and aborting are. This is an artifact of
+ the way the system assert is normally used and permits:
+
+ ink_assert(!setsockopt(...));
+
+ **Note:** when using the system "assert", you do not need to worry
+ about the condition since the code will be 'dead code eliminated'
+ by the compiler; with `INKAssert`, you do.
+
+**Example**
+ ~ switch (event) {
+ case EVENT_IMMEDIATE:
+ ....
+ default:
+ INKAssert (!setsockopt(...));
+ break;
+ }
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDestroy.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDestroy.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDestroy.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDestroy.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,45 @@
+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](INKCacheKeyHostNameSet) - INKCacheKeyHostNameSet
+INKCacheRead - [Next](INKCacheRead)
+### INKCacheKeyDestroy
+
+Destroys a cache key.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheKeyDestroy(INKCacheKey <em class="replaceable"><code>key`)
+
+**Arguments**
+ ~ `INKCacheKey` `<em class="replaceable"><code>key` is the key to
+ be destroyed.
+
+**Description**
+ ~ Destroys a cache key (deallocates memory). You must destroy
+ cache keys when you are finished with them (i.e., after all reads
+ and writes are completed).
+
+**Returns**
+ ~ `INK_SUCCESS` if the cache key was successfully destroyed.
+
+ `INK_ERROR` if the cache key could not be deallocated or was not
+ valid.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,63 @@
+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](CacheInterfaceFunctions) - Cache Interface Fxns:
+INKCacheKeyCreate, INKSetCacheUrl
+INKCacheKeyHostNameSet - [Next](INKCacheKeyHostNameSet)
+### INKCacheKeyDigestSet
+
+Generates and assigns a cache key to an object that will be
+cached.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheKeyDigestSet(INKCacheKey <em class="replaceable"><code>key`,
+ const unsigned char \**`input`*, int *`length`*)
+
+**Arguments**
+ ~ `INKCacheKey` `<em class="replaceable"><code>key` is the key
+ that will be associated with the cached object. Before calling
+ `INKCacheKeyDigestSet`, you must create the key with
+ `INKCacheKeyCreate`. Note that in order to generate unique keys,
+ you must use unique input strings. This means that if the input
+ strings are identical, then `INKCacheKeyCreate` generates identical
+ keys.
+
+ `const unsigned char *``<em class="replaceable"><code>input`
+ is a character string that uniquely identifies the object. In most
+ cases, it's the URL of the object.
+
+ `int``<em class="replaceable"><code>length` is the length of the
+ input string.
+
+**Description**
+ ~ Generates and assigns a cache key to the object to be cached.
+
+**Returns**
+ ~ `INK_SUCCESS` if the cache key is successfully generated.
+
+ `INK_ERROR` if `INKCacheKeyDigestSet` cannot be set.
+
+**Example**
+ ~ const char *digest_string = "mydigest"
+ INKCacheKey mykey;
+ INKCacheKeyCreate(&mykey);
+ INKCacheKeyDigestSet(mykey,digest_string, strlen(digest_string);
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,55 @@
+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](INKCacheKeyDigestSet) - INKCacheKeyDigestSet
+INKCacheKeyDestroy - [Next](INKCacheKeyDestroy)
+### INKCacheKeyHostNameSet
+
+Associates a host name to a cache key. Use if you want to support
+cache partitioning by host name.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheKeyHostNameSet(INKCacheKey <em class="replaceable"><code>key`,
+ const unsigned char *`*hostname`*, int *`host_len`*;
+
+**Arguments**
+ ~ `INKCacheKey` `<em class="replaceable"><code>key` is the key to
+ the cached object.
+
+ `const unsigned char <em class="replaceable"><code>*hostname` ** is
+ the host name you are associating with the cache key.
+
+ `int <em class="replaceable"><code>host_len` is the length of the
+ string `<em class="replaceable"><code>hostname`.
+
+**Description**
+ ~ Associates a host name to a cache key. The host name setting is
+ used in conjunction with the Traffic Server configuration files
+ `partition.config` and `hosting.config` that enable you to specify
+ under which cache partition the object should be stored.
+
+**Returns**
+ ~ `INK_SUCCESS` if the `<em class="replaceable"><code> hostname`
+ is successfully associated with the cache key.
+
+ `INK_ERROR` if `<em class="replaceable"><code>hostname` cannot be
+ set or is invalid.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,76 @@
+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](INKCacheRemove) - INKCacheRemove
+INKVConnCacheObjectSizeGet -
+[Next](INKVConnCacheObjectSizeGet)
+### INKCacheKeyPinnedSet
+
+Pins the document corresponding to the specified key in the cache
+so that the garbage collection process does not delete the document
+from the cache for the specified number of seconds.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheKeyPinnedSet (INKCacheKey <em class="replaceable"><code>key`,
+ time\_t *`pin_in_cache`*)
+
+**Arguments**
+ ~ `INKCacheKey` `<em class="replaceable"><code>key` is the cache
+ key for the document to be pinned.
+
+ `time_t <em class="replaceable"><code>pin_in_cache`
+ represents the number of seconds the document is to be pinned in
+ the cache.
+
+**Description**
+ ~ Pins the document corresponding to the specified
+ `<em class="replaceable"><code>key` in the cache for the specified
+ number of seconds specified in
+ `<em class="replaceable"><code>pin_in_cache`. Once the document is
+ pinned, the garbage collection will not delete this document from
+ the specifed number of seconds and the document can even persist
+ across Traffic Server re-runs. However, after the
+ `<em class="replaceable"><code>pin_in_cache` interval has expired,
+ the cache may delete the document at any time in order to reclaim
+ space.
+
+ To delete this document before the
+ `<em class="replaceable"><code>pin_in_cache` interval expires, call
+ the `INKCacheRemove()` function with the document's cache key.
+
+ `InkCacheKeyPinnedSet()` should be used after a key is created and
+ before writing the document to cache using `I``NKCacheWrite()`.
+
+ Because a document is not pinned in the cache by default, it can be
+ garbage-collected at anytime.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ It is important that the `records.config` variable
+ `<i>proxy.config.cache.permit.pinning </i>` (in `records.config`)
+ is set to 1 to enable pinning.
+
+**Returns**
+ ~ `INK_SUCCESS` if the specified object was successfully pinned
+ in the cache.
+
+ `INK_ERROR` if the pin could not be set or is invalid.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRead.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRead.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRead.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRead.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,96 @@
+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](INKCacheKeyDestroy) - INKCacheKeyDestroy
+INKCacheReady - [Next](INKCacheReady)
+### INKCacheRead
+
+Initiates a cache read or lookup of an object in the Traffic Server
+cache.
+
+**Prototype**
+ ~ `INKAction INKCacheRead (INKCont <em class="replaceable"><code>contp`,
+ INKCacheKey *`key`*)
+
+**Arguments**
+ ~ `INKCont` `<em class="replaceable"><code>contp` is the
+ continuation the cache calls back (telling it whether the object
+ exists and can be read).
+
+ `INKCacheKey` `<em class="replaceable"><code>key` is the cache key
+ corresponding to the object to be read.
+
+**Description**
+ ~ Asks the Traffic Server cache if the object corresponding to
+ `<em class="replaceable"><code>key` exists in the cache and can be
+ read.
+
+ You can do a cache lookup to determine whether or not an object is
+ in the cache. To do a cache lookup, call `INKCacheRead` on a
+ continuation `<em class="replaceable"><code>contp`. If the object
+ can be read, then the cache calls
+ `<em class="replaceable"><code>contp` back with the event
+ `INK_EVENT_CACHE_OPEN_READ`. In this case, the cache also passes
+ `<em class="replaceable"><code>contp` a cache vconnection;
+ `<em class="replaceable"><code>contp` can then initiate a read
+ operation on that vconnection using `INKVConnRead`.
+ `INKVConnCacheObjectSizeGet` can be used to determine the size of
+ the object in the cache.
+
+ If the object cannot be read (if, for instance, it is not in the
+ cache), then the cache calls `<em class="replaceable"><code>contp`
+ back with the event `INK_EVENT_CACHE_OPEN_READ_FAILED`. An error
+ code is passed in the `void *edata` argument of
+ `<em class="replaceable"><code>contp`. The error code can be:
+
+ - `INK_CACHE_ERROR_NOT_READY`: trying to access to the cache
+ while it's not yet initialized.
+
+ - `INK_CACHE_ERROR_NO_DOC`: document does not exist in cache.
+
+ - `INK_CACHE_ERROR_DOC_BUSY`: trying to read a document while
+ another continuation is writing on it.
+
+ - Any other value: unknown read failure
+
+
+ Finally, once you have performed a cache lookup, you can write into
+ cache with `INKCacheWrite`. The user
+ (`<em class="replaceable"><code>contp`) also has the option to
+ cancel the action returned by `INKCacheRead` by using
+ `INKActionCancel`.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ It is up to the user to read the data from the cache `vc iobuffer`
+ and consume it. The cache does not bufferize the data and will not
+ call the user back unless all the data from the `cache iobuffer` is
+ consumed.
+
+ Reentrant calls are possible; in other words, the cache can call
+ back the user (`<em class="replaceable"><code>contp`) in the same
+ call.
+
+**Returns**
+ ~ An `INKAction` object if successful.
+
+ `INK_ERROR_PTR` if an argument is incorrect or if the API failed.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheReady.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheReady.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheReady.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheReady.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,52 @@
+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](INKCacheRead) - INKCacheRead
+INKCacheWrite - [Next](INKCacheWrite)
+### INKCacheReady
+
+Determines if the Traffic Server cache is initialized and ready to
+accept requests for the specified data type.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheReady (int *<em class="replaceable"><code>is_ready`)
+
+**Arguments**
+ ~ If the cache is ready, then the
+ `int *<em class="replaceable"><code>is_ready` argument is set to a
+ non-zero value. It is set to 0 if the cache is not ready.
+
+**Description**
+ ~ Asks the Traffic Server cache if it is initialized and ready to
+ accept requests. If the cache is not initialized, then any attempts
+ to read, write, or remove documents will fail.
+
+ When a plugin starts (i.e., when its `INKPluginInit` function is
+ called), there is no guarantee that the cache is already
+ initialized. This API is useful if a plugin needs to access the
+ cache from the `INKPluginInit` function. If the cache is not ready,
+ then the plugin should retry later.
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if this function cannot be set or if it is invalid.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRemove.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRemove.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRemove.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/INKCacheRemove.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,76 @@
+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](INKCacheWrite) - INKCacheWrite
+INKCacheKeyPinnedSet - [Next](INKCacheKeyPinnedSet)
+### INKCacheRemove
+
+Removes an object from the Traffic Server cache.
+
+**Prototype**
+ ~ `INKAction INKCacheRemove (INKCont <em class="replaceable"><code>contp`,
+ INKCacheKey *`key`*)
+
+**Arguments**
+ ~ `INKCont` `<em class="replaceable"><code>contp` is the
+ continuation the cache calls back when reporting the success or
+ failure of the remove.
+
+ `INKCacheKey` `<em class="replaceable"><code>key` is the cache key
+ that corresponds to the object tol be removed.
+
+**Description**
+ ~ Removes the object corresponding to
+ `<em class="replaceable"><code>key` from the cache.
+
+ If the object was removed successfully, then the cache calls
+ `<em class="replaceable"><code>contp` back with the event
+ `INK_EVENT_CACHE_REMOVE`.
+
+ If the object was not found in the cache, then the cache calls
+ `<em class="replaceable"><code>contp` back with the event
+ `INK_EVENT_CACHE_REMOVE_FAILED`. An error code is passed in the
+ `void *edata` argument of `<em class="replaceable"><code>contp`.
+ The error code can be:
+
+ - `INK_CACHE_ERROR_NOT_READY`: tried to access the cache before
+ it was initialized.
+
+ - `INK_CACHE_ERROR_NO_DOC`: doc doesn't exist in cache
+
+ - any other value: unknown remove failure
+
+
+ In both of these callbacks, the user does not have to do anything.
+ The user does not get a vconnection from the cache, since no data
+ needs to be transferred. When the cache calls the user back with
+ `INK_EVENT_CACHE_REMOVE`, the remove has already been committed.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ Reentrant calls are possible, i.e. the cache can call back the user
+ (`contp`) in the same call.
+
+**Returns**
+ ~ An `INKAction` object if successful.
+
+ `INK_ERROR_PTR` if an argument is incorrect or if the API fails.
+
+