|
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-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978" xml:lang="en"><title>Address |
|
13 string tokenizer overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-3380A468-D7C1-478B-81F7-C7B25CA2AF87"><title>Purpose</title> <p>The |
|
15 Address String Tokenizer offers methods for parsing phone numbers, E-mail |
|
16 addresses, URL and URI addresses from given text. It provides an interface |
|
17 for applications that, for example, want to create/use their own GUI for displaying |
|
18 found items. </p> </section> |
|
19 <section id="GUID-0A0412D0-A818-42C3-8288-D857FF3FB9AC"><title>Architectural |
|
20 Relationships</title> <p>All functionality is implemented in the <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer</apiname></xref> class. |
|
21 The interface can be accessed through the <codeph>tuladdressstringtokenizer.h </codeph> file. |
|
22 The binaries are linked to the <codeph>etul.lib</codeph> (Text Utilities - |
|
23 part of Egul component) library. </p> <fig id="GUID-831D95A9-EDD6-5351-83CD-F9246B88E821"> |
|
24 <title> Subsystem dependencies </title> |
|
25 <image href="GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e48659_href.png" placement="inline"/> |
|
26 </fig> </section> |
|
27 <section id="GUID-B712EDB6-0AAD-4E3F-9694-5EABECD3AA1D"><title>Description</title> <p><b>Usage</b> </p> <p>In |
|
28 order to use the Address String Tokenizer, the user has to create an instance |
|
29 of <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer</apiname></xref> by |
|
30 using the factory method <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer::NewL()</apiname></xref>. </p> <p>For |
|
31 example: </p> <codeblock id="GUID-59957EA3-0C1D-5A35-87A0-8DCB0D01D840" xml:space="preserve">CTulAddressStringTokenizer* addressStringTokenizer = CTulAddressStringTokenizer::NewL(text, searchCase);</codeblock> <p>The method takes two parameters of type <codeph>TDesC&</codeph> and <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>TTokenizerSearchCase</apiname></xref> which is |
|
32 defined in <codeph>tuladdressstringtokenizer.h</codeph>. </p> <p>The first |
|
33 parameter defines the text to be searched from. </p> <p>The second parameter |
|
34 tells what exactly is being looked for. It is an enum which describes the |
|
35 type of text being searched for. The types available are phone number, email |
|
36 address, fixed start URL or generic URI. </p> <p>The passed text is parsed |
|
37 in construction, and found items can be fetched using the <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>ItemArray()</apiname></xref> method. <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>ItemArray()</apiname></xref> returns a constant |
|
38 array containing all the found items. </p> <p>The interface also offers helper |
|
39 functions for handling the item array by itself. </p> <p>For more information |
|
40 on individual methods, please see the reference API for <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer</apiname></xref>. </p> <p><b>Example</b> </p> <p>This sample code explains a few simple use cases that |
|
41 search for items from a text string: </p> <codeblock id="GUID-2B5E70DF-6757-5803-B7BA-052EA4932EEF" xml:space="preserve">// Some text |
|
42 TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. |
|
43 You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra.")); |
|
44 |
|
45 // SFoundItem instance |
|
46 CTulAddressStringTokenizer::SFoundItem item; |
|
47 |
|
48 // Create an instance of CTulAddressStringTokenizer and search for URLs. |
|
49 CTulAddressStringTokenizer* singleSearch = CTulAddressStringTokenizer::NewL |
|
50 (strSomeText, CTulAddressStringTokenizer::EFindItemSearchScheme); |
|
51 |
|
52 // Get count of found items |
|
53 TInt count(singleSearch->ItemCount()); |
|
54 |
|
55 // Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result |
|
56 // variable |
|
57 singleSearch->Item(item); |
|
58 TPtrC16 result(strSomeText.Mid(item.iStartPos, item.iLength)); |
|
59 |
|
60 // Deallocate memory |
|
61 delete singleSearch; |
|
62 |
|
63 // Look for all possible things (cases work as binary mask) |
|
64 CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL |
|
65 (strSomeText, (CTulAddressStringTokenizer::TTokenizerSearchCase) |
|
66 (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin | |
|
67 CTulAddressStringTokenizer::EFindItemSearchURLBin | |
|
68 CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | |
|
69 CTulAddressStringTokenizer::EFindItemSearchScheme)); |
|
70 |
|
71 // Debug print all items and their type |
|
72 count = multiSearch->ItemCount(); |
|
73 multiSearch->Item(item); |
|
74 |
|
75 for(TInt i=0; i<count; i++) |
|
76 { |
|
77 result.Set(strSomeText.Mid(item.iStartPos, item.iLength)); |
|
78 RDebug::Print(_L("Found type %d item:"), item.iItemType); |
|
79 RDebug::Print(_L("%S"), &result) |
|
80 multiSearch->NextItem(item); |
|
81 } |
|
82 |
|
83 // Deallocate memory |
|
84 delete multiSearch; |
|
85 </codeblock> <p><b>Sequence Diagram</b> </p> <fig id="GUID-1FD4B286-A5EE-43B7-BE5C-A22AB47A8E00"> |
|
86 <title> Sequence of events for <codeph>CTulAddressStringTokenizer</codeph></title> |
|
87 <image href="GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C_d0e48752_href.png" placement="inline"/> |
|
88 </fig> </section> |
|
89 </conbody></concept> |