<?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, E-mail

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_d0e48659_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<256> 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->ItemCount());

// Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result 

// variable

singleSearch->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->ItemCount();

multiSearch->Item(item);

for(TInt i=0; i<count; i++)

    {

    result.Set(strSomeText.Mid(item.iStartPos, item.iLength));

    RDebug::Print(_L("Found type %d item:"), item.iItemType);

    RDebug::Print(_L("%S"), &result)

    multiSearch->NextItem(item);

    }

// Deallocate memory

delete multiSearch;

</codeblock> <p><b>Sequence Diagram</b> </p> <fig id="GUID-1FD4B286-A5EE-43B7-BE5C-A22AB47A8E00">

<title>                 Sequence of events for <codeph>CTulAddressStringTokenizer</codeph></title>

<image href="GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C_d0e48752_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>