|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF" xml:lang="en"><title>Creating |
|
13 an URI</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This tutorial describes various methods of creating an URI. </p> |
|
15 <section><title>Introduction</title> <p>The <codeph>CUri</codeph> class provides |
|
16 modifying and non-modifying (parsing and extraction) functionality on URIs. |
|
17 This allows a number of operations to be performed on the URI such as extraction |
|
18 of parts, modifying, validation and resolving. The two variants of <codeph>CUri</codeph> class |
|
19 are <codeph>CUri16</codeph> for 16-bit (Unicode) URIs and <codeph>CUri8</codeph> for |
|
20 8-bit (narrow) URIs. </p> </section> |
|
21 <section><title>Procedure</title> <p>Use <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> and <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita"><apiname>UriUtils</apiname></xref> classes |
|
22 to create an URI in one of the following methods: </p> <ul> |
|
23 <li><p><xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita#GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF/GUID-0CE5258E-7954-4246-BF8D-66A9A3791A87">Creating |
|
24 an URI from parts</xref></p></li> |
|
25 <li><p><xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita#GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF/GUID-E837279E-CF09-4247-96A6-B41EB3CDBF73">Creating |
|
26 an URI from a file name</xref></p></li> |
|
27 <li><p><xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita#GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF/GUID-11F582F5-0C39-4DFE-A3D0-823D0D3E8A79">Creating |
|
28 an URI from relative URIs</xref></p></li> |
|
29 <li><p><xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita#GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF/GUID-3AC094A2-6E3A-46C6-8227-079F394233EE">Creating |
|
30 an URI from an unicode descriptor</xref></p></li> |
|
31 </ul> </section> |
|
32 <section id="GUID-0CE5258E-7954-4246-BF8D-66A9A3791A87"><title>Creating an |
|
33 URI from parts</title><p>Create an URI by adding each component. This is done |
|
34 by calling <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita#GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB/GUID-304702F1-4BE4-37EB-899E-6E338C13CCF4"><apiname>CUri8::SetComponentL()</apiname></xref> repeatedly for each component. <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> supports |
|
35 modification of URI components. It also provides reference to a <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref> object |
|
36 to use the non-modifying functionality that is provided by <xref href="GUID-A81CD022-5AD4-3BD8-B006-B3891C4F4F74.dita"><apiname>TUriC8</apiname></xref>. </p> <p>The |
|
37 code below constructs a <xref href="GUID-9D22BBBA-2DF2-36D2-BD07-5DE56F8541AA.dita"><apiname>CUri</apiname></xref> object from parts such as |
|
38 scheme, host and user info components. </p> <codeblock id="GUID-C40E1243-2D81-556C-919F-BBF34E732F1B" xml:space="preserve">TUriC8 pUri; |
|
39 //create a pointer to CUri8 object, pass a reference to a parsed TUriC8 object |
|
40 CUri8* uri = CUri8::NewL( pUri ); </codeblock> <p> <xref href="GUID-93132FF9-512F-30EC-8AB0-BD3E98F668E6.dita"><apiname>NewL()</apiname></xref> and <xref href="GUID-343E6447-4947-34EE-8641-3CB72930CCF6.dita"><apiname>NewLC()</apiname></xref> methods |
|
41 have overloads that construct an empty URI object. </p> <codeblock id="GUID-3C6F97F5-20FA-55FF-8963-9C2B81800A7D" xml:space="preserve"> |
|
42 // Add components to build a URI |
|
43 _LIT8( KScheme0, "http" ); |
|
44 _LIT8( KHost0, "www.mypage.com" ); |
|
45 _LIT8( KUserInfo0, "user:pass" ); |
|
46 CUri8* uri = CUri8::NewLC(); |
|
47 uri->SetComponentL( KScheme0, EUriScheme ); // set the scheme component |
|
48 uri->SetComponentL( KHost0, EUriHost ); // set the host component |
|
49 uri->SetComponentL( KUserInfo0, EUriUserinfo ); // set the user info component |
|
50 const TDesC8& des = uri->Uri().UriDes(); // retrieve the created URI |
|
51 CleanupStack::PopAndDestroy( uri );</codeblock> <p>The descriptor <codeph>des</codeph> contains |
|
52 the URI "http://user:pass@www.mypage.com". </p> <p><b> Removing a component</b> </p> <p> <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita#GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB/GUID-67A357DE-BE32-3198-8D8D-834D4FC21D93"><apiname>CUri8::RemoveComponentL()</apiname></xref> removes |
|
53 a specific component from an URI. </p> <p>The following code removes the scheme |
|
54 component of the URI. This function removes a component only if it exits. </p> <codeblock id="GUID-E58A81D6-1E32-5DF1-8457-B54DF52DD8C0" xml:space="preserve">uri8->RemoveComponentL( EUriScheme ); //remove the scheme component |
|
55 const TDesC8& des8 = uri8->Uri().UriDes(); //retrieve the URI</codeblock> <p> <codeph>des</codeph> contains |
|
56 the remaining part of the URI that is <codeph>user:pass@www.mypage.com</codeph>, |
|
57 after removing "http" (the scheme component). </p> <p><b>Creating authority |
|
58 components</b> </p> <p>Similar to an URI, authority components can be created |
|
59 from its components. This is done by adding the user information, host and |
|
60 port by calling <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita#GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA/GUID-16A86324-075F-31DF-811C-5B6D66D013BD"><apiname>CAuthority8::SetComponentL()</apiname></xref> repeatedly. </p> <p>Parse |
|
61 the component that must be added by calling <xref href="GUID-985C12CB-9230-3A35-9F5F-E455D4C23EBB.dita#GUID-985C12CB-9230-3A35-9F5F-E455D4C23EBB/GUID-7CCA2647-E8D0-312B-83BE-BE857FB61D0C"><apiname>TAuthorityParser8::Parse()</apiname></xref> and |
|
62 create an object using <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita#GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA/GUID-8EB92707-4B5D-3BED-98A6-F6AA6BE3E0DE"><apiname>CAuthority8::NewL()</apiname></xref>. </p> <codeblock id="GUID-6F61ABB0-31A6-59AC-AE44-1745786A5960" xml:space="preserve">TAuthorityParser8 authorityParser; |
|
63 _LIT8( KAuthority,"www.nokia.com" ); |
|
64 authorityParser.Parse( KAuthority ); // parse the authority component |
|
65 CAuthority8* authority = CAuthority8::NewL( authorityParser ); // create an authority object |
|
66 _LIT8( KUserinfo,"user:info" ); // Add components to the Authority |
|
67 CleanupStack::PushL( authority ); |
|
68 authority->SetComponentL( KUserinfo,EAuthorityUserinfo ); // set the userinfo |
|
69 _LIT8( KHost, "www.nokia.com" ); |
|
70 authority->SetComponentL( KHost,EAuthorityHost ); // set the host |
|
71 _LIT8( KPort,"80" ); |
|
72 authority->SetComponentL( KPort,EAuthorityPort ); // set the port |
|
73 const TDesC8& authorityDes = authority->Authority().AuthorityDes(); // get the authority component |
|
74 CleanupStack::PopAndDestroy( authority );</codeblock> <p> <codeph>authorityDes</codeph> descriptor |
|
75 contains the complete authority component <codeph>user:info@www.nokia.com:80</codeph>. </p> <p><b>Setting |
|
76 and escaping the authority component</b> </p> <p> <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita#GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA/GUID-52E9DED4-C414-34A6-B3FA-66DB7EF39880"><apiname>CAuthority8::SetAndEscapeComponentL()</apiname></xref> allows |
|
77 you to escape encode and set the authority component in an URI. This escapes |
|
78 any unsafe data before setting the component. </p> <codeblock id="GUID-0F25673B-BB07-5D1E-9489-4B6C1ADAA227" xml:space="preserve">CAuthority8* authority = CAuthority8::NewL( authorityParser ); |
|
79 CleanupStack::PushL( authority ); |
|
80 authority->SetAndEscapeComponentL( KUserinfo,EAuthorityUserinfo ); //escape encode and set user info component |
|
81 CleanupStack::PopAndDestroy( authority );</codeblock><p><b>Removing the authority |
|
82 component </b> </p> <p> <xref href="GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA.dita#GUID-3B5EC759-81D3-3A5E-B437-7AA3BD3124BA/GUID-CEF5F6D0-F0ED-3CB6-99D3-F57EC7F6E052"><apiname>CAuthority8::RemoveComponentL()</apiname></xref> removes |
|
83 a component, specified with a <xref href="GUID-36A87623-F89F-38DE-B4DE-4C626C663E6A.dita"><apiname>TAuthorityComponent</apiname></xref> component, |
|
84 from the authority data. </p> <codeblock id="GUID-C641C205-37CE-5129-803E-F87388A7094C" xml:space="preserve">//Remove the user info component from the URI |
|
85 authority->RemoveComponentL( EAuthorityUserinfo );</codeblock></section> |
|
86 <section id="GUID-E837279E-CF09-4247-96A6-B41EB3CDBF73"><title>Creating an |
|
87 URI from a file name</title><p>To create a file URI object, call <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita#GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB/GUID-8C97EB2A-C7D0-382C-ACA1-1599A180361B"><apiname>CUri8::CreateFileUriL()</apiname></xref>. </p> <p>The |
|
88 following code fragment creates the file URI object. </p> <codeblock id="GUID-5BC27144-0C5D-59E8-9B10-DF5030395352" xml:space="preserve">//Set the physical path of the file |
|
89 LIT( KFullUriName, "D:\\MyFolder\\MyDoc.doc" ); |
|
90 //create the Uri for the path component |
|
91 CUri8* pathUri8 = CUri8::CreateFileUriL( KFullUriName,0 );</codeblock> <p>The |
|
92 code returns the URI for the specified file path. Provide the full file name |
|
93 descriptor. For example, <filepath>D:\\MyFolder\\MyDoc.doc</filepath> and |
|
94 specify whether the drive on which the file exists is fixed or external. <codeph>0</codeph> indicates |
|
95 a fixed drive, otherwise specify <codeph>EExtMedia</codeph>. </p> <p>If the |
|
96 file exists on: </p> <ol id="GUID-3EF4AFE9-5292-520C-B316-3E3F2BEA29E4"> |
|
97 <li id="GUID-76401E43-AEE9-54CA-B053-9C4F114697D1"><p>a fixed drive, then |
|
98 the URI takes the form <i>file:///private/<drive-letter>/<filepath></i> </p> </li> |
|
99 <li id="GUID-5569AD56-2FFA-501F-A54C-DDDE13A63AD4"><p>a removable drive, then |
|
100 the URI takes the form <i>file:///ext-media/<filepath> or file:///private/ext-media/<filepath> </i>. </p> </li> |
|
101 </ol> <p>If the file is private to the application, then use <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita#GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB/GUID-48B3DF31-578E-34B5-83E4-0D3665D98E98"><apiname>CUri8::CreatePrivateFileUriL()</apiname></xref> instead |
|
102 of <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita#GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB/GUID-8C97EB2A-C7D0-382C-ACA1-1599A180361B"><apiname>CUri8::CreateFileUriL()</apiname></xref>. </p></section> |
|
103 <section id="GUID-11F582F5-0C39-4DFE-A3D0-823D0D3E8A79"><title>Creating |
|
104 an URI from relative URIs</title><p>This section explains how to create URIs |
|
105 from base and reference URIs. </p> <p><b>Resolving </b> </p> <p>Resolving |
|
106 is the process of interpreting what the string means, stripping it into some |
|
107 component parts and then using those to decide on the following: </p> <ol id="GUID-91EAB7B6-9993-5657-9A79-F5A53DC62558"> |
|
108 <li id="GUID-B7E1B815-23C0-58B2-873B-8AF79EBC9FC8"><p>How to look up something, |
|
109 interpreting the raw content that was sent back to us. </p> </li> |
|
110 <li id="GUID-FD77DB94-226B-5BA4-960F-0D2D06C45548"><p>What we want to look |
|
111 up for that identifier. </p> </li> |
|
112 <li id="GUID-7BFB4C7A-44D1-5A53-A2BA-33C6E94AC30A"><p>Once we have looked |
|
113 it up, what protocol is required to acquire it. </p> </li> |
|
114 <li id="GUID-8A76183B-DA2F-5520-94B4-5BE3A30400A1"><p>Interpreting the raw |
|
115 content that was sent back to us. </p> </li> |
|
116 </ol> <p>The first one is called resolving. In this context, resolving is |
|
117 the process of converting a relative URI reference (for example, <filepath>../../../resource.txt</filepath>) |
|
118 to its absolute form, for example, <filepath>http://somehost/resource.txt</filepath>. </p> <p>You |
|
119 need to resolve the URI to know what the identifier actually points to. </p> <p><b>Creating |
|
120 an URI by resolving</b> </p> <p>The following code resolves the reference |
|
121 URI against the base URI and returns an absolute URI. </p> <p>Create the base |
|
122 and reference URIs from its components using <xref href="GUID-D723C462-53F1-35F8-B70C-7432049ECE30.dita"><apiname>SetComponentL()</apiname></xref>. |
|
123 Refer to <xref href="GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF.dita#GUID-4D32A29F-6573-5233-8982-BDEEDDB4F0FF/GUID-6FCAF213-79C5-5780-965F-45E5817E7242">Creating |
|
124 a URI from parts</xref>. </p> <codeblock id="GUID-75783DAE-B2D4-5010-A013-A1BA751CEC0F" xml:space="preserve">_LIT8( KBase,"http://www.mypage.com/folder1/folder2/index.html" ); |
|
125 _LIT8( KReference, "../../empdetail.html" ); |
|
126 |
|
127 TUriParser8 baseUri; //base URI object |
|
128 TInt error = baseUri.Parse( KBase ); //parse the base URI |
|
129 |
|
130 TUriParser8 refUri; //reference URI object |
|
131 error = refUri.Parse( KReference ); //parse the reference URI |
|
132 |
|
133 CUri8* resolvedUri = NULL; |
|
134 resolvedUri = CUri8::ResolveL( baseUri, refUri ); //resolve the reference URI against base URI |
|
135 const TDesC8& des1 = resolvedUri->Uri().UriDes(); //retrieve the resolved URI</codeblock> <p>The |
|
136 code returns an absolute URI, "<codeph>http://www.mypage.com/empdetail.html</codeph> " |
|
137 in this case. </p> </section> |
|
138 <section id="GUID-3AC094A2-6E3A-46C6-8227-079F394233EE"><title>Creating an |
|
139 URI from an unicode descriptor</title><p> <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita#GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA/GUID-8A9C278B-8DF6-3C5A-ADCB-8434B6DB6DFF"><apiname>UriUtils::CreateUriL()</apiname></xref> creates |
|
140 a <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> object from a Unicode descriptor. </p> <codeblock id="GUID-A990A14C-7C4A-5277-92F4-38C8E0F18A9C" xml:space="preserve">_LIT8( KUri,"http://web.intra/Dev/Sysdoc/devlib.htm" ); |
|
141 CUri8* uri8= UriUtils::CreateUriL( KUri );</codeblock> <p>This returns a new <xref href="GUID-E6F8C94C-C74C-329B-BB11-E06F0E83A4BB.dita"><apiname>CUri8</apiname></xref> object. |
|
142 It returns <codeph>EUriUtilsParserErrInvalidUri</codeph> if the descriptor |
|
143 is an invalid URI. </p> <p>Create an authority component of URI from a descriptor |
|
144 by calling <xref href="GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA.dita#GUID-265F8D6B-4B88-342A-BD7B-5934CC9437DA/GUID-2AEF4C06-11E2-3A9C-9F05-904488065D02"><apiname>UriUtils::CreateAuthorityL()</apiname></xref>. </p> </section> |
|
145 </conbody><related-links> |
|
146 <link href="GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita"><linktext>HTTP Utilities |
|
147 Library Overview</linktext></link> |
|
148 <link href="GUID-A8F13E5A-56F2-5C72-AF81-5AC062B94C6C.dita"><linktext>Using URI |
|
149 utilities</linktext></link> |
|
150 </related-links></concept> |