Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



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

[Top]


Required background

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

[Top]


Key concepts

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.

[Top]


Architectural relationships

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

[Top]


API summary

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.

Class diagram for InetProtUtils

Class diagram for InetProtUtils

[Top]


Typical uses

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:

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.