--- a/Symbian3/SDK/Source/GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,303 +1,303 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723" xml:lang="en"><title>HTTP
-Utilities Library Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section><title>Purpose</title> <p>The <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API
-provides functionality to handle URIs, such as extracting URI components,
-constructing and modifying a URI, text utilities, and URI component utilities
-required to work with URIs. </p> </section>
-<section><title>Required background</title> <p>The clients that make use of
-this API must be familiar with the following standards: </p> <ul>
-<li id="GUID-4F6AFFCE-D446-5E19-91F5-8F29A059D7C9"><p> <xref href="http://www.ietf.org/rfc/rfc2396.txt" scope="external">RFC 2396</xref>, for Uniform Resource Identifiers (URI) </p> </li>
-<li id="GUID-D32F8A79-8D61-5B0F-A38C-9C77C50D1E1D"><p> <xref href="http://tools.ietf.org/html/rfc1132" scope="external">RFC 1123</xref> for internet date and time specifications </p> </li>
-<li id="GUID-8B0C887C-0856-5903-BF3C-558BCFC8BC1F"><p> <xref href="http://www.openmobilealliance.org/tech/affiliates/wap/wap-230-wsp-20010705-a.pdf" scope="external">WAP WSP</xref> for HTTP functionality. </p> </li>
-</ul> </section>
-<section><title>Key concepts</title> <p>The component has the following key
-concepts: </p> <dl>
-<dlentry>
-<dt>URI</dt>
-<dd><p>Universal Resource Identifier (URI) is a formatted string that identifies
-the location and name of a resource, for instance a web page address. </p> </dd>
-</dlentry>
-<dlentry>
-<dt>URI components</dt>
-<dd><p>Let us consider the following URI: </p> <p> <codeph>http://user:info@waterlang.org:80/top_path/foo.htm?checkme#ref</codeph> </p> <p>The
-URI can be split into components as follows: </p> <table id="GUID-4765D4B9-A3E4-5ADF-B1A7-830BB7E10EBD">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>URI Component</entry>
-<entry>Example</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p>Scheme (protocol) </p> </entry>
-<entry><p> <codeph>http</codeph> </p> </entry>
-</row>
-<row>
-<entry><p>Authority </p> <ul>
-<li id="GUID-7FF5EC7F-1B7C-5E91-9479-E305E4459EA0"><p>User Information </p> </li>
-<li id="GUID-BC76E4D9-7393-5464-9E3C-7B0756FFD4D1"><p>Host </p> </li>
-<li id="GUID-B586337A-1116-58C4-BC7F-940945AD38B8"><p>Port </p> </li>
-</ul> </entry>
-<entry><p> </p> <ul>
-<li id="GUID-81135C6E-C55E-5699-98D6-49BA2D9871BE"><p> <codeph>user:info</codeph> </p> </li>
-<li id="GUID-4A07BDB8-F32B-5572-8B46-4E0C78EDC65C"><p> <codeph>waterlang.org</codeph> </p> </li>
-<li id="GUID-18C83120-4046-52B7-926C-DC9644E86C49"><p> <codeph>80</codeph> </p> </li>
-</ul> </entry>
-</row>
-<row>
-<entry><p>Path </p> </entry>
-<entry><p> <codeph>top_path/foo.htm</codeph> </p> </entry>
-</row>
-<row>
-<entry><p>Query </p> </entry>
-<entry><p> <codeph>checkme</codeph> </p> </entry>
-</row>
-<row>
-<entry><p>Segment </p> </entry>
-<entry><p> <codeph> ref</codeph> </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> </dd>
-</dlentry>
-<dlentry>
-<dt>Authority component</dt>
-<dd><p>In an URI, the user information, host and port information put together
-is called authority. Format for authority appears as the following: </p> <p> <codeph>[user-info@]host[:port]</codeph> </p> <p>where, <codeph>user-info</codeph> may consist of a user name and, optionally, scheme-specific information
-about how to gain authorization to access the server, for example, password. <codeph>port</codeph> specifies
-the port number. </p> </dd>
-</dlentry>
-</dl> </section>
-<section><title>Architectural relationships</title> <p>The <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API
-(<filepath>inetprotutils.dll</filepath>) is used by the following components: </p> <ul>
-<li id="GUID-8FA3CA2A-0A42-5F64-9AC0-56B2E340B63A"><p>App services </p> <ul>
-<li id="GUID-922DF8F6-1801-5A99-AD8D-15A92DF31242"><p>DM / DS </p> </li>
-<li id="GUID-096E985C-6170-5908-955E-4406CC3C690D"><p>Content Handling Framework </p> </li>
-</ul> </li>
-<li id="GUID-DCA9F8B1-1066-57F6-9BC5-ECF8D81B0EA2"><p>Symbian platform services: </p> <ul>
-<li id="GUID-88AEE90D-1A2D-5468-95C8-AFE8ECB5FF14"><p>Certificate lib </p> </li>
-<li id="GUID-4265166D-092D-5005-8E7D-127EB9C25DF1"><p>Multimedia </p> </li>
-</ul> </li>
-</ul> </section>
-<section><title>API summary</title> <p>The following classes are used for
-creating, parsing and modifying the URI: </p> <table id="GUID-6161C49F-F18A-51BD-A6F8-51E045A1DD6E">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>Class Name</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> </p> </entry>
-<entry><p>Creates URI from parts and modifies the URI. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita"><apiname>CAuthority8</apiname></xref> </p> </entry>
-<entry><p>Modifies the authority and creates authority from parts. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> </p> </entry>
-<entry><p>Retrieves information about the URI such as extract, compare, validate
-etc. (the non-modifying functionality). </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-F7CCFDE5-4829-314C-A209-2F6714C02AA6.dita"><apiname>TAuthorityC8</apiname></xref> </p> </entry>
-<entry><p>Retrieves information about the authority URI such as extract, compare,
-validate etc. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> </p> </entry>
-<entry><p>Parses a text URI. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-985C12CB-9230-3A35-9F5F-E455D4C23EBB.dita"><apiname>TAuthorityParser8</apiname></xref> </p> </entry>
-<entry><p>Parses a text authority. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The following classes are used for parsing delimited data in the
-URI: </p> <table id="GUID-D58565BF-4859-53FA-8278-CF3ED3D9B487">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>Class Name</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-51DFAA06-EC5E-32E6-9819-39938C46B2C0.dita"><apiname>CDelimitedPath8</apiname></xref> </p> </entry>
-<entry><p>Creates a delimited path, where components of the path are delimited
-by '/' . </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-9A640379-04BC-3A8E-9452-54833B2419AE.dita"><apiname>CDelimitedQuery8</apiname></xref> </p> </entry>
-<entry><p>Creates a delimited query, where components of the query are delimited
-by '&'. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-CF89AECB-5085-32CA-85B4-3573CDB1D595.dita"><apiname>CDelimitedPathSegment8</apiname></xref> </p> </entry>
-<entry><p>Creates a delimited path segment, where components of the path segment
-are delimited by ';'. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-CD78AD53-FD6C-397A-9930-12E8EDCF6040.dita"><apiname>TDelimitedPathParser8</apiname></xref> </p> </entry>
-<entry><p>Parses path delimited by a '/'. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-F76F2546-D3AC-341B-BED8-D3C88EA2C018.dita"><apiname>TDelimitedQueryParser8</apiname></xref> </p> </entry>
-<entry><p>Parses query delimited by a '&'. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-F55AF53B-662F-3682-9B6D-A3D14AED0D58.dita"><apiname>TDelimitedPathSegmentParser8</apiname></xref> </p> </entry>
-<entry><p>Parses path segments delimited by a ';'. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-9CC256C4-D4A2-3534-9B3C-2FBF1AAE5F51.dita"><apiname>EscapeUtils</apiname></xref> </p> </entry>
-<entry><p>Encodes and decodes excluded and reserved URI characters. It can
-be used with 8 bit and 16 bit descriptors. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-9FC0E63B-1927-30B0-8A97-E9CB1010FFEE.dita"><apiname> InetProtTextUtils</apiname></xref> </p> </entry>
-<entry><p>Parses HTTP header text. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita"><apiname>UriUtils</apiname></xref> </p> </entry>
-<entry><p>Provides extra utilities for URI/Authority classes such as creating
-URI from Unicode descriptor. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The following classes are used for encoding and decoding WSP headers: </p> <table id="GUID-7EFEBABF-2AE5-56EF-9C73-B3B84E279A93">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>Class Name</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-8E0D4BBE-BD06-396F-9517-45F9BFCDEF37.dita"><apiname>CWspHeaderEncoder</apiname></xref> </p> </entry>
-<entry><p>The class is used to encode one header field at a time with all
-its values and parameters. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-310AB7CF-C1B0-3C5A-8C4A-C96259A49F0F.dita"><apiname>TWspHeaderSegmenter </apiname></xref> </p> </entry>
-<entry><p>The class is used to separate a WSP buffer into WSP header name/value
-pairs. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-CFE23AB1-A94B-3609-8B37-35C2A9023DE3.dita"><apiname>TWspPrimitiveEncoder</apiname></xref> </p> </entry>
-<entry><p>The class is used to convert WSP header data into binary strings. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-A0F4B729-E70A-3125-A5A6-D908216FCA5A.dita"><apiname>TWspPrimitiveDecoder</apiname></xref> </p> </entry>
-<entry><p>The class is used to convert the binary data into integers, strings,
-dates, etc. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-9C280536-E402-35CB-B317-BE4E6A8C23D8.dita"><apiname>TWspField</apiname></xref> </p> </entry>
-<entry><p>The class holds the name and value pair of WSP header field. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The following diagram shows the <codeph>InetProtUtils</codeph> classes
-and their relationships. </p> <fig id="GUID-482F6611-C67C-5003-94DD-29DCBCC85092">
-<title> Class diagram for InetProtUtils </title>
-<image href="GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e172177_href.png" placement="inline"/>
-</fig> </section>
-<section><title>Typical uses</title> <p>Applications that use HTTP transport
-framework use <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API. The utilities may also
-be useful for applications which deal with internet strings or URIs, such
-as mail or IM applications. </p> <p>The following tasks can be performed using <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref>: </p> <p><b>Creating
-an URI </b> </p> <p>URI can be created in different ways. It can be created
-from parts, from file or by resolving two URIs using <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> class. </p> <p>For
-more information on creating a URI, refer to <xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita">Creating
-an URI</xref> tutorial. </p> <p><b>Parsing an URI </b> </p> <p>To check if
-the components in the URI are syntactically correct as per the four main components
-and fragment identifier, parse the URI. Use <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> class
-to parse an URI. </p> <p>For more information on parsing, refer to <xref href="GUID-D535D51E-EAF5-581A-929B-5B1EF179A273.dita">Parsing
-an URI</xref> tutorial. </p> <p>URI classes namely, <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref>, <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> and <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> provide
-functionalities for parsing generic and SIP URIs. <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> class
-provides a reference to a <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> object so that the non-modifying
-functionality can be used. <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> is used to obtain information
-about an URI. </p> <p><b>Extracting URI components </b> </p> <p> <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> class
-provides extracting methods to extract components from the URI. <xref href="GUID-25B6817F-8EBC-3DF3-B3BC-3D1E1430C8A6.dita"><apiname>TAuthority8</apiname></xref> class
-extracts the authority component. </p> <p>For more information on getting
-URI components, refer to <xref href="GUID-8E3BD71D-D372-5315-B282-F87FA60A1D5A.dita">Extracting
-the URI Components</xref> tutorial. </p> <p><b>Generating the filename from
-an URI </b> </p> <p>A fully qualified file name can be generated from a file
-URI object. <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita#GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74/GUID-AD8DC94E-743B-3347-9AC4-B37AE23AA786"><apiname>TUriC8::GetFileNameL()</apiname></xref> provides this functionality.
-The path component encodes the file's location on the file system. </p> <p>For
-more information, refer to <xref href="GUID-4B7352BF-4BF8-5FF2-8835-F146BB7D4EAC.dita">Generating
-File Name from URI</xref> tutorial. </p> <p><b>Validating a URI </b> </p> <p>Use <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita#GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1/GUID-9B6C3634-7E19-39B5-A12F-80A16DDCFF4E"><apiname>TUriParser8::Validate()</apiname></xref> to
-check if components in a given URI are valid. This validates only SIP and
-SIPS scheme components. </p> <p>For more information, refer to <xref href="GUID-8F5BC47B-0551-5245-A1ED-629380111B43.dita">Validating
-an URI</xref> tutorial. </p> <p><b>Parsing delimited data </b> </p> <p>URI
-components are separated into segments using delimiters. Parse this delimited
-data. <codeph>TDelimitedXxxxParser8</codeph> classes provide the functionality
-to parse the delimited data, extract the current segment and parse the string
-for the next segment. </p> <p>For more information, refer to <xref href="GUID-42F0F282-58D6-4878-B53D-EAEEF86A3D7D.dita">Parsing
-Delimited Data</xref> tutorial. </p> <p><b>Modifying the data
-and the delimiter </b> </p> <p>The delimiters and segments of data within
-an URI can be added, removed and parsed. This functionality is provided by <codeph>CDelimitedXxxx8</codeph> classes. </p> <p>For
-more information, refer to <xref href="GUID-834F5FC8-EBE4-4076-B1E3-38DDFF89D700.dita">Modifying
-the Data and Delimiter</xref> tutorial. </p> <p><b>Escape encoding and decoding
-unsafe characters in an URI </b> </p> <p>The reserved and unsafe data in the
-URI is escape encoded and decoded using <xref href="GUID-9CC256C4-D4A2-3534-9B3C-2FBF1AAE5F51.dita"><apiname>EscapeUtils</apiname></xref> class.
-It also supports converting Unicode data (16-bit descriptor) into UTF8 data
-(8-bit descriptor) and vice-versa. For more information, refer to <xref href="GUID-0E8206E9-4F1D-5DF5-8A69-9B0831061CFF.dita">Escape
-Encoding and Decoding</xref> and <xref href="GUID-853BFDC0-1993-5EFC-AA68-C9EA496EEF3F.dita">Converting
-between Unicode and Utf8</xref> tutorials. </p> <p><b>Manipulating the URI
-data </b> </p> <p>The data in an URI can be manipulated using various text
-parsing utilities that are used typically in HTTP headers. <xref href="GUID-9FC0E63B-1927-30B0-8A97-E9CB1010FFEE.dita"><apiname>InetProtTextUtils</apiname></xref> provides
-functionality to: </p> <ul>
-<li id="GUID-E845FA13-8644-5762-94C7-F34C21BA50CC"><p>remove the leading/trailing
-contiguous white space characters from the descriptors </p> </li>
-<li id="GUID-D2418E05-405D-5E19-A239-D5261B420A83"><p>convert the decimal/hexadecimal
-value to descriptor and vice versa. </p> </li>
-<li id="GUID-99B9C4A8-AE2A-5541-BCB0-59E138898FB8"><p>extract tokens from: </p> <ul>
-<li id="GUID-AE9AFA73-84D8-5EDD-A51C-21714FA5C96C"><p>a list, which is a string
-separated with a character, for example, abc, def, ghi. </p> </li>
-<li id="GUID-CF6A13D6-0FB0-57A3-B6E2-1791316FD61E"><p>quoted strings in text. </p> </li>
-</ul> </li>
-</ul> <p>It supports both Unicode and UTF-8 formats. For more information
-on text manipulations, refer to <xref href="GUID-098106AC-0A5A-5C7D-B432-492EADFE7EA3.dita">Manipulating
-URI Data</xref> tutorial. </p><p><b>Using URI utilities </b> </p> <p>Additional
-functionality to create an URI from unicode descriptor is provided by <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita"><apiname>UriUtils</apiname></xref> class.
-It also allows to translate unsafe characters to UTF8 and escape-encode. </p> <p>For
-more information, refer to <xref href="GUID-A8F13E5A-56F2-5C72-AF81-5AC062B94C6C.dita">Using
-URI utilities</xref>. </p> <p><b>Using datetime utilities </b> </p> <p>To
-store dates in universal times and parse the internet dates into <xref href="GUID-13A9DD2B-8ABC-3D62-B54E-4F5DD5B9228B.dita"><apiname>TDateTime</apiname></xref> dates,
-use <xref href="GUID-156E9C02-99AD-3C63-80AD-939A6DFB08B1.dita"><apiname>TInternetDate</apiname></xref>. </p> <p>For more information, refer
-to <xref href="GUID-3F7142D6-261B-5FB9-888A-1A9BB51B67E5.dita">Using Date and Time
-Utilities</xref> tutorial. </p> <p><b>Escape encoding and decoding the WSP
-header </b> </p> <p>The WSP header information is encoded and decoded using <xref href="GUID-8E0D4BBE-BD06-396F-9517-45F9BFCDEF37.dita"><apiname>CWspHeaderEncoder</apiname></xref>.
-It uses <xref href="GUID-CFE23AB1-A94B-3609-8B37-35C2A9023DE3.dita"><apiname>TWspPrimitiveEncoder</apiname></xref> to convert the data into binary
-strings. </p> <p>For more information, refer to <xref href="GUID-0BE9F825-9FF8-55A1-AF7C-A380A0C64735.dita">Encoding
-and Decoding WSP Header</xref>. </p><note> Use <codeph>Cxxx</codeph> classes
-to create text from parts and <codeph>TxxParser</codeph> classes to parse
-text into components.</note> </section>
-</conbody><related-links>
-<link href="GUID-F46CDF2C-DA64-5F30-B4C8-CC4B02CE67B9.dita"><linktext>HTTP Utilities
-Library Concepts</linktext></link>
-<link href="GUID-96837414-3041-5E1E-A2E9-C18EECCF86D9.dita"><linktext>HTTP Utilities
-Library Tutorials</linktext></link>
-<link href="GUID-AFAD0F36-330B-50BD-B810-85BE7FA21179.dita"><linktext>HTTP Utilities
-Library Example</linktext></link>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723" xml:lang="en"><title>HTTP
+Utilities Library Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section><title>Purpose</title> <p>The <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API
+provides functionality to handle URIs, such as extracting URI components,
+constructing and modifying a URI, text utilities, and URI component utilities
+required to work with URIs. </p> </section>
+<section><title>Required background</title> <p>The clients that make use of
+this API must be familiar with the following standards: </p> <ul>
+<li id="GUID-4F6AFFCE-D446-5E19-91F5-8F29A059D7C9"><p> <xref href="http://www.ietf.org/rfc/rfc2396.txt" scope="external">RFC 2396</xref>, for Uniform Resource Identifiers (URI) </p> </li>
+<li id="GUID-D32F8A79-8D61-5B0F-A38C-9C77C50D1E1D"><p> <xref href="http://tools.ietf.org/html/rfc1132" scope="external">RFC 1123</xref> for internet date and time specifications </p> </li>
+<li id="GUID-8B0C887C-0856-5903-BF3C-558BCFC8BC1F"><p> <xref href="http://www.openmobilealliance.org/tech/affiliates/wap/wap-230-wsp-20010705-a.pdf" scope="external">WAP WSP</xref> for HTTP functionality. </p> </li>
+</ul> </section>
+<section><title>Key concepts</title> <p>The component has the following key
+concepts: </p> <dl>
+<dlentry>
+<dt>URI</dt>
+<dd><p>Universal Resource Identifier (URI) is a formatted string that identifies
+the location and name of a resource, for instance a web page address. </p> </dd>
+</dlentry>
+<dlentry>
+<dt>URI components</dt>
+<dd><p>Let us consider the following URI: </p> <p> <codeph>http://user:info@waterlang.org:80/top_path/foo.htm?checkme#ref</codeph> </p> <p>The
+URI can be split into components as follows: </p> <table id="GUID-4765D4B9-A3E4-5ADF-B1A7-830BB7E10EBD">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>URI Component</entry>
+<entry>Example</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p>Scheme (protocol) </p> </entry>
+<entry><p> <codeph>http</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>Authority </p> <ul>
+<li id="GUID-7FF5EC7F-1B7C-5E91-9479-E305E4459EA0"><p>User Information </p> </li>
+<li id="GUID-BC76E4D9-7393-5464-9E3C-7B0756FFD4D1"><p>Host </p> </li>
+<li id="GUID-B586337A-1116-58C4-BC7F-940945AD38B8"><p>Port </p> </li>
+</ul> </entry>
+<entry><p> </p> <ul>
+<li id="GUID-81135C6E-C55E-5699-98D6-49BA2D9871BE"><p> <codeph>user:info</codeph> </p> </li>
+<li id="GUID-4A07BDB8-F32B-5572-8B46-4E0C78EDC65C"><p> <codeph>waterlang.org</codeph> </p> </li>
+<li id="GUID-18C83120-4046-52B7-926C-DC9644E86C49"><p> <codeph>80</codeph> </p> </li>
+</ul> </entry>
+</row>
+<row>
+<entry><p>Path </p> </entry>
+<entry><p> <codeph>top_path/foo.htm</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>Query </p> </entry>
+<entry><p> <codeph>checkme</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>Segment </p> </entry>
+<entry><p> <codeph> ref</codeph> </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </dd>
+</dlentry>
+<dlentry>
+<dt>Authority component</dt>
+<dd><p>In an URI, the user information, host and port information put together
+is called authority. Format for authority appears as the following: </p> <p> <codeph>[user-info@]host[:port]</codeph> </p> <p>where, <codeph>user-info</codeph> may consist of a user name and, optionally, scheme-specific information
+about how to gain authorization to access the server, for example, password. <codeph>port</codeph> specifies
+the port number. </p> </dd>
+</dlentry>
+</dl> </section>
+<section><title>Architectural relationships</title> <p>The <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API
+(<filepath>inetprotutils.dll</filepath>) is used by the following components: </p> <ul>
+<li id="GUID-8FA3CA2A-0A42-5F64-9AC0-56B2E340B63A"><p>App services </p> <ul>
+<li id="GUID-922DF8F6-1801-5A99-AD8D-15A92DF31242"><p>DM / DS </p> </li>
+<li id="GUID-096E985C-6170-5908-955E-4406CC3C690D"><p>Content Handling Framework </p> </li>
+</ul> </li>
+<li id="GUID-DCA9F8B1-1066-57F6-9BC5-ECF8D81B0EA2"><p>Symbian platform services: </p> <ul>
+<li id="GUID-88AEE90D-1A2D-5468-95C8-AFE8ECB5FF14"><p>Certificate lib </p> </li>
+<li id="GUID-4265166D-092D-5005-8E7D-127EB9C25DF1"><p>Multimedia </p> </li>
+</ul> </li>
+</ul> </section>
+<section><title>API summary</title> <p>The following classes are used for
+creating, parsing and modifying the URI: </p> <table id="GUID-6161C49F-F18A-51BD-A6F8-51E045A1DD6E">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Class Name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> </p> </entry>
+<entry><p>Creates URI from parts and modifies the URI. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita"><apiname>CAuthority8</apiname></xref> </p> </entry>
+<entry><p>Modifies the authority and creates authority from parts. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> </p> </entry>
+<entry><p>Retrieves information about the URI such as extract, compare, validate
+etc. (the non-modifying functionality). </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-F7CCFDE5-4829-314C-A209-2F6714C02AA6.dita"><apiname>TAuthorityC8</apiname></xref> </p> </entry>
+<entry><p>Retrieves information about the authority URI such as extract, compare,
+validate etc. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> </p> </entry>
+<entry><p>Parses a text URI. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-985C12CB-9230-3A35-9F5F-E455D4C23EBB.dita"><apiname>TAuthorityParser8</apiname></xref> </p> </entry>
+<entry><p>Parses a text authority. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The following classes are used for parsing delimited data in the
+URI: </p> <table id="GUID-D58565BF-4859-53FA-8278-CF3ED3D9B487">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Class Name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-51DFAA06-EC5E-32E6-9819-39938C46B2C0.dita"><apiname>CDelimitedPath8</apiname></xref> </p> </entry>
+<entry><p>Creates a delimited path, where components of the path are delimited
+by '/' . </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-9A640379-04BC-3A8E-9452-54833B2419AE.dita"><apiname>CDelimitedQuery8</apiname></xref> </p> </entry>
+<entry><p>Creates a delimited query, where components of the query are delimited
+by '&'. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-CF89AECB-5085-32CA-85B4-3573CDB1D595.dita"><apiname>CDelimitedPathSegment8</apiname></xref> </p> </entry>
+<entry><p>Creates a delimited path segment, where components of the path segment
+are delimited by ';'. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-CD78AD53-FD6C-397A-9930-12E8EDCF6040.dita"><apiname>TDelimitedPathParser8</apiname></xref> </p> </entry>
+<entry><p>Parses path delimited by a '/'. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-F76F2546-D3AC-341B-BED8-D3C88EA2C018.dita"><apiname>TDelimitedQueryParser8</apiname></xref> </p> </entry>
+<entry><p>Parses query delimited by a '&'. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-F55AF53B-662F-3682-9B6D-A3D14AED0D58.dita"><apiname>TDelimitedPathSegmentParser8</apiname></xref> </p> </entry>
+<entry><p>Parses path segments delimited by a ';'. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-9CC256C4-D4A2-3534-9B3C-2FBF1AAE5F51.dita"><apiname>EscapeUtils</apiname></xref> </p> </entry>
+<entry><p>Encodes and decodes excluded and reserved URI characters. It can
+be used with 8 bit and 16 bit descriptors. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-9FC0E63B-1927-30B0-8A97-E9CB1010FFEE.dita"><apiname> InetProtTextUtils</apiname></xref> </p> </entry>
+<entry><p>Parses HTTP header text. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita"><apiname>UriUtils</apiname></xref> </p> </entry>
+<entry><p>Provides extra utilities for URI/Authority classes such as creating
+URI from Unicode descriptor. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The following classes are used for encoding and decoding WSP headers: </p> <table id="GUID-7EFEBABF-2AE5-56EF-9C73-B3B84E279A93">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Class Name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-8E0D4BBE-BD06-396F-9517-45F9BFCDEF37.dita"><apiname>CWspHeaderEncoder</apiname></xref> </p> </entry>
+<entry><p>The class is used to encode one header field at a time with all
+its values and parameters. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-310AB7CF-C1B0-3C5A-8C4A-C96259A49F0F.dita"><apiname>TWspHeaderSegmenter </apiname></xref> </p> </entry>
+<entry><p>The class is used to separate a WSP buffer into WSP header name/value
+pairs. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-CFE23AB1-A94B-3609-8B37-35C2A9023DE3.dita"><apiname>TWspPrimitiveEncoder</apiname></xref> </p> </entry>
+<entry><p>The class is used to convert WSP header data into binary strings. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-A0F4B729-E70A-3125-A5A6-D908216FCA5A.dita"><apiname>TWspPrimitiveDecoder</apiname></xref> </p> </entry>
+<entry><p>The class is used to convert the binary data into integers, strings,
+dates, etc. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-9C280536-E402-35CB-B317-BE4E6A8C23D8.dita"><apiname>TWspField</apiname></xref> </p> </entry>
+<entry><p>The class holds the name and value pair of WSP header field. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The following diagram shows the <codeph>InetProtUtils</codeph> classes
+and their relationships. </p> <fig id="GUID-482F6611-C67C-5003-94DD-29DCBCC85092">
+<title> Class diagram for InetProtUtils </title>
+<image href="GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e165576_href.png" placement="inline"/>
+</fig> </section>
+<section><title>Typical uses</title> <p>Applications that use HTTP transport
+framework use <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref> API. The utilities may also
+be useful for applications which deal with internet strings or URIs, such
+as mail or IM applications. </p> <p>The following tasks can be performed using <xref href="GUID-46ED72C3-E4BF-336C-BDC1-1F5128A9197D.dita"><apiname>InetProtUtils</apiname></xref>: </p> <p><b>Creating
+an URI </b> </p> <p>URI can be created in different ways. It can be created
+from parts, from file or by resolving two URIs using <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> class. </p> <p>For
+more information on creating a URI, refer to <xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita">Creating
+an URI</xref> tutorial. </p> <p><b>Parsing an URI </b> </p> <p>To check if
+the components in the URI are syntactically correct as per the four main components
+and fragment identifier, parse the URI. Use <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> class
+to parse an URI. </p> <p>For more information on parsing, refer to <xref href="GUID-D535D51E-EAF5-581A-929B-5B1EF179A273.dita">Parsing
+an URI</xref> tutorial. </p> <p>URI classes namely, <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref>, <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> and <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita"><apiname>TUriParser8</apiname></xref> provide
+functionalities for parsing generic and SIP URIs. <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> class
+provides a reference to a <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> object so that the non-modifying
+functionality can be used. <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> is used to obtain information
+about an URI. </p> <p><b>Extracting URI components </b> </p> <p> <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> class
+provides extracting methods to extract components from the URI. <xref href="GUID-25B6817F-8EBC-3DF3-B3BC-3D1E1430C8A6.dita"><apiname>TAuthority8</apiname></xref> class
+extracts the authority component. </p> <p>For more information on getting
+URI components, refer to <xref href="GUID-8E3BD71D-D372-5315-B282-F87FA60A1D5A.dita">Extracting
+the URI Components</xref> tutorial. </p> <p><b>Generating the filename from
+an URI </b> </p> <p>A fully qualified file name can be generated from a file
+URI object. <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita#GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74/GUID-AD8DC94E-743B-3347-9AC4-B37AE23AA786"><apiname>TUriC8::GetFileNameL()</apiname></xref> provides this functionality.
+The path component encodes the file's location on the file system. </p> <p>For
+more information, refer to <xref href="GUID-4B7352BF-4BF8-5FF2-8835-F146BB7D4EAC.dita">Generating
+File Name from URI</xref> tutorial. </p> <p><b>Validating a URI </b> </p> <p>Use <xref href="GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1.dita#GUID-EB2EEEF1-705B-334D-A4B0-3D0C4CBE2DA1/GUID-9B6C3634-7E19-39B5-A12F-80A16DDCFF4E"><apiname>TUriParser8::Validate()</apiname></xref> to
+check if components in a given URI are valid. This validates only SIP and
+SIPS scheme components. </p> <p>For more information, refer to <xref href="GUID-8F5BC47B-0551-5245-A1ED-629380111B43.dita">Validating
+an URI</xref> tutorial. </p> <p><b>Parsing delimited data </b> </p> <p>URI
+components are separated into segments using delimiters. Parse this delimited
+data. <codeph>TDelimitedXxxxParser8</codeph> classes provide the functionality
+to parse the delimited data, extract the current segment and parse the string
+for the next segment. </p> <p>For more information, refer to <xref href="GUID-42F0F282-58D6-4878-B53D-EAEEF86A3D7D.dita">Parsing
+Delimited Data</xref> tutorial. </p> <p><b>Modifying the data
+and the delimiter </b> </p> <p>The delimiters and segments of data within
+an URI can be added, removed and parsed. This functionality is provided by <codeph>CDelimitedXxxx8</codeph> classes. </p> <p>For
+more information, refer to <xref href="GUID-834F5FC8-EBE4-4076-B1E3-38DDFF89D700.dita">Modifying
+the Data and Delimiter</xref> tutorial. </p> <p><b>Escape encoding and decoding
+unsafe characters in an URI </b> </p> <p>The reserved and unsafe data in the
+URI is escape encoded and decoded using <xref href="GUID-9CC256C4-D4A2-3534-9B3C-2FBF1AAE5F51.dita"><apiname>EscapeUtils</apiname></xref> class.
+It also supports converting Unicode data (16-bit descriptor) into UTF8 data
+(8-bit descriptor) and vice-versa. For more information, refer to <xref href="GUID-0E8206E9-4F1D-5DF5-8A69-9B0831061CFF.dita">Escape
+Encoding and Decoding</xref> and <xref href="GUID-853BFDC0-1993-5EFC-AA68-C9EA496EEF3F.dita">Converting
+between Unicode and Utf8</xref> tutorials. </p> <p><b>Manipulating the URI
+data </b> </p> <p>The data in an URI can be manipulated using various text
+parsing utilities that are used typically in HTTP headers. <xref href="GUID-9FC0E63B-1927-30B0-8A97-E9CB1010FFEE.dita"><apiname>InetProtTextUtils</apiname></xref> provides
+functionality to: </p> <ul>
+<li id="GUID-E845FA13-8644-5762-94C7-F34C21BA50CC"><p>remove the leading/trailing
+contiguous white space characters from the descriptors </p> </li>
+<li id="GUID-D2418E05-405D-5E19-A239-D5261B420A83"><p>convert the decimal/hexadecimal
+value to descriptor and vice versa. </p> </li>
+<li id="GUID-99B9C4A8-AE2A-5541-BCB0-59E138898FB8"><p>extract tokens from: </p> <ul>
+<li id="GUID-AE9AFA73-84D8-5EDD-A51C-21714FA5C96C"><p>a list, which is a string
+separated with a character, for example, abc, def, ghi. </p> </li>
+<li id="GUID-CF6A13D6-0FB0-57A3-B6E2-1791316FD61E"><p>quoted strings in text. </p> </li>
+</ul> </li>
+</ul> <p>It supports both Unicode and UTF-8 formats. For more information
+on text manipulations, refer to <xref href="GUID-098106AC-0A5A-5C7D-B432-492EADFE7EA3.dita">Manipulating
+URI Data</xref> tutorial. </p><p><b>Using URI utilities </b> </p> <p>Additional
+functionality to create an URI from unicode descriptor is provided by <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita"><apiname>UriUtils</apiname></xref> class.
+It also allows to translate unsafe characters to UTF8 and escape-encode. </p> <p>For
+more information, refer to <xref href="GUID-A8F13E5A-56F2-5C72-AF81-5AC062B94C6C.dita">Using
+URI utilities</xref>. </p> <p><b>Using datetime utilities </b> </p> <p>To
+store dates in universal times and parse the internet dates into <xref href="GUID-13A9DD2B-8ABC-3D62-B54E-4F5DD5B9228B.dita"><apiname>TDateTime</apiname></xref> dates,
+use <xref href="GUID-156E9C02-99AD-3C63-80AD-939A6DFB08B1.dita"><apiname>TInternetDate</apiname></xref>. </p> <p>For more information, refer
+to <xref href="GUID-3F7142D6-261B-5FB9-888A-1A9BB51B67E5.dita">Using Date and Time
+Utilities</xref> tutorial. </p> <p><b>Escape encoding and decoding the WSP
+header </b> </p> <p>The WSP header information is encoded and decoded using <xref href="GUID-8E0D4BBE-BD06-396F-9517-45F9BFCDEF37.dita"><apiname>CWspHeaderEncoder</apiname></xref>.
+It uses <xref href="GUID-CFE23AB1-A94B-3609-8B37-35C2A9023DE3.dita"><apiname>TWspPrimitiveEncoder</apiname></xref> to convert the data into binary
+strings. </p> <p>For more information, refer to <xref href="GUID-0BE9F825-9FF8-55A1-AF7C-A380A0C64735.dita">Encoding
+and Decoding WSP Header</xref>. </p><note> Use <codeph>Cxxx</codeph> classes
+to create text from parts and <codeph>TxxParser</codeph> classes to parse
+text into components.</note> </section>
+</conbody><related-links>
+<link href="GUID-F46CDF2C-DA64-5F30-B4C8-CC4B02CE67B9.dita"><linktext>HTTP Utilities
+Library Concepts</linktext></link>
+<link href="GUID-96837414-3041-5E1E-A2E9-C18EECCF86D9.dita"><linktext>HTTP Utilities
+Library Tutorials</linktext></link>
+<link href="GUID-AFAD0F36-330B-50BD-B810-85BE7FA21179.dita"><linktext>HTTP Utilities
+Library Example</linktext></link>
</related-links></concept>
\ No newline at end of file