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:

1. a fixed drive, then the URI takes the form file:///private/<drive-letter>/<filepath>

2. 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:

1. How to look up something, interpreting the raw content that was sent back to us.

2. What we want to look up for that identifier.

3. Once we have looked it up, what protocol is required to acquire it.

4. 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().