<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978" xml:lang="en"><title>Address
string tokenizer overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-3380A468-D7C1-478B-81F7-C7B25CA2AF87"><title>Purpose</title> <p>The
Address String Tokenizer offers methods for parsing phone numbers, email addresses,
URL and URI addresses from given text. It provides an interface for applications
that, for example, want to create/use their own GUI for displaying found items. </p> </section>
<section id="GUID-0A0412D0-A818-42C3-8288-D857FF3FB9AC"><title>Architectural
Relationships</title> <p>All functionality is implemented in the <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer</apiname></xref> class.
The interface can be accessed through the <codeph>tuladdressstringtokenizer.h </codeph> file.
The binaries are linked to the <codeph>etul.lib</codeph> (Text Utilities -
part of Egul component) library. </p> <fig id="GUID-831D95A9-EDD6-5351-83CD-F9246B88E821">
<title>              Subsystem dependencies            </title>
<image href="GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e14680_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-B712EDB6-0AAD-4E3F-9694-5EABECD3AA1D"><title>Description</title> <p><b>Usage</b> </p> <p>In
order to use the Address String Tokenizer, the user has to create an instance
of <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer</apiname></xref> by
using the factory method <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>CTulAddressStringTokenizer::NewL()</apiname></xref>. </p> <p>For
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&amp;</codeph> and <xref href="GUID-D35F2DD5-09A3-366C-8384-46FEB6B7DB18.dita"><apiname>TTokenizerSearchCase</apiname></xref> which is
defined in <codeph>tuladdressstringtokenizer.h</codeph>. </p> <p>The first
parameter defines the text to be searched from. </p> <p>The second parameter
tells what exactly is being looked for. It is an enum which describes the
type of text being searched for. The types available are phone number, email
address, fixed start URL or generic URI. </p> <p>The passed text is parsed
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
array containing all the found items. </p> <p>The interface also offers helper
functions for handling the item array by itself. </p> <p>For more information
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
search for items from a text string: </p> <codeblock id="GUID-2B5E70DF-6757-5803-B7BA-052EA4932EEF" xml:space="preserve">// Some text
TBufC&lt;256&gt; strSomeText(_L("Mail to me@someplace.com or call 040 1234567. 
                        You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra."));

// SFoundItem instance
CTulAddressStringTokenizer::SFoundItem item;

// Create an instance of CTulAddressStringTokenizer and search for URLs.
CTulAddressStringTokenizer* singleSearch = CTulAddressStringTokenizer::NewL
                                           (strSomeText, CTulAddressStringTokenizer::EFindItemSearchScheme);

// Get count of found items
TInt count(singleSearch-&gt;ItemCount());

// Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result 
// variable
singleSearch-&gt;Item(item);
TPtrC16 result(strSomeText.Mid(item.iStartPos, item.iLength));

// Deallocate memory
delete singleSearch;

// Look for all possible things (cases work as binary mask)
CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL
                                          (strSomeText, (CTulAddressStringTokenizer:: TTokenizerSearchCase)
           (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin |           
            CTulAddressStringTokenizer::EFindItemSearchURLBin | 
            CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | 
            CTulAddressStringTokenizer::EFindItemSearchScheme));

// Debug print all items and their type
count = multiSearch-&gt;ItemCount();
multiSearch-&gt;Item(item);

for(TInt i=0; i&lt;count; i++)
    {
    result.Set(strSomeText.Mid(item.iStartPos, item.iLength));
    RDebug::Print(_L("Found type %d item:"), item.iItemType);
    RDebug::Print(_L("%S"), &amp;result)
    multiSearch-&gt;NextItem(item);
    }

// Deallocate memory
delete multiSearch;
</codeblock> <p><b>Sequence Diagram</b> </p> <fig id="GUID-8BF3A74A-9E14-57C4-A0E5-105A0230BFA1">
<title>                 Sequence of events for CTulAddressStringTokenizer</title>
<image href="GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB_d0e14771_href.png" placement="inline"/>
</fig> </section>
</conbody></concept>