trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From iga...@apache.org
Subject svn commit: r1031963 [5/13] - in /trafficserver/site/branches/ats-cms: content/docs/trunk/sdk/ templates/
Date Sat, 06 Nov 2010 06:30:02 GMT
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**
+
+![A Transformation and its VIOs](images/vconnection.jpg)
+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.
+
+
 
 



Mime
View raw message