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 [2/13] - in /trafficserver/site/branches/ats-cms:
content/docs/trunk/sdk/ templates/
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_DeprecatedFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_DeprecatedFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_DeprecatedFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_DeprecatedFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,1170 @@
+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](App_SampleSourceCode) - Appendix A. Sample Source Code
+Other Deprecated Functions: Statistics Fxns -
+[Next](OtherDeprecatedFunctions)
+## Appendix B. Deprecated Functions
+
+This appendix lists the functions that are deprecated in current
+and all subsequent versions of Traffic Server.
+
+## Deprecated MIME Header Functions
+
+****
+[INKMimeFieldCopy](App_DeprecatedFunctions#INKMimeFieldCopy)
+[INKMimeFieldCopyValues](App_DeprecatedFunctions#INKMimeFieldCopyValues)
+[INKMimeFieldCreate](App_DeprecatedFunctions#INKMimeFieldCreate)
+[INKMimeFieldDestroy](App_DeprecatedFunctions#INKMimeFieldDestroy)
+[INKMimeFieldLengthGet](App_DeprecatedFunctions#INKMimeFieldLengthGet)
+[INKMimeFieldNameGet](App_DeprecatedFunctions#INKMimeFieldNameGet)
+[INKMimeFieldNameSet](App_DeprecatedFunctions#INKMimeFieldNameSet)
+[INKMimeFieldNext](App_DeprecatedFunctions#INKMimeFieldNext)
+[INKMimeFieldValueAppend](App_DeprecatedFunctions#INKMimeFieldValueAppend)
+[INKMimeFieldValueDelete](App_DeprecatedFunctions#INKMimeFieldValueDelete)
+[INKMimeFieldValueGet](App_DeprecatedFunctions#INKMimeFieldValueGet)
+[INKMimeFieldValueGetDate](App_DeprecatedFunctions#INKMimeFieldValueGetDate)
+[INKMimeFieldValueGetInt](App_DeprecatedFunctions#INKMimeFieldValueGetInt)
+[INKMimeFieldValueGetUint](App_DeprecatedFunctions#INKMimeFieldValueGetUint)
+[INKMimeFieldValueInsertDate](App_DeprecatedFunctions#INKMimeFieldValueInsertDate)
+[INKMimeFieldValueInsertInt](App_DeprecatedFunctions#INKMimeFieldValueInsertInt)
+[INKMimeFieldValueInsertUint](App_DeprecatedFunctions#INKMimeFieldValueInsertUint)
+[INKMimeFieldValuesClear](App_DeprecatedFunctions#INKMimeFieldValuesClear)
+[INKMimeFieldValuesCount](App_DeprecatedFunctions#INKMimeFieldValuesCount)
+[INKMimeFieldValueSet](App_DeprecatedFunctions#INKMimeFieldValueSet)
+[INKMimeFieldValueSetDate](App_DeprecatedFunctions#INKMimeFieldValueSetDate)
+[INKMimeFieldValueSetInt](App_DeprecatedFunctions#INKMimeFieldValueSetInt)
+[INKMimeFieldValueSetUint](App_DeprecatedFunctions#INKMimeFieldValueSetUint)
+[INKMimeHdrFieldValueGet](App_DeprecatedFunctions#INKMimeHdrFieldValueGet)
+[INKMimeHdrFieldValueGetDate](App_DeprecatedFunctions#INKMimeHdrFieldValueGetDate)
+[INKMimeHdrFieldValueGetInt](App_DeprecatedFunctions#INKMimeHdrFieldValueGetInt)
+[INKMimeHdrFieldValueGetUint](App_DeprecatedFunctions#INKMimeHdrFieldValueGetUint)
+[INKMimeHdrFieldValueInsert](App_DeprecatedFunctions#INKMimeHdrFieldValueInsert)
+[INKMimeHdrFieldValueInsertDate](App_DeprecatedFunctions#INKMimeHdrFieldValueInsertDate)
+[INKMimeHdrFieldValueInsertInt](App_DeprecatedFunctions#INKMimeHdrFieldValueInsertInt)
+[INKMimeHdrFieldValueInsertUint](App_DeprecatedFunctions#INKMimeHdrFieldValueInsertUint)
+[INKMimeHdrFieldValueSet](App_DeprecatedFunctions#INKMimeHdrFieldValueSet)
+[INKMimeHdrFieldValueSetDate](App_DeprecatedFunctions#INKMimeHdrFieldValueSetDate)
+[INKMimeHdrFieldValueSetInt](App_DeprecatedFunctions#INKMimeHdrFieldValueSetInt)
+[INKMimeHdrFieldValueSetUint](App_DeprecatedFunctions#INKMimeHdrFieldValueSetUint)
+[INKMimeHdrFieldDelete](App_DeprecatedFunctions#INKMimeHdrFieldDelete)
+[INKMimeHdrFieldInsert](App_DeprecatedFunctions#INKMimeHdrFieldInsert)
+[INKMimeHdrFieldRetrieve](App_DeprecatedFunctions#INKMimeHdrFieldRetrieve)
+### INKMimeFieldCopy
+
+Copies a MIME field from one location to another.
+
+**Prototype**
+ ~ `void INKMimeFieldCopy (INKMBuffer <em class="replaceable"><code>dest_bufp`,
+ INKMLoc *`dest_offset`*, INKMBuffer *`src_bufp`*, INKMLoc
+ *`src_offset`*)
+
+**Description**
+ ~ Copies the contents of the MIME field located at
+ `<em class="replaceable"><code>src_offset` within the marshal
+ buffer `<em class="replaceable"><code>src_bufp` to the MIME field
+ located at `<em class="replaceable"><code>dest_offset` within the
+ marshal buffer `<em class="replaceable"><code>dest_bufp`.
+ `INKMimeFieldCopy` works correctly even if
+ `<em class="replaceable"><code>src_bufp` and
+ `<em class="replaceable"><code>dest_bufp` point to different
+ marshal buffers.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ You must first create the destination MIME field before you copy
+ into it.
+
+
+### INKMimeFieldCopyValues
+
+Copies MIME field values from one location to another.
+
+**Prototype**
+ ~ `void INKMimeFieldCopyValues (INKMBuffer <em class="replaceable"><code>dest_bufp`,
+ INKMLoc *`dest_offset`*, INKMBuffer *`src_bufp`*, INKMLoc
+ *`src_offset`*)
+
+**Description**
+ ~ Copies the values contained within the MIME field located at
+ `<em class="replaceable"><code>src_offset` within the marshal
+ buffer `<em class="replaceable"><code>src_bufp` to the MIME field
+ located at `<em class="replaceable"><code>dest_offset` within the
+ marshal buffer `<em class="replaceable"><code>dest_bufp`.
+
+ ~ `INKMimeFieldCopyValues` works correctly even if
+ `<em class="replaceable"><code>src_bufp` and
+ `<em class="replaceable"><code>dest_bufp` point to different
+ marshal buffers. `INKMIMEFieldCopyValues` does not copy the field's
+ name.
+
+
+### INKMimeFieldCreate
+
+Creates a new MIME field within a specified marshal buffer.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldCreate (INKMBuffer <em class="replaceable"><code>bufp`)
+
+**Description**
+ ~ Creates a new MIME field with the marshal buffer
+ `<em class="replaceable"><code>bufp`. Returns the offset location
+ of the new MIME field.
+
+ Release the created `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldDestroy
+
+Deletes a specified MIME field from a marshal buffer.
+
+**Prototype**
+ ~ `void INKMimeFieldDestroy (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*)
+
+**Description**
+ ~ Destroys the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ Release the handle with a call to `INKHandleMLocRelease`.
+
+
+### INKMimeFieldLengthGet
+
+Calculates the length of a string representation of a specified
+MIME field.
+
+**Prototype**
+ ~ `int INKMimeFieldLengthGet (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*)
+
+**Description**
+ ~ Calculates the length of the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` if it was returned as a
+ string. This is the length of the MIME field in its unparsed
+ form.
+
+
+### INKMimeFieldNameGet
+
+Gets the name and length of a specified MIME field.
+
+**Prototype**
+ ~ `const char* INKMimeFieldNameGet (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int \**`length`*)
+
+**Description**
+ ~ Returns the name of the field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ `INKMimeFieldNameGet` places the length of the returned string
+ in the `<em class="replaceable"><code>length` argument. If
+ `<em class="replaceable"><code>length` is `NULL`, then no attempt
+ is made to dereference it.
+
+ Release the returned string with a call to
+ `INKHandleStringRelease`.
+
+
+### INKMimeFieldNameSet
+
+Sets a specified MIME field's name.
+
+**Prototype**
+ ~ `void INKMimeFieldNameSet (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, const char \**`name`*, int *`length`*)
+
+**Description**
+ ~ Sets the name of the field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the string
+ `<em class="replaceable"><code> name`.
+
+ ~ If `<em class="replaceable"><code>length` is -1, then
+ `INKMimeFieldNameSet` assumes that name is null-terminated.
+ Otherwise, the length of the string name is taken to be
+ `<em class="replaceable"><code>length`.
+
+ ~ `INKMimeFieldNameSet` copies the string to within
+ `<em class="replaceable"><code>bufp`, so it is okay to modify or
+ delete `<em class="replaceable"><code>name` after calling
+ `INKMimeFieldNameSet`.
+
+
+### INKMimeFieldNext
+
+Returns the next MIME field after a specified MIME field in a MIME
+header.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldNext (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ offset)
+
+**Description**
+ ~ Conceptually, there are a list of MIME fields in a MIME header
+ (see
+ [About HTTP Headers](HTTPHeaders#AboutHTTPHeaders "About HTTP Headers")).
+ `INKMimeFieldNext` returns the location of the next field in the
+ list after the field located at
+ `<em class="replaceable"><code> offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ Release the returned `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldValueAppend
+
+Appends a string to a specified value in a MIME field.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldNext (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*)
+
+**Description**
+ ~ Conceptually, there are a list of MIME fields in a MIME header
+ (see
+ [About HTTP Headers](HTTPHeaders#AboutHTTPHeaders "About HTTP Headers")).
+ `INKMimeFieldNext` returns the location of the next field in the
+ list after the field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ Release the returned `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldValueDelete
+
+Deletes a specified value from a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValueDelete (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int *`idx`*)
+
+**Description**
+ ~ Removes and deletes a value from the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value should be deleted. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeFieldValuesCount` `(`*`bufp, offset`*`) - 1`, then no
+ operation is performed.
+
+
+### INKMimeFieldValueGet
+
+Gets a specified field value from a MIME header.
+
+**Prototype**
+ ~ `const char* INKMimeFieldValueGet (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*, int *`idx`*, int \**`length`*)
+
+**Description**
+ ~ Retrieves a string value from within the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which field to retrieve. The fields are numbered from `0` to
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `NULL` is returned.
+
+ ~ The length of the returned string is placed in the
+ `<em class="replaceable"><code>length` argument. If
+ `<em class="replaceable"><code>length` is `NULL,` then no attempt
+ is made to dereference it.
+
+ Release the returned string with a call to
+ `INKHandleStringRelease`.
+
+
+### INKMimeFieldValueGetDate
+
+Gets date value from a MIME field.
+
+**Prototype**
+ ~ `time_t INKMimeFieldValueGetDate (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*, int *`idx`*)
+
+**Description**
+ ~ Retrieves a date value from within the MIME field located at
+ `<em class="replaceable"><code> offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which field to retrieve. The fields are numbered from `0` to
+ `INKMimeFieldValuesCount`
+ (`<em class="replaceable"><code>bufp, offset`) - 1. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `INKMimeFieldValueGetDate` returns `(``time_t``) 0`.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueGetDate` parses the string value to return an
+ integer date representation.
+
+
+### INKMimeFieldValueGetInt
+
+Gets an integer field value in a MIME field.
+
+**Prototype**
+ ~ `int INKMimeFieldValueGetInt (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*, int *`idx`*)
+
+**Description**
+ ~ Retrieves an integer value from within the MIME field located
+ at `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value within the field to retrieve. The fields are numbered
+ from `0` to
+ `INKMimeFieldValuesCount``(``<em class="replaceable"><code>bufp, offset``) - 1`.
+ If `<em class="replaceable"><code>idx` does not lie within that
+ range, then `INKMimeFieldValueGetInt` returns `(``int``) 0`.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueGetInt` parses the string value to return an
+ integer.
+
+
+### INKMimeFieldValueGetUint
+
+Gets unsigned integer field value in a MIME field.
+
+**Prototype**
+ ~ `unsigned int INKMimeFieldValueGetUint (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*, int *`idx`*)
+
+**Description**
+ ~ Retrieves an unsigned integer value from within the MIME field
+ located at `<em class="replaceable"><code>offset` within the
+ marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which field to retrieve. The fields are numbered from `0` to
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `INKMimeFieldValueGetUnit` returns `(``unsigned int``) 0`.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueGetUint` parses the string value to return an
+ unsigned integer.
+
+
+### INKMimeFieldValueInsertDate
+
+Inserts a date value into a MIME field.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldValueInsertDate (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, time\_t *`value`*, int *`idx`*)
+
+**Description**
+ ~ Inserts the date `<em class="replaceable"><code>value` into the
+ MIME field located at `<em class="replaceable"><code>offset` within
+ the marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value` is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` place the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueInsertDate` simply formats the date into a string
+ and then calls `INKMimeFieldValueInsert`.
+
+ Release the returned `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldValueInsertInt
+
+Inserts an integer value into a MIME field.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldValueInsertInt (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int *`value`*, int *`idx`*)
+
+**Description**
+ ~ Inserts the integer `<em class="replaceable"><code>value` into
+ the MIME field located at `<em class="replaceable"><code>offset`
+ within the marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value` is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` places the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueInsertInt` simply formats the integer into a
+ string and then calls `INKMimeFieldValueInsert`.
+
+ Release the returned `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldValueInsertUint
+
+Inserts an unsigned integer value into a MIME field.
+
+**Prototype**
+ ~ `INKMLoc INKMimeFieldValueInsertUint (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, unsigned int *`value`*, int *`idx`*)
+
+**Description**
+ ~ Inserts the unsigned integer
+ `<em class="replaceable"><code>value` into the MIME field located
+ at `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ placed with respect to the other values already in the MIME field.
+ If `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value` is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` place the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueInsertUint` simply formats the unsigned integer
+ into a string and then calls `INKMimeFieldValueInsert`.
+
+ Release the returned `INKMLoc` with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeFieldValuesClear
+
+Clears all values in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValuesClear (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*)
+
+**Description**
+ ~ Removes and destroys all of the values within the MIME field
+ located at `<em class="replaceable"><code>offset` within the
+ marshal buffer `<em class="replaceable"><code>bufp`.
+
+
+### INKMimeFieldValuesCount
+
+Counts the values in a MIME field.
+
+**Prototype**
+ ~ `int INKMimeFieldValuesCount (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*)
+
+**Description**
+ ~ Returns a count of the number of values in the MIME field
+ located at `<em class="replaceable"><code> offset` within the
+ marshal buffer `<em class="replaceable"><code>bufp`.
+
+
+### INKMimeFieldValueSet
+
+Sets a value in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValueSet (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`offset`*, int *`idx`*, const char \**`value`*, int
+ *`length`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the string
+ `<em class="replaceable"><code>value`. If
+ `<em class="replaceable"><code>length` is `-1`, then it is assumed
+ that `<em class="replaceable"><code>value` is null-terminated.
+ Otherwise, the length of the string
+ `<em class="replaceable"><code>value` is taken to be
+ `<em class="replaceable"><code>length`.
+
+ ~ The string is copied to within
+ `<em class="replaceable"><code>bufp`, so it's okay to modify or
+ delete `<em class="replaceable"><code>value` after calling
+ `INKMimeFieldValueSet`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`, then no
+ operation is performed.
+
+
+### INKMimeFieldValueSetDate
+
+Sets a date value in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValueSetDate (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int *`idx`*, time\_t *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code> offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the data `value`.
+
+ ~ The `<em class="replaceable"><code> idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueSetDate` simply formats the date into a string
+ and then calls `INKMimeFieldValueSet`.
+
+
+### INKMimeFieldValueSetInt
+
+Sets an integer value in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValueSetInt (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int *`idx`*, int *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the integer
+ `<em class="replaceable"><code>value`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueSetInt` simply formats the integer into a string
+ and then calls `INKMimeFieldValueSet`.
+
+
+### INKMimeFieldValueSetUint
+
+Sets an unsigned integer value in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeFieldValueSetUint (INKMBuffer <em class="replaceable"><code>bufp`,INKMLoc
+ *`offset`*, int *`idx`*, unsigned int *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>offset` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the unsigned integer
+ `<em class="replaceable"><code>value`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, offset``) - 1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeFieldValueSetUint` simply formats the unsigned integer into
+ a string and then calls `INKMimeFieldValueSet`.
+
+
+### INKMimeHdrFieldValueGet
+
+Gets a specified field value from a MIME header.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueStringGet`.
+
+**Prototype**
+ ~ `const char* INKMimeHdrFieldValueGet (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr_loc`*, INKMLoc *`field`*, int *`idx`*, int
+ \**`value_len_ptr`*)
+
+**Description**
+ ~ Retrieves a string value from within the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which field to retrieve. The fields are numbered from `0` to
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range
+ then `NULL` will be returned.
+
+ ~ The length of the returned string is placed in the
+ `<em class="replaceable"><code>value_len_ptr` argument. If
+ `<em class="replaceable"><code>value_len_ptr` is `NULL`, then no
+ attempt is made to dereference it.
+
+**Returns**
+ ~ A pointer to the specified field value in the MIME header.
+ Release with a call to `INKHandleStringRelease`.
+
+
+### INKMimeHdrFieldValueGetDate
+
+Gets date value from a MIME field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueDateGet`.
+
+**Prototype**
+ ~ `time_t INKMimeHdrFieldValueGetDate (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*)
+
+**Description**
+ ~ Retrieves a date value from within the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which field to retrieve. The fields are numbered from `0` to
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) -1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `INKMimeHdrFieldValueGetDate` returns `(``time_t``) 0`.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueGetDate` parses the string value to return an
+ integer date representation.
+
+**Returns**
+ ~ The date value from the specified MIME header.
+
+
+### INKMimeHdrFieldValueGetInt
+
+Gets an integer field value in a MIME field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueIntGet`.
+
+**Prototype**
+ ~ `int INKMimeHdrFieldValueGetInt (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*, int
+ \**`value_len-ptr`*)
+
+**Description**
+ ~ Retrieves an integer value from within the MIME field located
+ at `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value within the field to retrieve. The fields are numbered
+ from `0` to `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `INKMimeHdrFieldValueGetInt` returns `(``int``) 0`.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueGetInt` parses the string value to return an
+ integer.
+
+**Returns**
+ ~ The integer value from the specified MIME field.
+
+
+### INKMimeHdrFieldValueGetUint
+
+Gets unsigned integer field value in a MIME field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueUintGet`.
+
+**Prototype**
+ ~ `unsigned int INKMimeHdrFieldValueGetUint (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*)
+
+**Description**
+ ~ Retrieves an unsigned integer value from within the MIME field
+ located at `<em class="replaceable"><code>field` within the marshal
+ buffer `<em class="replaceable"><code>bufp`. The
+ `<em class="replaceable"><code>idx` parameter specifies which field
+ to retrieve. The fields are numbered from `0` to
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`. If
+ `<em class="replaceable"><code>idx` does not lie within that range,
+ then `INKMimeHdrFieldValueGetUnit` returns `(``unsigned int``) 0`.
+ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueGetUint` parses the string value to return an
+ unsigned integer.
+
+ It is not possible to determine if `INKMimeHdrFieldValueGetUint` is
+ returning an `unsigned int` value in error. If you need to check
+ for errors in MIME header field values, then you can fetch the
+ header as a string and examine it.
+
+**Returns**
+ ~ The unsigned integer value from the specified MIME field.
+
+**Example**
+ ~ Below is some sample code that fetches MIME headers from
+ marshal buffers into strings using `INKMimeHdrFieldValueGet`
+ instead. The context of this example is that the plugin is
+ processing an HTTP transaction and has access to a transaction.
+ static void
+ handle_string (INKHttpTxn txnp, INKCont contp) {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc field;
+ int len;
+ char* output_string;
+ const char* value;
+ /* Fetch the transaction's client request header into a marshal buffer. */
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+ field=INKMimeHdrFieldRetrieve(bufp, hdr_loc,
+ INK_MIME_FIELD_CONTENT_LENGTH);
+
+ if (!field) {
+ INKError ("Content-Length field not found.\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+ /* Obtain the value of the content length (normally an
+ *unsigned int) as a string. */
+ value=INKMimeHdrFieldValueGet (bufp, hdr_loc, field, 0, &len);
+
+ if ((!value) || (len<=0))}
+ INKHandleMLocRelease (bufp, hdr_loc, field);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+ /* Allocate the string with an extra byte for the string terminator. */
+ output_string = (char*) INKmalloc(len + 1);
+
+ /* Copy the value. */
+ strncpy (output_string, value, len);
+
+ /* Terminate the string */
+ output_string[len] = '\0';
+ /* Now that you have the MIME fields as a string, you can do
+ whatever you want with it. For example: you can print it
+ or make sure it's an unsigned integer (by using the
+ atol C function or by scanning each ASCII character). */
+ INKDebug("my-plugin", "%s", output_string);
+
+ /* Release handles and allocated memory. */
+ INKHandleStringRelease (bufp, field, value);
+
+
+### INKMimeHdrFieldValueInsert
+
+Inserts a value into a specified location within a MIME field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueStringInsert`.
+
+**Prototype**
+ ~ `INKMLoc INKMimeHdrFieldValueInsert (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, const char \**`value`*, int
+ *`length`*, int *`idx`*)
+
+**Description**
+ ~ Inserts the string `<em class="replaceable"><code>value` into
+ the MIME field located at `<em class="replaceable"><code>field`
+ within the marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ If `<em class="replaceable"><code>length` is `-1`, then
+ `INKMimeHdrFieldValueInsert` assumes that
+ `<em class="replaceable"><code>value` is null-terminated.
+ Otherwise, the length of the string
+ `<em class="replaceable"><code>value` is taken to be
+ `<em class="replaceable"><code> length`.
+
+ ~ `INKMimeHdrFieldValueInsert` copies the string to within
+ `<em class="replaceable"><code>bufp`, so it is okay to modify or
+ delete `<em class="replaceable"><code>value` after calling
+ `INKMimeHdrFieldValueSet`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then
+ `INKMimeHdrFieldValueInsert` prepends the
+ `<em class="replaceable"><code>value` to the list of values in the
+ field. Increasing values of `<em class="replaceable"><code>idx`
+ place the `<em class="replaceable"><code>value` further down the
+ list of values. If `<em class="replaceable"><code>idx` is `-1`,
+ then `INKMimeHdrFieldValueInsert` appends the
+ `<em class="replaceable"><code>value` to the list of values. Normal
+ usage is to specify `-1`for `<em class="replaceable"><code>idx` so
+ that the `<em class="replaceable"><code>value` is appended to the
+ list of values.
+
+
+### INKMimeHdrFieldValueInsertDate
+
+Inserts a date value into a MIME field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueDateInsert`.
+
+**Prototype**
+ ~ `INKMLoc INKMimeHdrFieldValueInsertDate (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, time\_t *`value`*, int
+ *`idx`*)
+
+**Description**
+ ~ Inserts the data `<em class="replaceable"><code>value` into the
+ MIME field located at `<em class="replaceable"><code>field` within
+ the marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value` is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` places the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueInsertDate` simply formats the date into a
+ string and then calls `INKMimeHdrFieldValueInsert`.
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ Do not use the return value (`INKMLoc`) of this function. Future
+ versions will be changed to `void`.
+
+
+### INKMimeHdrFieldValueInsertInt
+
+Inserts an integer value into a MIME field.
+
+**Note:** This API is deprecated and has been succeeded by
+`INKMimeHdrFieldValueIntInsert`.
+
+**Prototype**
+ ~ `INKMLoc INKMimeHdrFieldValueInsertInt (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`value`*, int *`idx`*)
+
+**Description**
+ ~ Inserts the integer `<em class="replaceable"><code>value` into
+ the MIME field located at `<em class="replaceable"><code>field`
+ within the marshal buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value` is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` places the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueInsertInt` simply formats the integer into a
+ string and then calls `INKMimeHdrFieldValueInsert`.
+
+
+### INKMimeHdrFieldValueInsertUint
+
+Inserts an unsigned integer value into a MIME field.
+
+**Note:** This API is deprecated and has been succeeded by
+`INKMimeHdrFieldValueUintInsert`.
+
+**Prototype**
+ ~ `INKMLoc INKMimeHdrFieldValueInsertUint (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, unsigned int *`value`*, int
+ *`idx`*)
+
+**Description**
+ ~ Inserts the unsigned integer
+ `<em class="replaceable"><code>value` into the MIME field located
+ at `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ where the inserted `<em class="replaceable"><code>value` should be
+ put with respect to the other values already in the MIME field. If
+ `<em class="replaceable"><code>idx` is `0`, then the
+ `<em class="replaceable"><code>value`is prepended to the list of
+ values in the field. Increasing values of
+ `<em class="replaceable"><code>idx` place the
+ `<em class="replaceable"><code>value` further down the list of
+ values. If `<em class="replaceable"><code>idx` is `-1`, then the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values. Normal usage is to specify `-1` for
+ `<em class="replaceable"><code>idx` so that the
+ `<em class="replaceable"><code>value` is appended to the list of
+ values.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueInsertUint` simply formats the unsigned
+ integer into a string and then calls
+ `INKMimeHdrFieldValueInsert`.
+
+
+### INKMimeHdrFieldValueSet
+
+Sets a value in a MIME field.
+
+**Note:** This API is deprecated and has been succeeded by
+`INKMimeHdrFieldValueStringSet`.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldValueSet (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*, const char
+ \**`value`*, int *`length`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the string
+ `<em class="replaceable"><code>value`.
+
+ ~ If `<em class="replaceable"><code>length` is `-1`, then it is
+ assumed that `<em class="replaceable"><code>value` is
+ null-terminated. Otherwise, the length of the string
+ `<em class="replaceable"><code>value` is taken to be
+ `<em class="replaceable"><code>length`.
+
+ ~ The string is copied to within
+ `<em class="replaceable"><code>bufp`, so it is okay to modify or
+ delete `<em class="replaceable"><code>value` after calling
+ `INKMimeHdrFieldValueSet`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`, then no
+ operation is performed.
+
+
+### INKMimeHdrFieldValueSetDate
+
+Sets the date value in a MIME field.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldValueSetDate (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*, time\_t
+ *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the date
+ `<em class="replaceable"><code>value`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If the
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) -1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueSetDate` simply formats the date into a string
+ and then calls `INKMimeHdrFieldValueSet`.
+
+
+### INKMimeHdrFieldValueSetInt
+
+Sets an integer value within a MIME field.
+
+**Note:** This API is deprecated and has been succeeded by
+`INKMimeHdrFieldValueIntSet`.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldValueSetInt (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*, int *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the integer
+ `<em class="replaceable"><code>value`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between`0` and
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueSetInt` simply formats the integer into a
+ string and then calls `INKMimeHdrFieldValueSet`.
+
+
+### INKMimeHdrFieldValueSetUint
+
+Sets a value in a MIME field to a specified unsigned integer.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldValueUintSet`.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldValueSetUint (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr`*, INKMLoc *`field`*, int *`idx`*, unsigned int
+ *`value`*)
+
+**Description**
+ ~ Sets a value in the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp` to the unsigned integer
+ `<em class="replaceable"><code>value`.
+
+ ~ The `<em class="replaceable"><code>idx` parameter specifies
+ which value in the field to change. If
+ `<em class="replaceable"><code>idx` is not between `0` and
+ `INKMimeHdrFieldValuesCount`
+ `(``<em class="replaceable"><code>bufp, hdr, field``) - 1`, then no
+ operation is performed.
+
+ ~ All values are stored as strings within the MIME field.
+ `INKMimeHdrFieldValueSetUint` simply formats the unsigned integer
+ into a string and then calls `INKMimeHdrFieldValueSet`.
+
+
+### INKMimeHdrFieldDelete
+
+Destroys a MIME header field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldDestroy`.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldDelete (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr_loc`*, INKMLoc *`field`*)
+
+**Description**
+ ~ Deletes the MIME field located at
+ `<em class="replaceable"><code>field` within the MIME header
+ located at `<em class="replaceable"><code>hdr_loc` in the marshal
+ buffer `<em class="replaceable"><code>bufp`.
+
+ Make sure you release the `INKMLoc` handle field with a call to
+ `INKHandleMLocRelease`.
+
+
+### INKMimeHdrFieldInsert
+
+Appends a field in a MIME header.
+
+**Note:**This API is deprecated and has been replaced by
+`INKMimeHdrFieldAppend`.
+
+**Prototype**
+ ~ `void INKMimeHdrFieldInsert (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr_loc`*, INKMLoc *`field`*, int *`idx`*)
+
+**Description**
+ ~ Appends the MIME field located at
+ `<em class="replaceable"><code>field` within the marshal buffer
+ `<em class="replaceable"><code>bufp` into the MIME header located
+ at `<em class="replaceable"><code>hdr_loc` within the marshal
+ buffer `<em class="replaceable"><code>bufp`.
+
+ ~ The `<i>idx </i>` parameter specifies where the inserted field
+ should be put with respect to the other fields already in the MIME
+ header.
+
+
+### INKMimeHdrFieldRetrieve
+
+Retrieves a MIME header field.
+
+**Note:** This API is deprecated and has been replaced by
+`INKMimeHdrFieldFind`.
+
+**Prototype**
+ ~ `INKMLoc INKMimeHdrFieldRetrieve (INKMBuffer <em class="replaceable"><code>bufp`,
+ INKMLoc *`hdr_loc`*, const char\* \**`retrieved_str`*)
+
+**Description**
+ ~ Retrieves a MIME field from within the MIME header located at
+ `<em class="replaceable"><code>hdr_loc` within the marshal buffer
+ `<em class="replaceable"><code>bufp`.
+
+ ~ The `<em class="replaceable"><code>retrieved_str` parameter
+ specifies which field to retrieve. For each MIME field in the MIME
+ header, a pointer comparison is done between the field name and
+ `<em class="replaceable"><code>retrieved_str`. This is a much
+ quicker retrieval function than `INKMimeHdrFieldFind`, since it
+ obviates the need for a string comparision. However,
+ `<em class="replaceable"><code> retrieved_str` must be one of the
+ predefined field names listed above (of the form
+ `INK_MIME_FIELD_XXX`) in order for the call to succeed. If the
+ requested field cannot be found, then `0` is returned.
+
+ Release with a call to `INKHandleMLocRelease`.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_SampleSourceCode.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_SampleSourceCode.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_SampleSourceCode.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_SampleSourceCode.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,317 @@
+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](INKTextLogObjectWrite) - INKTextLogObjectWrire
+Appendix B. Deprecated Functions -
+[Next](App_DeprecatedFunctions)
+## Appendix A. Sample Source Code
+
+This appendix provides several source code examples. In the online
+formats of this book, function calls are linked to their references
+in the previous chapters. The following sample plugins are
+provided:
+
+- [blacklist-1.c](App_SampleSourceCode#Sample_blacklist-1.c "blacklist-1.c")
+
+
+## blacklist-1.c
+
+The sample blacklisting plugin included in the Traffic Server SDK
+is `blacklist-1.c`. This plugin checks every incoming HTTP client
+request against a list of blacklisted web sites. If the client
+requests a blacklisted site, then the plugin returns an
+`Access forbidden` message to the client.
+
+This plugin illustrates:
+
+- An HTTP transaction extension
+
+- How to examine HTTP request headers
+
+- How to use the logging interface
+
+- How to use the plugin configuration management interface
+
+
+ /* blacklist-1.c: An example program that denies client access
+ * to blacklisted sites. This plugin illustrates
+ * how to use configuration information from the
+ * blacklist.txt configuration file.
+ *
+ * Usage:
+ * (Solaris) : blacklist-1.so
+ *
+ *
+ */
+
+ #include <stdio.h>
+ #include <string.h>
+ #include <ts/ts.h>
+
+ #define MAX_NSITES 500
+
+ static char* sites[MAX_NSITES];
+ static int nsites;
+ static INKMutex sites_mutex;
+ static INKTextLogObject log;
+
+ static void
+ handle_dns (INKHttpTxn txnp, INKCont contp)
+ {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ INKError ("couldn't retrieve request url\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = INKUrlHostGet (bufp, url_loc, &host_length);
+ if (!host) {
+ INKError ("couldn't retrieve request hostname\n");
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ INKMutexLock(sites_mutex);
+
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ if (log) {
+ INKTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
+ } else {
+ printf ("blacklisting site: %s\n", sites[i]);
+ }
+ INKHttpTxnHookAdd (txnp,
+ INK_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ INKHandleStringRelease (bufp, url_loc, host);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_ERROR);
+ INKMutexUnlock(sites_mutex);
+ return;
+ }
+ }
+
+ INKMutexUnlock(sites_mutex);
+ INKHandleStringRelease (bufp, url_loc, host);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+
+ done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ handle_response (INKHttpTxn txnp)
+ {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ char *url_str;
+ char *buf;
+ int url_length;
+
+ if (!INKHttpTxnClientRespGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client response header\n");
+ goto done;
+ }
+
+ INKHttpHdrStatusSet (bufp, hdr_loc, INK_HTTP_STATUS_FORBIDDEN);
+ INKHttpHdrReasonSet (bufp, hdr_loc,
+ INKHttpHdrReasonLookup (INK_HTTP_STATUS_FORBIDDEN),
+ strlen (INKHttpHdrReasonLookup (INK_HTTP_STATUS_FORBIDDEN)) );
+
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ INKError ("couldn't retrieve request url\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ buf = (char *)INKmalloc (4096);
+
+ url_str = INKUrlStringGet (bufp, url_loc, &url_length);
+ sprintf (buf, "You are forbidden from accessing \"%s\"\n", url_str);
+ INKfree (url_str);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+
+ INKHttpTxnErrorBodySet (txnp, buf, strlen (buf), NULL);
+
+ done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ read_blacklist (void)
+ {
+ char blacklist_file[1024];
+ INKFile file;
+
+ sprintf (blacklist_file, "%s/blacklist.txt", INKPluginDirGet());
+ file = INKfopen(blacklist_file, "r");
+
+ INKMutexLock (sites_mutex);
+ nsites = 0;
+
+ if (file != NULL) {
+ char buffer[1024];
+
+ while (INKfgets (file, buffer, sizeof(buffer)-1) != NULL &&
+ nsites < MAX_NSITES) {
+ char* eol;
+ if ((eol = strstr(buffer, "\r\n")) != NULL) {
+ /* To handle newlines on Windows */
+ *eol = '\0';
+ } else if ((eol = strchr(buffer, '\n')) != NULL) {
+ *eol = '\0';
+ } else {
+ /* Not a valid line, skip it */
+ continue;
+ }
+ if (sites[nsites] != NULL) {
+ INKfree (sites[nsites]);
+ }
+ sites[nsites] = INKstrdup (buffer);
+ nsites++;
+ }
+
+ INKfclose (file);
+ } else {
+ INKError ("unable to open %s\n", blacklist_file);
+ INKError ("all sites will be allowed\n", blacklist_file);
+ }
+
+ INKMutexUnlock (sites_mutex);
+
+ }
+
+ static int
+ blacklist_plugin (INKCont contp, INKEvent event, void *edata)
+ {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+
+ switch (event) {
+ case INK_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case INK_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case INK_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = INKTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* Need at least TS 2.0 */
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+ }
+
+ void
+ INKPluginInit (int argc, const char *argv[])
+ {
+ int i;
+ INKCont contp;
+ INKPluginRegistrationInfo info;
+ int error;
+
+ info.plugin_name = "blacklist-1";
+ info.vendor_name = "DsCompany";
+ info.support_email = "ts-api-support@DsCompany.com";
+
+ if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
+ INKError ("Plugin registration failed.\n");
+ }
+
+ if (!check_ts_version()) {
+ INKError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ /* create an INKTextLogObject to log blacklisted requests to */
+ log = INKTextLogObjectCreate("blacklist", INK_LOG_MODE_ADD_TIMESTAMP,
+ NULL, &error);
+ if (!log) {
+ printf("Blacklist plugin: error %d while creating log\n", error);
+ }
+
+ sites_mutex = INKMutexCreate ();
+
+ nsites = 0;
+ for (i = 0; i < MAX_NSITES; i++) {
+ sites[i] = NULL;
+ }
+
+ read_blacklist ();
+
+ contp = INKContCreate (blacklist_plugin, NULL);
+
+ INKHttpHookAdd (INK_HTTP_OS_DNS_HOOK, contp);
+
+ INKMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
+ }
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_Troubleshooting.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_Troubleshooting.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_Troubleshooting.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/App_Troubleshooting.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,71 @@
+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](Dep_MutexFunctions) - Mutex Function
+Unable to Load Plugins - [Next](Trouble_LoadPlugins)
+## Appendix C. Troubleshooting Tips
+
+This appendix lists the following troubleshooting tips.
+
+- [Unable to Compile Plugins](App_Troubleshooting#Trouble_CompilePlugins "Unable to Compile Plugins")
+
+- [Unable to Load Plugins](Trouble_LoadPlugins "Unable to Load Plugins")
+
+- [Using Debug Tags](Trouble_DebugTags "Using Debug Tags")
+
+- [Using a Debugger](Trouble_UsingDebugger "Using a Debugger")
+
+- [Debugging Memory Leaks](Trouble_DebugMemLeaks "Debugging Memory Leaks")
+
+
+## Unable to Compile Plugins
+
+The process for compiling a shared library varies with the platform
+used, so the Traffic Server API includes `makefile` templates you
+can use to create shared libraries on all supported Traffic Server
+platforms.
+
+### UNIX Example
+
+Assuming the sample program is stored in the file `hello-world.c`,
+you could use the following commands to building a shared library
+on Solaris using the GNU C compiler.
+
+ gcc -g -Wall -fPIC -o hello-world.o -c hello-world.c
+ gcc -g -Wall -shared -o hello-world.so hello-world.o
+
+The first command compiles `hello-world.c`as Position Independent
+Code (PIC); the second command links the single`hello-world.o`
+object file into the `hello-world.so` shared library.
+
+![[Caution]](images/docbook/caution.png)
+Caution
+Make sure that your plugin is not statically linked with system
+libraries.
+
+### HPUX Example
+
+Assuming the sample program is stored in the file `hello_world.c`,
+you could use the following commands to build a shared library on
+HPUX:
+
+ cc +z -o hello_world.o -c hello_world.c
+ ld -b -o hello_world.so hello_world.o
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/AppendTransformPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/AppendTransformPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/AppendTransformPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/AppendTransformPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,149 @@
+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](SampleNullTransformPlugin) - The Sample Null Transform
+Plugin
+The Sample Buffered Null Transform Plugin -
+[Next](SampleBufferedNullTransformPlugin)
+## The Append-Transform Plugin
+
+The append-transform plugin appends text to the body of an HTTP
+response. It obtains this text from a file; the name of the file
+containing the append text is a parameter you specify in
+`plugin.config`, as follows:
+
+ append-transform.so path/to/file
+
+The append-transform plugin is based on `null-transform.c`. The
+only difference is that after the plugin feeds the document through
+the transformation, it adds text to the response.
+
+Below is a list of the functions in `append-transform.c`, in the
+order they appear in the source code. Below each entry is a
+description of what the function does:
+
+- `<b>my_data_alloc</b>`
+
+ Allocates and initializes a `MyData` structure. The plugin defines
+ a struct, `MyData`, as follows:
+
+ typedef struct {
+ INKVIO output_vio;
+ INKIOBuffer output_buffer;
+ INKIOBufferReader output_reader;
+ int append_needed;
+ } MyData;
+
+ The `MyData` structure is used to represent data that the
+ transformation (vconnection) needs. The transformation's data
+ pointer is set to a `MyData` pointer using `INKContDataSet` in the
+ `handle_transform` routine.
+
+- `<b>my_data_destroy</b>`
+
+ Destroys objects of type `MyData`. To deallocate the transform's
+ data, the `append_transform` routine (see below) calls
+ `my_data_destroy` when the transformation is complete.
+
+- `<b>handle_transform</b>`
+
+ This function does the actual data transformation. The
+ transformation is created in `transform_add` (see below).
+ `handle_transform` is called by `append_transform`.
+
+- `<b>append_transform</b>`
+
+ This is the handler function for the transformation vconnection
+ created in `transform_add`. It is the implementation of the
+ vconnection.
+
+ - If the transformation vconnection has been closed, then
+ `append_transform` calls `my_data_destroy` to destroy the
+ vonnection.
+
+ - If `append_transform` receives an error event, then it calls
+ back the continuation to let it know it has completed the write
+ operation.
+
+ - If it receives a `WRITE_COMPLETE` event, then it shuts down the
+ write portion of its vconnection.
+
+ - If it receives a `WRITE_READY` or any other event (such as
+ `INK_HTTP_RESPONSE_TRANSFORM_HOOK`), then it calls
+ `handle_transform` to attempt to transform more data.
+
+
+- `<b>transformable</b>`
+
+ The plugin transforms only documents that have a content type of
+ `text/html`. This function examines the `Content-Type` MIME header
+ field in the response header. If the value of the MIME field is
+ `text/html`, then the function returns 1; otherwise, it returns
+ zero.
+
+- `<b>transform_add</b>`
+
+ Creates the transformation for the current transaction and sets up
+ a transformation hook. The handler function for the transformation
+ is `append_transform`.
+
+- `<b>transform_plugin</b>`
+
+ This is the handler function for the main continuation for the
+ plugin. Traffic Server calls this function whenever it reads an
+ HTTP response header. `transform_plugin` does the following:
+
+ - Gets a handle to the HTTP transaction being processed
+
+ - Calls `transformable` to determine whether the response
+ document content is of type `text/html`
+
+ - If the content is transformable, then it calls `transform_add`
+ to create the transformation.
+
+ - Calls `INKHttpTxnReenable` to continue the transaction
+
+
+- `<b>load</b>`
+
+ Opens the file containing the text to be appended and loads the
+ contents of the file into an `INKIOBuffer` called `append_buffer`.
+
+- `<b>INKPluginInit</b>`
+
+ Does the following:
+
+ - Checks to make sure that the required configuration information
+ (the append text filename) is entered in `plugin.config`
+ correctly.
+
+ - If there is a filename, then `INKPluginInit` calls load to load
+ the text.
+
+ - Creates a continuation for the plugin. The handler for this
+ continuation is `transform_plugin`.
+
+ - Adds the plugin's continuation to
+ `INK_HTTP_READ_RESPONSE_HDR_HOOK`. In other words, it sets up a
+ callback of the plugin's continuation when Traffic Server reads
+ HTTP response headers.
+
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,42 @@
+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](WorkWHTTPHeaderFunc) - Working with HTTP Header
+Functions
+Implementing the Handler and Getting a Handle to the Transaction -
+[Next](ImplementHandler_GetTransHandle)
+## The Basic Authorization Plugin
+
+The sample basic authorization plugin, `basic-auth.c`, checks for
+basic HTTP proxy authorization. In HTTP basic proxy authorization,
+client user names and passwords are contained in the
+`Proxy-Authorization` header. The password is encoded using base64
+encoding. The plugin checks all incoming requests for the
+authorization header, user name, and password. If the plugin does
+not find all of the these, then it reenables with an error
+(effectively stopping the transaction) and adds a transaction hook
+to the send response header event.
+
+### Creating the Plugin's Parent Continuation and Global Hook
+
+The parent continuation and global hook are created as follows:
+
+ INKHttpHookAdd (INK_HTTP_OS_DNS_HOOK, INKContCreate (auth_plugin, NULL));
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BlacklistPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BlacklistPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BlacklistPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/BlacklistPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,110 @@
+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](HeaderBasedPluginEx) - Chapter 4. Header-Based Plugin
+Examples
+Setting a Global Hook - [Next](SettingGlobalHook)
+## The Blacklist Plugin
+
+The sample blacklisting plugin included in the Traffic Server SDK
+is `blacklist_1.c`. This plugin checks every incoming HTTP client
+request against a list of blacklisted web sites. If the client
+requests a blacklisted site, then the plugin returns an
+`Access forbidden` message to the client.
+
+The flow of HTTP processing with the blacklist plugin is
+illustrated in the figure titled
+["Blacklist Plugin"](CreatingTSPlugins#Fig_BlacklistPlugin "Figure 2.5. Blacklist Plugin").
+This example also contains a simple configuration management
+interface. It can read a list of blacklisted sites from a file
+(`blacklist.txt`) that can be updated by a Traffic Server
+administrator. When the configuration file is updated, Traffic
+Server sends an event to the plugin that wakes it up to do some
+work.
+
+### Creating the Parent Continuation
+
+You create the static parent continuation in the mandatory
+`INKPluginInit` function. This parent continuation effectively
+**is** the plugin: the plugin does work when this continuation
+receives an event from Traffic Server. Traffic Server passes the
+event as an argument to the continuation's handler function. When
+you create continuations, you must create and specify their handler
+functions.
+
+You can specify an optional mutex lock when you create
+continuations. The mutex lock protects data shared by asynchronous
+processes. Because Traffic Server has a multi-threaded design, race
+conditions can occur if several threads try to access the same
+continuation's data.
+
+Here is how the static parent continuation is created in
+`blacklist-1.c`
+
+ void
+ INKPluginInit (int argc, const char *argv[])
+ { ...
+ INKCont contp;
+
+ contp = INKContCreate (blacklist_plugin, NULL);
+ ...
+ }
+
+:
+
+The handler function for the plugin is `blacklist_plugin`, and the
+mutex is null. The continuation handler function's job is to handle
+the events that are sent to it; accordingly, the `blacklist_plugin`
+routine consists of a switch statement that covers each of the
+events that might be sent to it:
+
+ static int
+ blacklist_plugin (INKCont contp, INKEvent event, void *edata)
+ {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ switch (event) {
+ case INK_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case INK_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case INK_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+When you write handler functions, you have to anticipate any events
+that might be sent to the handler by hooks or by other functions.
+In the Blacklist plugin, `INK_EVENT_OS_DNS` is sent because of the
+global hook established in `INKPluginInit`,
+`INK_EVENT_HTTP_SEND_RESPONSE_HDR` is sent because the plugin
+contains a transaction hook (see
+[Setting Up a Transaction Hook](SettingUpTransacHook "Setting Up a Transaction Hook")),
+and `INK_EVENT_MGMT_UPDATE` is sent by Traffic Manager whenever
+there is a configuration change (see
+[Setting Up UI Update Callbacks](SettingUpUIUpdateCallbacks "Setting Up UI Update Callbacks")).
+It is good practice to have a default case in your switch
+statements.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI.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](IOBuffers_IO) - IO Buffers
+How to Do a Cache Write - [Next](DoACacheWrite)
+## Guide to the Cache API
+
+The cache API enables plugins to read, write, and remove objects in
+the Traffic Server cache. All cache APIs are keyed by an object
+called an `INKCacheKey`; cache keys are created via
+`INKCacheKeyCreate`; keys are destroyed via `INKCacheKeyDestroy`.
+Use `INKCacheKeyDigestSet` to set the hash of the cache key.
+
+Note that the cache APIs differentiate between HTTP data and plugin
+data. The cache APIs do not allow you to write HTTP docs in the
+cache; you can only write plugin-specific data (a specific type of
+data that differs from the HTTP type).
+
+**Example:**
+
+ const unsigned char *key_name = "example key name";
+
+ INKCacheKey key;
+ INKCacheKeyCreate (&key);
+ INKCacheKeyDigestSet (key, (unsigned char *) key_name , strlen(key_name));
+ INKCacheKeyDestroy (key);
+
+### How to Do a Cache Read
+
+`INKCacheRead` does not really read - it is used for lookups (see
+the sample Protocol plugin). Possible callback events include:
+
+- `INK_EVENT_CACHE_OPEN_READ` - indicates the lookup was
+ successful. The data passed back along with this event is a cache
+ vconnection that can be used to initiate a read on this keyed
+ data.
+
+- `INK_EVENT_CACHE_OPEN_READ_FAILED` - indicates the lookup was
+ unsuccessful. Reasons for this event could be that another
+ continuation is writing to that cache location, or the cache key
+ doesn't refer to a cached resource. Data payload for this event
+ indicates the possible reason the read failed (`INKCacheError`).
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI_Example.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI_Example.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI_Example.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheAPI_Example.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,73 @@
+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](Errors_Cache) - Errors
+Chapter 16. Plugin Management - [Next](PluginManagement)
+### Example
+
+In the example below, suppose there is a cache hit and the cache
+returns a vconnection that enables you to read the document from
+cache. To do this, you need to prepare a buffer (`cache_bufp`) to
+hold the document; meanwhile, use `INKVConnCachedObjectSizeGet` to
+find out the actual size of the document (`content_length`). Then,
+issue `INKVConnRead` to read the document with the total data
+length required as `content_length`. Assume the following data:
+
+ INKIOBuffer cache_bufp = INKIOBufferCreate ();
+ INKIOBufferReader cache_readerp = INKIOBufferReaderAlloc (out_bufp);
+ INKVConn cache_vconnp = NULL;
+ INKVIO cache_vio = NULL;
+ int content_length = 0;
+
+In the `INK_CACHE_OPEN_READ` handler:
+
+ cache_vconnp = (INKVConn) data;
+ INKVConnCachedObjectSizeGet (cache_vconnp, &content_length);
+ cache_vio = INKVConnRead (cache_vconn, contp, cache_bufp, content_length);
+
+In the `INK_EVENT_VCONN_READ_READY` handler:
+
+ (usual VCONN_READ_READY handler logic)
+ int nbytes = INKVIONBytesGet (cache_vio);
+ int ntodo = INKVIONTodoGet (cache_vio);
+ int ndone = INKVIONDoneGet (cache_vio);
+ (consume data in cache_bufp)
+ INKVIOReenable (cache_vio);
+
+Do not try to get continuations or VIOs from `INKVConn` objects for
+cache vconnections. Also note that the following APIs can only be
+used on transformation vconnections and must not be used on cache
+vconnections or net vconnections:
+
+- `INKVConnWriteVIOGet`
+
+- `INKVConnReadVIOGet`
+
+- `INKVConnClosedGet`
+
+
+APIs such as `INKVConnRead`, `INKVConnWrite`, `INKVConnClose`,
+`INKVConnAbort`, and `INKVConnShutdown` can be used on any kind of
+vconnections.
+
+When you are finished:
+
+ INKCacheKeyDestroy (key);
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheInterfaceFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheInterfaceFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheInterfaceFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/CacheInterfaceFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,78 @@
+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](INKNetVConnRemotePortGet) - INKNetVConnRemotePortGet
+INKCacheKeyDigestSet - [Next](INKCacheKeyDigestSet)
+## Cache Interface Functions
+
+****
+[INKCacheKeyCreate](CacheInterfaceFunctions#INKCacheKeyCreate)
+[INKSetCacheUrl](CacheInterfaceFunctions#INKSetCacheUrl)
+[INKCacheKeyDigestSet](INKCacheKeyDigestSet)
+[INKCacheKeyHostNameSet](INKCacheKeyHostNameSet)
+[INKCacheKeyDestroy](INKCacheKeyDestroy)
+[INKCacheRead](INKCacheRead)
+[INKCacheReady](INKCacheReady)
+[INKCacheWrite](INKCacheWrite)
+[INKCacheRemove](INKCacheRemove)
+[INKCacheKeyPinnedSet](INKCacheKeyPinnedSet)
+[INKVConnCacheObjectSizeGet](INKVConnCacheObjectSizeGet)
+### INKCacheKeyCreate
+
+Creates a new cache key that will be assigned to an object to be
+cached.
+
+**Prototype**
+ ~ `INKReturnCode INKCacheKeyCreate (InkCacheKey *<em class="replaceable"><code>new_key`)
+
+**Arguments**
+ ~ `INKCacheKey *``<em class="replaceable"><code>new_key`
+ is set to the allocated key.
+
+**Description**
+ ~ Creates (allocates memory for) a new cache key. The key can
+ then be generated and assigned to an object using
+ `INKCacheKeyDigestSet`.
+
+**Returns**
+ ~ `INK_SUCCESS` if successful.
+
+ `INK_ERROR` if the cache key could not be allocated.
+
+
+### INKSetCacheUrl
+
+This is an API to set the cache URL. This will be the URL for the
+cached object.
+
+**Prototype**
+ ~ `INKReturnCode INKSetCacheUrl (INKHttpTxn <span class="replaceable">txnp</span>, const char *<span class="replaceable">url</span>)`
+
+**Arguments**
+ ~ The URL for the cached object will be set
+ to`<span class="replaceable"> url</span>`.
+
+**Example**
+ ~ INKHttpTxn txnp = (INKHttpTxn)edata;
+ if (INKSetCacheUrl(txnp, "http://www.yahoo.com") != INK_SUCCESS) {
+ // ERROR
+ }
+
+