Creating +an URI

This tutorial describes various methods of creating an URI.

Introduction

The CUri class provides +modifying and non-modifying (parsing and extraction) functionality on URIs. +This allows a number of operations to be performed on the URI such as extraction +of parts, modifying, validation and resolving. The two variants of CUri class +are CUri16 for 16-bit (Unicode) URIs and CUri8 for +8-bit (narrow) URIs.

Procedure

Use CUri8 and UriUtils classes +to create an URI in one of the following methods:

Creating +an URI from parts
Creating +an URI from a file name
Creating +an URI from relative URIs
Creating +an URI from an unicode descriptor

Creating an +URI from parts

Create an URI by adding each component. This is done +by calling CUri8::SetComponentL() repeatedly for each component. CUri8 supports +modification of URI components. It also provides reference to a TUriC8 object +to use the non-modifying functionality that is provided by TUriC8.

The +code below constructs a CUri object from parts such as +scheme, host and user info components.

TUriC8 pUri; +//create a pointer to CUri8 object, pass a reference to a parsed TUriC8 object +CUri8* uri = CUri8::NewL( pUri );

NewL() and NewLC() methods +have overloads that construct an empty URI object.

+// Add components to build a URI +_LIT8( KScheme0, "http" ); +_LIT8( KHost0, "www.mypage.com" ); +_LIT8( KUserInfo0, "user:pass" ); +CUri8* uri = CUri8::NewLC(); +uri->SetComponentL( KScheme0, EUriScheme ); // set the scheme component +uri->SetComponentL( KHost0, EUriHost ); // set the host component +uri->SetComponentL( KUserInfo0, EUriUserinfo ); // set the user info component +const TDesC8& des = uri->Uri().UriDes(); // retrieve the created URI +CleanupStack::PopAndDestroy( uri );

The descriptor des contains +the URI "http://user:pass@www.mypage.com".

Removing a component

CUri8::RemoveComponentL() removes +a specific component from an URI.

The following code removes the scheme +component of the URI. This function removes a component only if it exits.

uri8->RemoveComponentL( EUriScheme ); //remove the scheme component +const TDesC8& des8 = uri8->Uri().UriDes(); //retrieve the URI

des contains +the remaining part of the URI that is user:pass@www.mypage.com, +after removing "http" (the scheme component).

Creating authority +components

Similar to an URI, authority components can be created +from its components. This is done by adding the user information, host and +port by calling CAuthority8::SetComponentL() repeatedly.

Parse +the component that must be added by calling TAuthorityParser8::Parse() and +create an object using CAuthority8::NewL().

TAuthorityParser8 authorityParser; +_LIT8( KAuthority,"www.nokia.com" ); +authorityParser.Parse( KAuthority ); // parse the authority component +CAuthority8* authority = CAuthority8::NewL( authorityParser ); // create an authority object +_LIT8( KUserinfo,"user:info" ); // Add components to the Authority +CleanupStack::PushL( authority ); +authority->SetComponentL( KUserinfo,EAuthorityUserinfo ); // set the userinfo +_LIT8( KHost, "www.nokia.com" ); +authority->SetComponentL( KHost,EAuthorityHost ); // set the host +_LIT8( KPort,"80" ); +authority->SetComponentL( KPort,EAuthorityPort ); // set the port +const TDesC8& authorityDes = authority->Authority().AuthorityDes(); // get the authority component +CleanupStack::PopAndDestroy( authority );

authorityDes descriptor +contains the complete authority component user:info@www.nokia.com:80.

Setting +and escaping the authority component

CAuthority8::SetAndEscapeComponentL() allows +you to escape encode and set the authority component in an URI. This escapes +any unsafe data before setting the component.

CAuthority8* authority = CAuthority8::NewL( authorityParser ); +CleanupStack::PushL( authority ); +authority->SetAndEscapeComponentL( KUserinfo,EAuthorityUserinfo ); //escape encode and set user info component +CleanupStack::PopAndDestroy( authority );

Removing the authority +component

CAuthority8::RemoveComponentL() removes +a component, specified with a TAuthorityComponent component, +from the authority data.

//Remove the user info component from the URI +authority->RemoveComponentL( EAuthorityUserinfo );

Creating an +URI from a file name

To create a file URI object, call CUri8::CreateFileUriL().

The +following code fragment creates the file URI object.

//Set the physical path of the file +LIT( KFullUriName, "D:\\MyFolder\\MyDoc.doc" ); +//create the Uri for the path component +CUri8* pathUri8 = CUri8::CreateFileUriL( KFullUriName,0 );

The +code returns the URI for the specified file path. Provide the full file name +descriptor. For example, D:\\MyFolder\\MyDoc.doc and +specify whether the drive on which the file exists is fixed or external. 0 indicates +a fixed drive, otherwise specify EExtMedia.

If the +file exists on:

a fixed drive, then +the URI takes the form file:///private/<drive-letter>/<filepath>
a removable drive, then +the URI takes the form file:///ext-media/<filepath> or file:///private/ext-media/<filepath> .

If the file is private to the application, then use CUri8::CreatePrivateFileUriL() instead +of CUri8::CreateFileUriL().

Creating +an URI from relative URIs

This section explains how to create URIs +from base and reference URIs.

Resolving

Resolving +is the process of interpreting what the string means, stripping it into some +component parts and then using those to decide on the following:

How to look up something, +interpreting the raw content that was sent back to us.
What we want to look +up for that identifier.
Once we have looked +it up, what protocol is required to acquire it.
Interpreting the raw +content that was sent back to us.

The first one is called resolving. In this context, resolving is +the process of converting a relative URI reference (for example, ../../../resource.txt) +to its absolute form, for example, http://somehost/resource.txt.

You +need to resolve the URI to know what the identifier actually points to.

Creating +an URI by resolving

The following code resolves the reference +URI against the base URI and returns an absolute URI.

Create the base +and reference URIs from its components using SetComponentL(). +Refer to Creating +a URI from parts.

_LIT8( KBase,"http://www.mypage.com/folder1/folder2/index.html" ); +_LIT8( KReference, "../../empdetail.html" ); + +TUriParser8 baseUri; //base URI object +TInt error = baseUri.Parse( KBase ); //parse the base URI + +TUriParser8 refUri; //reference URI object +error = refUri.Parse( KReference ); //parse the reference URI + +CUri8* resolvedUri = NULL; +resolvedUri = CUri8::ResolveL( baseUri, refUri ); //resolve the reference URI against base URI +const TDesC8& des1 = resolvedUri->Uri().UriDes(); //retrieve the resolved URI

The +code returns an absolute URI, "http://www.mypage.com/empdetail.html " +in this case.

Creating an +URI from an unicode descriptor

UriUtils::CreateUriL() creates +a CUri8 object from a Unicode descriptor.

_LIT8( KUri,"http://web.intra/Dev/Sysdoc/devlib.htm" ); +CUri8* uri8= UriUtils::CreateUriL( KUri );

This returns a new CUri8 object. +It returns EUriUtilsParserErrInvalidUri if the descriptor +is an invalid URI.

Create an authority component of URI from a descriptor +by calling UriUtils::CreateAuthorityL().