HTTP +Utilities Library Overview

Purpose

The InetProtUtils 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.

Required background

The clients that make use of +this API must be familiar with the following standards:

RFC 2396, for Uniform Resource Identifiers (URI)
RFC 1123 for internet date and time specifications
WAP WSP for HTTP functionality.

Key concepts

The component has the following key +concepts:

URI: Universal Resource Identifier (URI) is a formatted string that identifies +the location and name of a resource, for instance a web page address.
URI components: Let us consider the following URI:

http://user:info@waterlang.org:80/top_path/foo.htm?checkme#ref

The +URI can be split into components as follows:
+ + + +URI Component +Example + + + + +
Scheme (protocol)
+
http
+ + +
Authority

+
User Information

+
Host

+
Port

+
+

+
user:info

+
waterlang.org

+
80

+
+ + +
Path
+
top_path/foo.htm
+ + +
Query
+
checkme
+ + +
Segment
+
ref
+ + + +
Authority component: In an URI, the user information, host and port information put together +is called authority. Format for authority appears as the following:

[user-info@]host[:port]

where, user-info may consist of a user name and, optionally, scheme-specific information +about how to gain authorization to access the server, for example, password. port specifies +the port number.

Architectural relationships

The InetProtUtils API +(inetprotutils.dll) is used by the following components:

App services
- DM / DS
- Content Handling Framework
Symbian platform services:
- Certificate lib
- Multimedia

API summary

The following classes are used for +creating, parsing and modifying the URI:

+ + + +Class Name +Description + + + + +

CUri8

Creates URI from parts and modifies the URI.

+ + +

CAuthority8

Modifies the authority and creates authority from parts.

+ + +

TUriC8

Retrieves information about the URI such as extract, compare, validate +etc. (the non-modifying functionality).

+ + +

TAuthorityC8

Retrieves information about the authority URI such as extract, compare, +validate etc.

+ + +

TUriParser8

Parses a text URI.

+ + +

TAuthorityParser8

Parses a text authority.

+ + + +

The following classes are used for parsing delimited data in the +URI:

+ + + +Class Name +Description + + + + +

CDelimitedPath8

Creates a delimited path, where components of the path are delimited +by '/' .

+ + +

CDelimitedQuery8

Creates a delimited query, where components of the query are delimited +by '&'.

+ + +

CDelimitedPathSegment8

Creates a delimited path segment, where components of the path segment +are delimited by ';'.

+ + +

TDelimitedPathParser8

Parses path delimited by a '/'.

+ + +

TDelimitedQueryParser8

Parses query delimited by a '&'.

+ + +

TDelimitedPathSegmentParser8

Parses path segments delimited by a ';'.

+ + +

EscapeUtils

Encodes and decodes excluded and reserved URI characters. It can +be used with 8 bit and 16 bit descriptors.

+ + +

InetProtTextUtils

Parses HTTP header text.

+ + +

UriUtils

Provides extra utilities for URI/Authority classes such as creating +URI from Unicode descriptor.

+ + + +

The following classes are used for encoding and decoding WSP headers:

+ + + +Class Name +Description + + + + +

CWspHeaderEncoder

The class is used to encode one header field at a time with all +its values and parameters.

+ + +

TWspHeaderSegmenter

The class is used to separate a WSP buffer into WSP header name/value +pairs.

+ + +

TWspPrimitiveEncoder

The class is used to convert WSP header data into binary strings.

+ + +

TWspPrimitiveDecoder

The class is used to convert the binary data into integers, strings, +dates, etc.

+ + +

TWspField

The class holds the name and value pair of WSP header field.

+ + + +

The following diagram shows the InetProtUtils classes +and their relationships.

+ Class diagram for InetProtUtils + +

Typical uses

Applications that use HTTP transport +framework use InetProtUtils API. The utilities may also +be useful for applications which deal with internet strings or URIs, such +as mail or IM applications.

The following tasks can be performed using InetProtUtils:

Creating +an URI

URI can be created in different ways. It can be created +from parts, from file or by resolving two URIs using CUri8 class.

For +more information on creating a URI, refer to Creating +an URI tutorial.

Parsing an URI

To check if +the components in the URI are syntactically correct as per the four main components +and fragment identifier, parse the URI. Use TUriParser8 class +to parse an URI.

For more information on parsing, refer to Parsing +an URI tutorial.

URI classes namely, CUri8, TUriC8 and TUriParser8 provide +functionalities for parsing generic and SIP URIs. CUri8 class +provides a reference to a TUriC8 object so that the non-modifying +functionality can be used. TUriC8 is used to obtain information +about an URI.

Extracting URI components

TUriC8 class +provides extracting methods to extract components from the URI. TAuthority8 class +extracts the authority component.

For more information on getting +URI components, refer to Extracting +the URI Components tutorial.

Generating the filename from +an URI

A fully qualified file name can be generated from a file +URI object. TUriC8::GetFileNameL() provides this functionality. +The path component encodes the file's location on the file system.

For +more information, refer to Generating +File Name from URI tutorial.

Validating a URI

Use TUriParser8::Validate() to +check if components in a given URI are valid. This validates only SIP and +SIPS scheme components.

For more information, refer to Validating +an URI tutorial.

Parsing delimited data

URI +components are separated into segments using delimiters. Parse this delimited +data. TDelimitedXxxxParser8 classes provide the functionality +to parse the delimited data, extract the current segment and parse the string +for the next segment.

For more information, refer to Parsing +Delimited Data tutorial.

Modifying the data +and the delimiter

The delimiters and segments of data within +an URI can be added, removed and parsed. This functionality is provided by CDelimitedXxxx8 classes.

For +more information, refer to Modifying +the Data and Delimiter tutorial.

Escape encoding and decoding +unsafe characters in an URI

The reserved and unsafe data in the +URI is escape encoded and decoded using EscapeUtils class. +It also supports converting Unicode data (16-bit descriptor) into UTF8 data +(8-bit descriptor) and vice-versa. For more information, refer to Escape +Encoding and Decoding and Converting +between Unicode and Utf8 tutorials.

Manipulating the URI +data

The data in an URI can be manipulated using various text +parsing utilities that are used typically in HTTP headers. InetProtTextUtils provides +functionality to:

remove the leading/trailing +contiguous white space characters from the descriptors
convert the decimal/hexadecimal +value to descriptor and vice versa.
extract tokens from:
- a list, which is a string +separated with a character, for example, abc, def, ghi.
- quoted strings in text.

It supports both Unicode and UTF-8 formats. For more information +on text manipulations, refer to Manipulating +URI Data tutorial.

Using URI utilities

Additional +functionality to create an URI from unicode descriptor is provided by UriUtils class. +It also allows to translate unsafe characters to UTF8 and escape-encode.

For +more information, refer to Using +URI utilities.

Using datetime utilities

To +store dates in universal times and parse the internet dates into TDateTime dates, +use TInternetDate.

For more information, refer +to Using Date and Time +Utilities tutorial.

Escape encoding and decoding the WSP +header

The WSP header information is encoded and decoded using CWspHeaderEncoder. +It uses TWspPrimitiveEncoder to convert the data into binary +strings.

For more information, refer to Encoding +and Decoding WSP Header.

Use Cxxx classes +to create text from parts and TxxParser classes to parse +text into components.