Landmark attributes

A landmark can contain the following attributes:

Landmark attributes

Item ID	This ID is a reference to the landmark in a landmark database. It is locally unique within one database.
Landmark name	The name of the landmark can contain a maximum of 255 characters. The landmark name does not have to be unique in a database.
Position	The WGS84 coordinate for the landmark.
Coverage radius	Coverage radius is set if the landmark is big, for example, a city. It defines the size of the area, which the landmark represents. The coverage area is specified in meters.
Category info	The categories related to the landmark, e.g. restaurant, gas station, grocery store, etc. For more information about categories, see section Landmark categories .
Icon	A reference to an icon in an icon file which can be used to symbolize the landmark in a UI. An icon mask can also be specified from the same icon file.
Description	A textual description of the landmark, for example, “Chinese restaurant. Nice atmosphere and the service is superb”. The description has a maximum length of 4095 characters.
Position fields	Generic position fields as defined by Location Acquisition API . A position field can, for instance, be the street address of the landmark or the name of the city where the landmark is found. Landmarks API only supports text position fields. If the client wants to store a non-text field, the value must first be converted to a textual representation. A landmark can contain any number of position fields.
Place ID	The unique id specified by the client for any location.
TimeStamp	The time associated with a landmark.The format that is used for timestamp is YYYYMMDD:HHMMSS.MMMMMM wherein the date field is mandatory.Validations for this field are the same as in TTime object.

Local and global landmark categories

Landmark categories may be local or global. Local categories are defined by the user. They are stored in a database and cannot be reused by multiple databases unless the user creates the same category in several databases.

Global categories are predefined in the terminal and may be reused in multiple databases and multiple phones and on different platforms. The Global Category ID uniquely specifies a global category, which makes global categories localizable. The names and icons of global categories are predefined in a resource file and the category name is automatically changed in the database when it is open if the terminal language changes since the last usage of the database. Note: The global category name will not be changed to the newly selected language if the user has previously renamed this category.

The predefined global landmark categories are listed in the following table:

Predefined global landmark categories

3000	Accommodation	Hotel, Camping site
6000	Business	Bank, Factory, Office
9000	Communication	Internet Access Point, Public Telephone, Wireless LAN Hot Spot
12000	Educational institute	School, College
15000	Entertainment	Amusement park, Cinema, Concert hall, Night club
18000	Food & Beverage	Fast food, Restaurant, Café, Bar
21000	Geographical area	City, City center, Town
24000	Outdoor activities	Camping site, Fishing place, Hunting, National park, Playground
27000	People	My home, My friend’s home, Father’s summer cottage, Child’s school
30000	Public service	Tourist information office, Government office, Library, Post office, Hospital, Police
33000	Religious places	Church, Mosque
36000	Shopping	Market Place, Pharmacy, Shop, Shopping Center
39000	Sightseeing	Monument, Mountain top, Museum
42000	Sports	Bowling, Golf course, Ice hockey hall, Stadium
45000	Transport	Airport, Bus stop, Harbour, Railway Station, Rest area

Other IDs are reserved for future use. Names are given only for reference purposes, localized names are defined for all languages supported by the platform.

Category attributes

A landmark category contains the following attributes:

Landmark category attributes

Item ID	This ID is a reference to the category in a landmark database. It is locally unique within one database.
Category name	The name of the category can contain a maximum of 124 characters. The category name must be unique in a database. If the client tries to change the name of a category and that name is already occupied by another category, the update fails.
Global category ID	This ID refers to a category in a globally defined category set.
Icon	A reference to an icon in an icon file, which can be used to symbolize the category in a UI. An icon mask can also be specified from the same icon file.

Notations Used

* - 0 or more occurences

1* - 1 or more occurrences

[] - optional contents

‘’ - literals

X*Y - between X & Y occurences ( For Eg : 2*5 - between 2 & 5 occurences )

Grammar Definition

