HTTP -Utilities Library Overview

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.

-HTTP Utilities -Library Concepts -HTTP Utilities -Library Tutorials -HTTP Utilities -Library Example + + + + + +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.

+HTTP Utilities +Library Concepts +HTTP Utilities +Library Tutorials +HTTP Utilities +Library Example

\ No newline at end of file