Week 23 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462.
<?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>