url -> [ protocol ‘://’ ] hostname ‘/?’ location *[ ‘??’ location ]

protocol -> ‘http’ | ‘https’

hostname -> [‘www.’] ‘maps.ovi.com’

location -> locationparams *[ '&' locationparams ]

locationparams -> placeid | latitude | longitude | name | street | housenumber | postalcode | city | state | country | telephone | web | category | description | positionaccuracy | altitude | altitudeaccuracy | speed | heading | timestamp

placeid -> ‘pid =’ placeidvalue

placeidvalue -> 0*255 [ alphanum | escaped ]

alphanum -> alpha | digit

alpha -> lowalpha | upalpha

lowalpha -> ‘a’ | ‘b’ | ‘c’ | ‘d’ | ‘e’ | ‘f’ | ‘g’ | ‘h’ | ‘i’ | ‘j’ | ‘k’ | ‘l’ | ‘m’ | ‘n’ | ‘o’ | ‘p’ | ‘q’ | ‘r’ | ‘s’ | ‘t’ | ‘u’ | ‘v’ | ‘w’ | ‘x’ | ‘y’ | ‘z’

upalpha -> ‘A’ | ‘B’ | ‘C’ | ‘D’ | ‘E’ | ‘F’ | ‘G’ | ‘H’ | ‘I’ | ‘J’ | ‘K’ | ‘L’ | ‘M’ | ‘N’ | ‘O’ | ‘P’ | ‘Q’ | ‘R’ | ‘S’ | ‘T’ | ‘U’ | ‘V’ | ‘W’ | ‘X’ | ‘Y’ | ‘Z’

digit -> ‘0’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’ | ‘7’ | ‘8’ | ‘9’

escaped -> ‘%’ hex hex

hex -> digit | ‘a’ | ‘b’ | ‘c’ | ‘d’ | ‘e’ | ‘f’ | ‘A’ | ‘B’ | ‘C’ | ‘D’ | ‘E’ | ‘F’

latitude -> ‘la =’ latitudevalue

latitudevalue -> [sign] 1*2 digit [ ‘.’0 *6 digit ]

sign -> ‘+’ | ‘-’

longitude -> ‘lo =’ longitudevalue

longitudevalue -> [sign] 1*3 digit [ ‘.’0 *6 digit ]

name -> ‘n =’ namevalue

namevalue -> 0*255 ( alphanum | escaped )

street -> ‘s =’ streetvalue

streetvalue -> 0*255 ( alphanum | escaped )

housenumber -> ‘sn =’ housenumbervalue

housenumbervalue -> 0*255 ( alphanum | escaped )

postalcode -> ‘pz =’ postalcodevalue

postalcodevalue -> 0*255 ( alphanum | escaped )

city -> ‘c =’ cityvalue

cityvalue -> 0*255 ( alphanum | escaped )

state -> ‘sp =’ statevalue

statevalue -> 0*255 ( alphanum | escaped )

country -> ‘cr =’ countryvalue

countryvalue -> 0*255 ( alphanum | escaped )

telephone -> ‘t =’ telephonevalue

telephonevalue -> 0*255 ( alphanum | escaped )

web -> ‘w =’ webvalue

webvalue ->0 *255 ( alphanum | escaped )

category -> ‘cat =’ categoryvalue

categoryvalue -> 0*124 ( alphanum | escaped )

description -> ‘d =’ descriptionvalue

descriptionvalue -> 0*4095 ( alphanum | escaped )

positionaccuracy -> ‘pa =’ positionaccuracyvalue

positionaccuracyvalue -> 1* digit [ ‘.’ 0*2digit ]

altitude -> ‘a=’ altitudevalue

altitudevalue -> [sign] 1* digit [ ‘.’ 0*2 digit ]

altitudeaccuracy -> ‘aa =’ altitudeaccuracyvalue

altitudeaccuracyvalue -> 1* digit [ ‘.’0 *2 digit ]

speed -> ‘v =’ speedvalue

speedvalue -> 1* digit [ ‘.’0 *2 digit ]

heading -> ‘h =’ headingvalue

headingvalue -> 1* digit [ ‘.’0 *2 digit ]

timestamp -> ‘ts =’ timestampvalue

timestampvalue -> full-date ':' [ full-time ]

full-date -> date-fullyear date-month date-mday

full-time -> time-hour time-minute time-second ['.'time-microseconds]

time-microseconds -> 0*6digit

time-second -> 2digit

time-minute -> 2digit

time-hour -> 2digit

date-mday -> 2digit

date-month -> 2digit

date-fullyear -> 4digit

Restrictions

locationparams	Latitude & longitude params are mandatory.Except the category param ( cat ),if there is repetition of any other params then only the value of the first occurrence is considered.The category param is allowed to be repeated in order to support multiple categories to be associated with a single landmark.
latitudevalue	Value ranges between -90 and +90,where negative values indicate southern hemisphere & positive values indicate northern hemisphere.The decimal number is rounded upto 6 decimal digits.
longitudevalue	Value ranges between -180 and +180,where negative values indicate western hemisphere & positive values indicate eastern hemisphere.The decimal number is rounded upto 6 decimal digits.
escaped	Only special characters whose Ascii value ( provided in hex ) ranges between these are to be escaped : 20 – 2F , 3A – 40 , 5B – 60 , 7B – 7E . Refer References section for ascii table
positionaccuracyvalue	Max value is that of max value of TReal32 .The metric considered here is metres.The decimal number is rounded upto 2 decimal digits.
altitudevalue	Max value is that of max value of TReal32 .The metric considered here is metres.The decimal number is rounded upto 2 decimal digits.
altitudeaccuracyvalue	Max value is that of max value of TReal32 The metric considered here is metres.The decimal number is rounded upto 2 decimal digits.
speedvalue	Max value is that of max value of TReal32 .The metric considered here is metres/second.The decimal number is rounded upto 2 decimal digits.
headingvalue	Max value is that of max value of TReal32 .The metric considered here is degrees.The decimal number is rounded upto 2 decimal digits.
timestampvalue	The full date is mandatory for this field to be encoded/parsed whereas if the full time is not specified then the default value assumed for time will be 0.

Example URL

Sample URL containing all the location information and conforming to the grammar as defined above.

"http://www.maps.ovi.com/?la=23.134&lo=120.22&pid=12&n=Placemark&s=HighStreet&sn=1234&pz=123457&c=Bangalore&sp=Karnataka&cr=India&t=9812434125&w=www.weburl.com&cat=MyLandmarks&cat=MyFavouritePlaces&d=Placemark%20from%20Bangalore&pa=12.22&a=43215&v=0&h=0&ts=20090304:121209.123456"

Database access

Landmarks are stored in databases. A client accesses landmark databases through the CPosLandmarkDatabase class. Each instance of CPosLandmarkDatabase is a handle to exactly one landmark database. All operations upon a landmark database are performed through instances of CPosLandmarkDatabase .

CPosLandmark represents the content of a landmark, for example the landmark name and landmark position. This class is used in CPosLandmarkDatabase methods to let the client read or edit a landmark in the database.

A landmark stored in a database is referenced by an ID ( TPosLmItemId ), which is unique within the database. To access a landmark through CPosLandmarkDatabase, the client must specify the ID of the landmark.

It is common that a client needs to retrieve a set of landmarks, for instance when listing the content of a landmark database. In Landmarks API, a landmark set is accessed by using an iterator object. CPosLmItemIterator lets the client retrieve the IDs of the iterated landmarks. The client can iterate all the landmarks in a database by retrieving a CPosLmItemIterator instance from CPosLandmarkDatabase .

Clients may require retrieving landmarks in a certain sort order. In Landmarks API, the client specifies sort preference by using a TPosLmSortPref object.

If a client is not interested in full landmark information, it can perform a partial read. For instance, the client may only be interested in the name of the landmark. By using a CPosLmPartialReadParameters object, the client can specify which landmark information is of interest.

• CPosLandmark
• CPosLandmarkDatabase
• CPosLmItemIterator
• CPosLmPartialReadParameters
• TPosLmItemId
• TPosLmSortPref

Category management

A landmark database can contain landmark categories. To access categories in the database, the client must create a CPosLmCategoryManager object connected to the database. Through this object, the client can retrieve information about the categories in the database or edit the category content.

CPosLandmarkCategory represents information about a landmark category. It is used in the CPosLmCategoryManager interface to pass category information from/to the client.

A landmark category stored in a database is referenced by an ID ( TPosLmItemId ), which is unique within the database. To refer to a landmark category, the client specifies the ID of the category. Note: The same type, TPosLmItemId , is used to refer to landmarks and categories. It is possible that a landmark and a category have the same ID.

Categories can be iterated, just like landmarks. CPosLmItemIterator is used for iterating both landmark and category sets. Note: The iterator is never used to iterate a mixed set of landmarks and categories.

• CPosLandmarkCategory
• CPosLmCategoryManager
• CPosLmItemIterator
• TPosLmItemId

Database events

A client can listen to events from landmark databases. To listen to the next event, the client calls CPosLandmarkDatabase::NotifyDatabaseEvent() . The client passes a TRequestStatus , which will be completed when an event is detected. When an event has been retrieved, the client must renew the NotifyDatabaseEvent() request to listen to further events.

• CPosLandmarkDatabase::NotifyDatabaseEvent()
• NotifyDatabaseEvent()
• TRequestStatus

Exchange operations

A client can exchange landmark data with another party by using the import and export functionality. If a client has received a file or buffer containing landmark data and the client is connected to a landmark database, the client can use Landmarks API to import landmarks to the landmark database. To import landmarks, the client has to create an instance of the CPosLandmarkParser class.

The client can also use Landmarks API to export landmarks from the landmark database. This will result in a file or buffer containing the landmark data. To export landmarks, the client has to create an instance of the CPosLandmarkEncoder class.

The exchange of landmarks is also supported via an URL.The client can encode a landmark object into an URL containing all the location inforamtion.To encode a landmark to an URL ,the client has to create an instance of the CPosLandmarkEncoder class.

Also the client can parse a given URL to decode the location information present in the URL and create a landmark object.To parse an URL ,the client has to create an instance of the CPosLandmarkParser class.

• CPosLandmarkEncoder
• CPosLandmarkParser

Incremental operations

Some operations in Landmarks API can potentially take a long time. These operations can therefore be run incrementally. The client retrieves a CPosLmOperation object, which can either be run incrementally or all at once.

If the operation is run incrementally, the client can read the operation progress between incremental steps.

• CPosLmOperation

Serialization support

A client can pack a landmark or a landmark category object into a buffer for further serialization. This can be used e.g. for sending data over process boundaries. On the receiving side packed objects can be unpacked from buffer. The PosLandmarkSerialization class contains static methods PackL() and UnpackL() for packing and unpacking CPosLandmark instances. PosLmCategorySerialization class contains appropriate methods for packing and unpacking CPosLandmarkCategory instances.

• CPosLandmark
• CPosLandmarkCategory
• PackL()
• PosLandmarkSerialization
• PosLmCategorySerialization
• UnpackL()

Database URI

CPosLandmarkDatabase contains a method OpenL() , which takes a database URI as input. The URI consists of a scheme and the database location, i.e. <scheme>://<location> . If the scheme is left out, it is understood that the database is local on the terminal and is accessed through the file system. The URI c:landmarks.LDB is therefore the same thing as file://c:landmarks.ldb .

The location part of a landmark database URI for a database residing in the terminal is specified by a drive letter, a database name and the LDB extension. The format is <drive>:<database name>.ldb , e.g. c:landmarks.ldb . Note: A path cannot be specified. If the URI does not specify the drive letter, for example landmarks.ldb , the default landmark database drive will be assumed.

CPosLandmarkDatabase provides also method DatabaseUriLC() , which retrieves the URI of the open database.

• <scheme>://<location>
• CPosLandmarkDatabase
• DatabaseUriLC()
• OpenL()

Compacting database

When modifying a landmark database, the database size increases. Some of this memory is not really used. The client should therefore supervise the database usage using the CPosLandmarkDatabase::SizeL() method and compact the database if there is too much unused space. CPosLandmarkDatabase::CompactL() is used to perform compacting and it can be run incrementally.

Compaction is done internally in Landmarks as fallback in case the client does not do it. This will lock the database and clients will not be able to access the database until the compaction is complete. This is unexpected behavior from the user’s point of view and it is therefore recommended that the client performs the compaction itself.

It is recommended to perform compaction when the usage level drops below 70%.

• CPosLandmarkDatabase::CompactL()
• CPosLandmarkDatabase::SizeL()

Releasing resources

The Landmarks subsystem uses ECom plug-ins that provide the implementation for accessing landmark databases. ECom allocates resources that are not released when the plug-in is unloaded. These must be explicitly released by the client at shutdown. This is done by calling the global method ReleaseLandmarkResources() , which has the same effect as REComSession::FinalClose() .

The most common way to release landmark resources is to call ReleaseLandmarkResources() last in the client’s destructor.

• REComSession::FinalClose()

             
              // Open a handle to the default landmark database.
              

              CPosLandmarkDatabase* db = CPosLandmarkDatabase::OpenL();
              

              CleanupStack::PushL( db );
              

              

              // Perform initialization. 
              

              // If initialization is not needed, this method will not do anything.
              

              ExecuteAndDeleteLD( db->InitializeL() );
              

              

              // Create an iterator for iterating the landmarks in the database
              

              CPosLmItemIterator* iter = db->LandmarkIteratorL();
              

              CleanupStack::PushL( iter );
              

              

              // Read each landmark in the database and do something.
              

              TPosLmItemId lmID = KPosLmNullItemId;
              

              while ( ( lmID = iter->NextL() ) != KPosLmNullItemId )
              

                  {
              

                  CPosLandmark* lm = db->ReadLandmarkLC( lmID );
              

                  // Do something with the landmark information
              

                  CleanupStack::PopAndDestroy( lm );
              

                  }
              

              // Close the iterator and the database handle.
              

              CleanupStack::PopAndDestroy( iter );
              

              CleanupStack::PopAndDestroy( db );
             
            

             
              void RenameLandmarkL( 
              

                  CPosLandmarkDatabase& aDatabase,
              

                  TPosLmItemId aLandmarkId,
              

                  const TDesC& aNewName )
              

              {
              

              // Read the landmark from the database. 
              

              CPosLandmark* lm = aDatabase.ReadLandmarkLC( aLandmarkId );
              

              

              // Set the new name and update the database
              

              lm->SetLandmarkNameL( aNewName );
              

              aDatabase.UpdateLandmarkL( *lm );
              

              

              CleanupStack::PopAndDestroy( lm );
              

              }
             
            

             
              _LIT( KName, "My Thai" );
              

              _LIT( KDescription, "Best Thai restaurant ever. Spicy food." );
              

              

              TLocality pos;
              

              pos.SetCoordinate( 61.1120, 23.4231 );
              

              

              // Create the landmark object and set available information.
              

              CPosLandmark* lm = CPosLandmark::NewLC();
              

              lm->SetLandmarkNameL( KName );
              

              lm->SetLandmarkDescriptionL( KDescription );
              

              lm->SetPositionL( pos );
              

              

              // Add the landmark to the database.
              

              aDatabase->AddLandmarkL(*lm);
              

              

              CleanupStack::PopAndDestroy(lm);
             
            

Reading partial landmarks

Landmark data could be spread among different tables in the landmark database. When landmark is read from database, all those tables need to be accessed. However, in many cases when many landmarks are read (e.g. for landmark list) applications need only partial information for every landmark. In this case amount of tables accessed and data transferred during reading can be reduced (thus improving performance) by using "partial read" mechanism of Landmarks API. Following diagram shows basic steps of partial read.

The following example shows how the client can efficiently read just the names of all the landmarks using partial read. aDatabase is an open CPosLandmarkDatabase handle. For simplicity the incremental operation is executed in one batch in this example.

              
               CArrayPtr<CPosLandmark>* ReadLandmarkNamesOnlyLC( CPosLandmarkDatabase& aDatabase )
               

               {
               

               // Retrieve IDs for all landmarks in the database.
               

               RArray<TPosLmItemId> landmarkIds;
               

               CleanupClosePushL( landmarkIds );
               

               CPosLmItemIterator* iter = aDatabase->LandmarkIteratorL();
               

               CleanupStack::PushL( iter );
               

               iter->GetItemIdsL( landmarkIds, 0, iter->NumOfItemsL() );
               

               CleanupStack::PopAndDestroy(iter);
               

               

               // Set partial parameters so that only the landmark name will be retrieved.
               

               CPosLmPartialReadParameters* part = CPosLmPartialReadParameters::NewLC();
               

               part->SetRequestedAttributes( CPosLandmark::ELandmarkName );
               

               aDatabase->SetPartialReadParametersL( *part );
               

               CleanupStack::PopAndDestroy( part );
               

               

               // Start collecting the partial landmark data. Note that
               

               // this will be quicker than reading full landmarks.
               

               CPosLmOperation* op = aDatabase->PreparePartialLandmarksL( landmarkIds );
               

               CleanupStack::PushL( op );
               

               op->ExecuteL();
               

               

               // The landmark objects can be retrieved from the operation object. These
               

               // landmark objects now contain only the names of the landmarks so
               

               // the heap is used efficiently.
               

               CArrayPtr<CPosLandmark>* lmData = aDatabase->TakePreparedPartialLandmarksL( op );
               

               CleanupStack::PopAndDestroy(op);
               

               CleanupStack::PopAndDestroy( &landmarkIds );
               

               

               CleanupStack::PushL( lmData ); // there is a slot for it freed by previous Pop
               

               return lmData;
               

               }
              
             

• CPosLandmarkDatabase
• aDatabase

             
              void ReadAllCategoriesInDatabase( CPosLandmarkDatabase& aDb )
              

              {
              

              // Create the category manager
              

              CPosLmCategoryManager* categoryManager = CPosLmCategoryManager::NewL( aDb );
              

              CleanupStack::PushL( categoryManager );
              

              

              // Create an iterator for iterating the landmarks in the database
              

              CPosLmItemIterator* iter = categoryManager->CategoryIteratorL();
              

              CleanupStack::PushL( iter );
              

              

              // Read each category in the database and do something.
              

              TPosLmItemId catID;
              

              while ( ( catID = iter->NextL() ) != KPosLmNullItemId )
              

                  {
              

                  CPosLandmarkCategory* cat = categoryManager->ReadCategoryLC( catID );
              

              

                  // do something with the category information
              

                  TPtrC catName;
              

                  cat->GetCategoryName( catName );
              

              

                  // if any changes made, following code saves them to database
              

                  // categoryManager->UpdateCategoryL( *cat );
              

              

                  CleanupStack::PopAndDestroy( cat );
              

                  }
              

              

              // Close the iterator and the category manager.
              

              CleanupStack::PopAndDestroy( iter );
              

              CleanupStack::PopAndDestroy( categoryManager );
              

              }
             
            

Creating local category

The following example shows how the client can create a new category and add it to database.

              
               // Create a local category object
               

               CPosLandmarkCategory* category = CPosLandmarkCategory::NewLC();
               

               _LIT( KRestaurant, "Restaurant" );
               

               category->SetCategoryNameL( KRestaurant );
               

               

               // Add it to database
               

               TPosLmItemId categoryId = aCategoryManager->AddCategoryL( *category );
               

               CleanupStack::PopAndDestroy( category );
              
             

Exporting landmarks

To export a set of landmarks, the client must first create a CPosLandmarkEncoder object for the landmark content format in which the landmarks should be encoded. The client can add some information of the landmark collection in the encoder as well.

The client must also provide a list of the landmarks to be exported. If some of the landmarks are not found in the database, the export operation fails with the error code KErrNotFound . The client does not have to add any landmarks to the encoder object. The export operation will add the ones specified in the ID array. The method returns an operation object, which can be run in incremental mode (see Executing incremental operations ). If it is run incrementally, the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks is exported. The client takes ownership of the returned operation object. When all the landmarks have been exported, the client must finalize the encoding by calling CPosLandmarkEncoder::FinalizeEncodingL() .

The sequence diagram below describes basic steps a client does to export landmarks from a database to a file.

The following example shows how the client can export landmarks to a file using the CPosLandmarkDatabase::ExportLandmarksL() method. aDatabase is an open CPosLandmarkDatabase handle. In this example incremental operations are executed synchronously.

              
               void ExportSelectedLandmarksL( 
               

                   CPosLandmarkDatabase& aDatabase,
               

                   RArray<TPosLmItemId>& aSelectedLandmarks)
               

               {
               

               _LIT( KExportFilePath, "c:\\eposLmExport.lmx" );
               

               // Mime type of landmarks exchange format
               

               _LIT8( KPosMimeTypeLandmarkCollectionXml, 
               

                "application/vnd.nokia.landmarkcollection+xml" );
               

               

               // Create the encoder to be used for exporting landmarks
               

               CPosLandmarkEncoder* encoder = 
               

                     CPosLandmarkEncoder::NewL( KPosMimeTypeLandmarkCollectionXml );
               

               CleanupStack::PushL( encoder );
               

               

               // Point out the file to export landmark data to
               

               encoder->SetOutputFileL( KExportFilePath );
               

               

               // Execute the operation in one batch
               

               // Note: There must be landmarks for specified IDs in the database,
               

               // otherwise operation will fail with KErrNotFound leave code
               

               ExecuteAndDeleteLD( aDatabase->ExportLandmarksL( 
               

                *encoder, aSelectedLandmarks, CPosLandmarkDatabase::EIncludeCategories ) );
               

               

               // Finalize encoding to complete export
               

               ExecuteAndDeleteLD( encoder->FinalizeEncodingL() );
               

               CleanupStack::PopAndDestroy( encoder );
               

               }
              
             

• CPosLandmarkDatabase
• CPosLandmarkDatabase::ExportLandmarksL()
• CPosLandmarkEncoder
• CPosLandmarkEncoder::FinalizeEncodingL()
• CPosLmOperation
• KErrNotFound

Importing landmarks

To import landmark content, the client must first create a parser object of class CPosLandmarkParser , which can parse the landmark content. The client does not have to call CPosLandmarkParser::ParseContentL() first. If the content is not already parsed, this will be handled by the import operation.

There are two different CPosLandmarkDatabase::ImportLandmarksL() overloads defined that can be used to import landmark data. In one of them, the client can pass an array defining a subset of the landmarks in the parser object. This way the client can select to import only a part of the landmark content. The other method does not take any parameters and imports all landmarks. Both the import methods return an operation object, which can be run in incremental mode (see Executing incremental operations ). If it is run incrementally, the client can supervise the progress of the operation.

If the CPosLmOperation object is deleted before the operation is complete, it is possible that only a subset of the landmarks is imported. The client takes ownership of the returned operation object. After completion, CPosLandmarkDatabase::ImportedLandmarksIteratorL() can be called to retrieve the IDs of the added landmarks. If the database is read-only, this operation will complete with the error code KErrAccessDenied . If the client specifies invalid transfer option values, this operation will panic.

Note: The CPosLmOperation::NextStep() method cannot be executed synchronously using User::WaitForRequest() for the import operations. Doing so may cause the operation to hang. CPosLmOperation::NextStep() must be executed using an active object.

The diagram below describes general steps, which client does when imports landmarks from a file.

The following example shows how the client can import landmarks from file using the CPosLandmarkDatabase::ImportLandmarksL() method. aDatabase is an open CPosLandmarkDatabase handle.

              
               void ImportLandmarksL( 
               

                   CPosLandmarkDatabase& aDatabase,
               

                   const TDesC& aImportFilePath )
               

               {
               

               // Mime type of landmarks exchange format
               

               _LIT8( KPosMimeTypeLandmarkCollectionXml, 
               

                   "application/vnd.nokia.landmarkcollection+xml");
               

               

               // Create the parser to be used for importing landmarks
               

               CPosLandmarkParser* parser = 
               

                   CPosLandmarkParser::NewL( KPosMimeTypeLandmarkCollectionXml );
               

               CleanupStack::PushL( parser );
               

               

               // Point out the file to import landmark data from
               

               parser->SetInputFileL( aImportFilePath );
               

               CPosLmOperation* op = aDatabase->ImportLandmarksL( 
               

                   *parser, CPosLandmarkDatabase::EDefaultOptions );
               

               CleanupStack::PushL( op );
               

               // Execute the operation in one batch
               

               op->ExecuteL();
               

               

               // Fetch the landmark iterator of imported landmark IDs
               

               CPosLmItemIterator* iter = aDatabase->ImportedLandmarksIteratorL( op );
               

               CleanupStack::PushL( iter ); 
               

               

               // Fetch imported landmark data using this iterator
               

               

               // Cleanup
               

               CleanupStack::PopAndDestroy( iter );
               

               CleanupStack::PopAndDestroy( op );
               

               CleanupStack::PopAndDestroy( parser );
               

               }
              
             

• CPosLandmarkDatabase
• CPosLandmarkDatabase::ImportLandmarksL()
• CPosLandmarkDatabase::ImportedLandmarksIteratorL()
• CPosLandmarkParser
• CPosLandmarkParser::ParseContentL()
• CPosLmOperation
• CPosLmOperation::NextStep()
• KErrAccessDenied
• User::WaitForRequest()

Encoding of Landmarks to URL

To encode a landmark to an URL ,the client has to first create an instance of CPosLandmarkEncoder class with the URL hostname as the MIME type.( which is 'maps.ovi.com' ).The output buffer into which the encoded URL is written can be set using the CPosLandmarkEncoder::SetUseOutputBufferL.The output can also be encoded into a file by setting the output file using CPosLandmarkEncoder::SetUseOutputFileL.

The client can specify the landmark to be encoded by using CPosLandmarkEncoder::AddLandmarkL() method.When the landmark has been encoded, the client must finalize the encoding by calling CPosLandmarkEncoder::FinalizeEncodingL().

The sequence diagram below describes basic steps a client does to encode landmark to a URL.Currently encoding of only a single landmark is supported.Therefore if AddLandmarkL() method is called more than once during the encoding process KErrNotSupported is returned.

The following example shows how the client can encode landmark to an URL using CPosLandmarkEncoder class.

               
                void EncodeLandmarktoUrl ( CPosLandmark& aLandmark )
                

                {
                

                //Mime type used for encoding URL
                

                _LIT8( KUrlMimeType , "maps.ovi.com" );
                

                

                // Create the encoder to be used for encoding landmark to URL
                

                CPosLandmarkEncoder* encoder = 
                

                      CPosLandmarkEncoder::NewL( KUrlMimeType );
                

                CleanupStack::PushL( encoder );
                

                

                // Set output buffer into which the encoded URL will be written
                

                CBufBase* outputBuffer = encoder->SetUseOutputBufferL();
                

                

                // Add the landmark to be encoded
                

                encoder->AddLandmarkL( aLandmark );
                

                

                // Perform required operation on the outputBuffer
                

                // Delete the buffer
                

                delete outputBuffer;
                

                

                // Finalize encoding
                

                ExecuteAndDeleteLD( encoder->FinalizeEncodingL() );
                

                CleanupStack::PopAndDestroy( encoder );
                

                

                }
               
              

• CPosLandmarkEncoder
• CPosLandmarkEncoder::AddLandmarkL()
• CPosLandmarkEncoder::FinalizeEncodingL().

Parsing URL to obtain a landmark

The client can parse an URL and decode the landmark information present in the URL by using the CPosLandmarkParser class.In order to do this,the client has to first create an instance of the CPosLandmarkParser with the MIME type as the hostname of the URL( which is 'maps.ovi.com' ).

The URL can be provided as an input buffer or input file by using the CPosLandmarkParser::SetInputBuffer method and CPosLandmarkParser::SetInputFileL or CPosLandmarkParser::SetInputFileHandleL methods respectively.

The URL can then be parsed by calling the CPosLandmarkParser::ParseContentL method.This method returns a pointer to the CPosLmOperation class , which is then used to call the CPosLmOperation::ExecuteL method to complete the parsing operation.

The parsed landmark can then be retrieved using the CPosLandmarkParser::LandmarkLC method.

The sequence diagram below describes basic steps a client does to parse an URLand decode it to a landmark Currently decoding of only a single landmark is supported.

The following example shows how the client can parse an URL using CPosLandmarkParser class.

               
                void ParseURLtoLandmark ( TDesC& aUrl )
                

                {
                

                //Mime type used for encoding URL
                

                _LIT8( KUrlMimeType , "maps.ovi.com" );
                

                

                // Create the parser to be used for parsing the URL
                

                CPosLandmarkParser* parser = 
                

                      CPosLandmarkParser::NewL( KUrlMimeType );
                

                CleanupStack::PushL( parser );
                

                

                

                // Set the input buffer that contains the URL to be parsed
                

                parser->SetInputBuffer( aUrl );
                

                

                // Parse the URL
                

                CPosLmOperation* op  = parser->ParseContentL();
                

                CleanupStack::PushL( op );
                

                // Execute the operation in one batch
                

                op -> ExecuteL();
                

                

                // Retrieve the parsed landmark
                

                CPosLandmark* parsedLandmark = parser->LandmarkLC();
                

                

                // Client can perform required operation on the parsedLandmark
                

                

                CleanupStack::PopAndDestroy( parsedLandmark );
                

                CleanupStack::PopAndDestroy( op );
                

                CleanupStack::PopAndDestroy( parser );
                

                

                }
               
              

• CPosLandmarkParser