1 /*

     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CLandmarkService class

    15  *

    16 */

    17 

    18 

    19 #ifndef __CLANDMARKSERVICE_H__

    20 #define __CLANDMARKSERVICE_H__

    21 

    22 #ifdef _DEBUG

    23 #include <flogger.h>

    24 #endif

    25 

    26 // INCLUDES

    27 #include <e32base.h>

    28 #include <e32cmn.h>

    29 #include <badesca.h>

    30 

    31 //FORWARD DECLARARTIONS

    32 class CLandmarkManageHandlers;

    33 class MLandmarkObserver;

    34 class CLandmarkFilter;

    35 class CPosLandmarkParser;

    36 class CPosLandmarkEncoder;

    37 class CPosLmItemIterator;

    38 class CPosLmDatabaseManager;

    39 class CPosLandmark;

    40 class CPosLandmarkCategory;

    41 class TPosLmDatabaseSettings;

    42 class CLandmarkManageObjects;

    43 

    44 /**

    45  * CLandmarkService

    46  * This class has the core implementation. The member functions of this class

    47  * call the native landmarks api's to perform the necessary operations. This class 

    48  * also owns the garbage collector which takes care of active objects associated 

    49  * with async requests. It also owns the CLandmarkManageHandlers object that manages

    50  * the handles to open databases. The interface class calls the appropriate member

    51  * functions of this class to perform the required operation.

    52  */

    53 // CLASS DECLARATION

    54 NONSHARABLE_CLASS(CLandmarkService): public CBase

    55 	{

    56 public:

    57 	/**

    58 	 * TPosItem

    59 	 * Specifies whether the id passed is a landmark id or a category id.

    60 	 */

    61 	enum TPosItem

    62 		{

    63 		ECategory = 0 /**<

    64 		 Item is a landmark category id. */,

    65 		ELandmark /**<

    66 		 Item is a landmark id. */,

    67 		};

    68 	/**

    69 	 * TDatabaseType

    70 	 *  Specifies whether the database is local or remote.

    71 	 */

    72 	enum TDatabaseType

    73 		{

    74 		ELocalDatabase = 0 /**<

    75 		 database is a local. */,

    76 		ERemoteDatabase /**<

    77 		 database is remote.  */,

    78 		};

    79 

    80 public: // New methods

    81 

    82 	/**

    83 	 * NewL.

    84 	 * Two-phased constructor.

    85 	 * Create a CLandmarkService object.

    86 	 * @return A pointer to the created instance of CLandmarkService.

    87 	 */

    88 	IMPORT_C static CLandmarkService* NewL();

    89 

    90 	/**

    91 	 * NewLC.

    92 	 * Two-phased constructor.

    93 	 * Create a CLandmarkService object.

    94 	 * @return A pointer to the created instance of CLandmarkService.

    95 	 */

    96 	IMPORT_C static CLandmarkService* NewLC();

    97 

    98 	/**

    99 	 * ~CLandmarkService

   100 	 * Destructor.

   101 	 */

   102 	~CLandmarkService();

   103 

   104 public: // Functions to retrieve data members

   105 

   106 	/**

   107 	 * ImportL.

   108 	 * Imports landmarks to the requested database.

   109 	 * @param aIterator A pointer reference to the list of imported landmarks. User

   110 	 * owns the iterator.

   111 	 * @param aLandmarkParser The instance of CPosLandmarkParser that 

   112 	 * will parse the input landmark file.

   113 	 * @param aDatabaseUri The URI of the database to which the parsed landmarks 

   114 	 * will be imported.

   115 	 */

   116 	IMPORT_C void ImportL( CPosLmItemIterator*& aIterator,

   117 			CPosLandmarkParser& aLandmarkParser,

   118 			const TDesC& aDatabaseUri = KNullDesC );

   119 

   120 	/**

   121 	 * ExportL.

   122 	 * Export a set of landmarks from the requested database to a file.

   123 	 * @param aLandmarkEncoder A pointer to a landmark encoder object.

   124 	 * @param aLandmarkIdArray The array of landmark ids which should be exported.

   125 	 * @param aDatabaseUri The URI of the database from which the landmarks will 

   126 	 * be exported.

   127 	 */

   128 	IMPORT_C void ExportL( CPosLandmarkEncoder& aLandmarkEncoder,

   129 			const RArray<TPosLmItemId>& aLandmarkIdArray,

   130 			const TDesC& aDatabaseUri = KNullDesC ) const;

   131 

   132 	/**

   133 	 * GetListL.

   134 	 * Gets a list of landmarks/landmark categories from the requested database synchronously.

   135 	 * @param aIterator A pointer reference to the list of retrieved landmarks/landmark 

   136 	 * categories. User owns the iterator.

   137 	 * @param aFilter The filter to be used for searching landmarks/landmark categories

   138 	 * in database.

   139 	 * @param aDatabaseUri The URI of the database from which landmarks/lanmdark categories 

   140 	 * should be fetched.

   141 	 */

   142 	IMPORT_C void GetListL ( CPosLmItemIterator*& aIterator,

   143 			CLandmarkFilter& aFilter, const TDesC& aDatabaseUri = KNullDesC ) const;

   144 

   145 	/**

   146 	 * GetListL.

   147 	 * Gets a list of landmark databases.

   148 	 * @param aDatabaseList A pointer reference to the list of retrieved databases. 

   149 	 * User owns allocated list.

   150 	 * @param aProtocol Protocol which matches that of the databases to be retrieved.

   151 	 */

   152 	IMPORT_C void GetListL( CDesCArray*& aDatabaseList,

   153 			const TDesC& aProtocol = KNullDesC ) const;

   154 

   155 	/**

   156 	 * GetListL.

   157 	 * Gets a list of landmarks/landmark categories from the requested database asynchronously.

   158 	 * @param aTransactionId The transaction id assigned to this asynchronous request.

   159 	 * @param aFilter The filter to be used for searching landmarks/landmark categories 

   160 	 * in database.

   161 	 * @param aDatabaseUri The URI of the database from which landmarks/lanmdark categories 

   162 	 * should be fetched.

   163 	 */

   164 	IMPORT_C void GetListL( TInt32 aTransactionId,

   165 			CLandmarkFilter& aFilter, const TDesC& aDatabaseUri = KNullDesC );

   166 

   167 	/**

   168 	 * AddItemL.

   169 	 * Adds a new Landmark to the given database.

   170 	 * @param aLandmark CPosLandmark instance to be added to database.

   171 	 * @param aDatabaseUri The URI of the database to which the CPosLandmark

   172 	 * instance should be added.

   173 	 */

   174 	IMPORT_C TPosLmItemId AddItemL( CPosLandmark& aLandmark,

   175 			const TDesC& aDatabaseUri = KNullDesC );

   176 

   177 	/**

   178 	 * AddItemL.

   179 	 * Adds a new Landmark category to the given database.

   180 	 * @param aCategory CPosLandmarkCategory instance to be added to database.

   181 	 * @param aDatabaseUri The URI of the database to which CPosLandmarkCategory

   182 	 * instance should be added.

   183 	 */

   184 	IMPORT_C TPosLmItemId AddItemL( CPosLandmarkCategory& aCategory,

   185 			const TDesC& aDatabaseUri = KNullDesC );

   186 

   187 	/**

   188 	 * AddItemL.

   189 	 * Adds a new database to terminal.

   190 	 * @param aDatabaseUri The URI of the database to be added to terminal.

   191 	 */

   192 	IMPORT_C void AddItemL( const TDesC& aDatabaseUri );

   193 

   194 	/**

   195 	 * UpdateItemL.

   196 	 * Updates an existing Landmark in the given database.

   197 	 * @param aLandmark CPosLandmark instance to be updated in database.

   198 	 * @param aDatabaseUri The URI of the database in which CPosLandmark 

   199 	 * instance should be updated.

   200 	 */

   201 	IMPORT_C void UpdateItemL( const CPosLandmark& aLandmark,

   202 			const TDesC& aDatabaseUri = KNullDesC );

   203 

   204 	/**

   205 	 * UpdateItemL.

   206 	 * Updates an existing Landmark category in the given database.

   207 	 * @param aCategory CPosLandmarkCategory instance to be updated in database.

   208 	 * @param aDatabaseUri The URI of the database to which CPosLandmarkCategory 

   209 	 * instance should be updated.

   210 	 */

   211 	IMPORT_C void UpdateItemL( const CPosLandmarkCategory& aCategory,

   212 			const TDesC& aDatabaseUri = KNullDesC );

   213 

   214 	/**

   215 	 * UpdateItemL.

   216 	 * Updates existing Database Information.

   217 	 * @param aSettings TPosLmDatabaseSettings information to be updated.

   218 	 * @param aDatabaseUri The URI of the database to be updated.

   219 	 */

   220 	IMPORT_C void UpdateItemL( TPosLmDatabaseSettings aSettings,

   221 			const TDesC& aDatabaseUri = KNullDesC );

   222 

   223 	/**

   224 	 * LandmarkLC.

   225 	 * Retrieves a Landmark from the database.

   226 	 * @param aLandmarkId Id of the landmark to be retrieved.

   227 	 * @param aDatabaseUri The URI of the database from which the CPosLandmark

   228 	 * instance should be retrieved.

   229 	 * @return A pointer to CPosLandmark instance.

   230 	 */

   231 	IMPORT_C CPosLandmark* LandmarkLC( const TPosLmItemId& aLandmarkId,

   232 			const TDesC& aDatabaseUri = KNullDesC ) const;

   233 

   234 	/**

   235 	 * CategoryLC.

   236 	 * Retrieves a Landmark category from the database.

   237 	 * @param aCategoryId Id of the landmark category to be retrieved.

   238 	 * @param aDatabaseUri The URI of the database from which the CPosLandmarkCategory

   239 	 * instance should be retrieved.

   240 	 * @return A pointer to CPosLandmarkCategory instance.

   241 	 */

   242 	IMPORT_C CPosLandmarkCategory* CategoryLC( const TPosLmItemId& aCategoryId,

   243 			const TDesC& aDatabaseUri = KNullDesC ) const;

   244 

   245 	/**

   246 	 * RemoveItemL.

   247 	 * Removes a Landmark/Landmark category from given database.

   248 	 * @param aItemId The id of the Landmark/Landmark category to be removed.

   249 	 * @param aItemIsLandmark Whether id passed is a landmark id or a category id.

   250 	 * @param aDatabaseUri The URI of the database from which the 

   251 	 * Landmark/Landmark category is to be removed.

   252 	 */

   253 	IMPORT_C void RemoveItemL( TPosLmItemId aItemId, TPosItem aItemIsLandmark,

   254 			const TDesC& aDatabaseUri = KNullDesC );

   255 

   256 	/**

   257 	 * RemoveItemL.

   258 	 * Removes the given database.

   259 	 * @param aDatabaseUri The URI of the database to be removed from terminal.

   260 	 */

   261 	IMPORT_C void RemoveItemL( const TDesC& aDatabaseUri );

   262 

   263 	/**

   264 	 * SetActiveL.

   265 	 * Sets specified database as an active database.

   266 	 * @param aDatabaseUri The URI of the database to be set as an active database.

   267 	 */

   268 	IMPORT_C void SetActiveL( const TDesC& aDatabaseUri );

   269 

   270 	/**

   271 	 * LinkCategoryToLandmarksL.

   272 	 * Associates a category with a set of landmarks.

   273 	 * @param aCategoryId The id of category.

   274 	 * @param aLandmarkIdArray The array of landmark ids to which the 

   275 	 * category is to be associated.

   276 	 * @param aDatabaseUri The URI of the database in which the landmarks and category exist.

   277 	 */

   278 	IMPORT_C void LinkCategoryToLandmarksL( TPosLmItemId aCategoryId,

   279 			RArray< TPosLmItemId >& aLandmarkIdArray,

   280 			const TDesC& aDatabaseUri = KNullDesC );

   281 

   282 	/**

   283 	 * UnlinkCategoryToLandmarksL.

   284 	 * Dissociates a category with a set of landmarks.

   285 	 * @param aCategoryId The id of category.

   286 	 * @param aLandmarkIdArray The array of landmark ids to which the 

   287 	 * category is to be dissociated.

   288 	 * @param aDatabaseUri The URI of the database in which the landmarks and category exist.

   289 	 */

   290 	IMPORT_C void UnlinkCategoryToLandmarksL( TPosLmItemId aCategoryId,

   291 			RArray< TPosLmItemId >& aLandmarkIdArray,

   292 			const TDesC& aDatabaseUri = KNullDesC );

   293 

   294 	/**

   295 	 * RegisterObserver.

   296 	 * Registers an observer for Asynchronous call backs.

   297 	 * @param aObserver A pointer to a concrete MLandmarkObserver instance.

   298 	 */

   299 	IMPORT_C void RegisterObserver( MLandmarkObserver* aObserver );

   300 

   301 	/**

   302 	 * Cancel.

   303 	 * Cancels an ongoing asynchronous request.

   304 	 * @param aTransactionId The transaction id of the asynchronous request.

   305 	 */

   306 	IMPORT_C void Cancel( TInt32 aTransactionId ) const;

   307 

   308 	/**

   309 	 * GetDefaultDbUri.

   310 	 * Gets the URI of the default database.

   311 	 * @param aDefaultDbUri A reference to the URI of the default database.				

   312 	 */

   313 	IMPORT_C void GetDefaultDbUriL( TPtrC& aDefaultDbUri ) const;

   314 

   315 private:// helper functions

   316 

   317 	/**

   318 	 * GetDbTypeFromUri.

   319 	 * Gets the type of database.

   320 	 * @param aDatabaseUri The URI of the database whose information is queried.

   321 	 * @return Error.

   322 	 */

   323 	TDatabaseType GetDbTypeFromUri ( const TDesC& aDbUri ) const;

   324 

   325 private: // Constructors

   326 

   327 	/**

   328 	 * ConstructL

   329 	 * 2nd phase constructor.

   330 	 * Perform the second phase construction of a

   331 	 * CLandmarkService object.

   332 	 */

   333 	void ConstructL();

   334 

   335 	/**

   336 	 * CLandmarkService.

   337 	 * C++ default constructor.

   338 	 */

   339 	CLandmarkService();

   340 

   341 private: // Data members

   342 

   343 	/**

   344 	 * iManageHandler

   345 	 * CPosLmManageHandler instance.

   346 	 */

   347 	CLandmarkManageHandlers* iManageHandler;

   348 

   349 	/**

   350 	 * iDatabaseManager

   351 	 * CPosLmDatabaseManager instance.

   352 	 */

   353 	CPosLmDatabaseManager* iDatabaseManager;

   354 

   355 	/**

   356 	 * iObserver

   357 	 * MLandmarkObserver instance.

   358 	 */

   359 	MLandmarkObserver* iObserver;

   360 

   361 	/**

   362 	 * iManageObjects

   363 	 * CLandmarkManageObjects instance.

   364 	 */

   365 	CLandmarkManageObjects* iManageObjects;

   366 

   367 #ifdef _DEBUG

   368 	RFileLogger iLog;

   369 #endif		

   370 	};

   371 

   372 #endif // __CLANDMARKSERVICE_H__

   373 

   374 // End of File

   375