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:[email protected]: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:

[[email protected]]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:

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

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

The following diagram shows the InetProtUtils classes and their relationships.

Figure 1. 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.