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:

[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.

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.

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