InetProtUtils Overview

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.

The clients that make use of this API need to be familiar with these standards:

• RFC 2396, for Uniform Resource Identifiers (URI)

• RFC 1123 for internet date and time specifications

• WAP WSP for HTTP functionality.

The component has the following key concepts:

URI

A 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 this 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 a URI, the user information, host and port information put together is called authority. Format for authority looks like this:

[user-info@]host[:port]

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

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

• App services

  • DM / DS

  • Content Handling Framework

  • Java MIDlet installer

• Symbian OS services:

  • Certificate lib

  • Multimedia

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

Class Name Description CUri8 The class is used for creating URI from parts and modifying the URI. CAuthority8 The class is used for modifying the authority, creating authority from parts. TUriC8 The class is used to get information about the URI such as extract, compare, validate etc. the non-modifying functionality. TAuthorityC8 The class is used to get information about the authority URI such as extract, compare, validate etc. TUriParser8 The class is used to parse a text URI. TAuthorityParser8 The class is used to parse a text authority.

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

Class Name Description CDelimitedPath8 The class is used for creating a delimited path, where components of the path are delimited by '/' . CDelimitedQuery8 The class is used for creating a delimited query, where components of the query are delimited by '&'. CDelimitedPathSegment8 The class is used for creating a delimited path segment, where components of the path segment are delimited by ';'. TDelimitedPathParser8 The class is used for parsing path delimited by a '/'. TDelimitedQueryParser8 The class is used for parsing query delimited by a '&'. TDelimitedPathSegmentParser8 The class is used for parsing path segments delimited by a ';'. EscapeUtils The class is used to encode and decode excluded and reserved URI characters. It can be used with 8 bit and 16 bit descriptors. InetProtTextUtils The class is used for HTTP header text parsing. UriUtils The class 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.

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

The following tasks can be performed using InetProtUtils:

Creating a 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 How to create a URI.

Parsing a URI

To check if the components in the URI are syntactically correct as per the four main components and fragment identifier, one needs to parse the URI. Use TUriParser8 class when you need to parse a URI.

For more information on parsing, refer to How to parse a URI.

URI classes namely, CUri8, TUriC8 and TUriParser8 provide functionality 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 get information about a URI.

Extracting URI components

Components from the URI can be extracted using extracting methods provided by TUriC8 class. You can extract the authority component using TAuthority8 class.

For more information on getting URI components, refer to How to extract the URI components.

Generating the filename from a URI

A fully qualified filename 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 How to generate filename from URI.

Validating a URI

You can check if components in a given URI are valid using TUriParser8::Validate(). This validates only SIP and SIPS scheme components.

For more information, refer to How to validate a URI.

Parsing delimited data

URI components are seperated into segments using delimiters. You can 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 How to parse the delimited data.

Modifying the data and the delimiter

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

For more information, refer to How to modify the data and the delimiter.

Escape encoding and decoding unsafe characters in a 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 How to escape encode and decode.

Manipulating the URI data

The data in a URI can be manipulated using various text parsing utilities that are used typically in HTTP headers. InetProtTextUtils provides functionaliy 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 How to manipulate URI data.

Using URI utilities

Additional functionality to create a 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, TInternetDate is used.

For more information, refer to Using date and time utilities.

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 How to encode and decode WSP header.

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