00001 /* 00002 * ============================================================================== 00003 * Name : EPos_CPosLmDatabaseManagerPluginBase.h 00004 * Part of : Mobile Location Framework/Landmarks 00005 * Interface : SDK/S60, Landmarks Database Management API 00006 * Description : CPosLmDatabaseManagerPluginBase class 00007 * Version : %version: bh1cfloc#3 % 00008 * 00009 * Copyright © 2005-2006 Nokia. All rights reserved. 00010 * This material, including documentation and any related computer 00011 * programs, is protected by copyright controlled by Nokia. All 00012 * rights are reserved. Copying, including reproducing, storing, 00013 * adapting or translating, any or all of this material requires the 00014 * prior written consent of Nokia. This material also contains 00015 * confidential information which may not be disclosed to others 00016 * without the prior written consent of Nokia. 00017 * ============================================================================ 00018 * Template version: 4.0 00019 */ 00020 00021 #ifndef CPOSLMDATABASEMANAGERPLUGINBASE_H 00022 #define CPOSLMDATABASEMANAGERPLUGINBASE_H 00023 00024 #include <e32base.h> 00025 #include <badesca.h> 00026 #include <epos_tposlmdatabaseevent.h> 00027 #include <epos_tposlmdatabasesettings.h> 00028 #include <epos_hposlmdatabaseinfo.h> 00029 00030 class CPosLmDbManPluginBaseExtension; 00031 class RPosLandmarkServer; 00032 00039 /* 00040 * This class is the base class which has to be subclassed in order to write a 00041 * plug-in for database management for a specific protocol. It is reserved for 00042 * for future extensions. 00043 * 00044 * @p CPosLmDatabaseManagerPluginBase contains functions for listing, 00045 * registering, unregistering, creating, deleting, copying landmark databases, 00046 * etc. 00047 * 00048 * 00049 * 00050 */ 00051 class CPosLmDatabaseManagerPluginBase : public CBase 00052 { 00053 public: 00054 00055 /* 00056 * Destructor. 00057 */ 00058 IMPORT_C virtual ~CPosLmDatabaseManagerPluginBase(); 00059 00060 public: 00061 00062 /* 00063 * Retrieves the type of media where a landmark database resides. 00064 * 00065 * This function does not validate the URI. If the URI is invalid, this 00066 * function will just return @p EMediaUnknown. 00067 * 00068 * @param[in] aDatabaseUri The URI of the database to check media for. 00069 * @return Type of storage media. 00070 */ 00071 virtual TMediaType DatabaseMedia( const TDesC& aDatabaseUri ) = 0; 00072 00073 /* 00074 * Retrieves the drive letter for the drive where a landmark database 00075 * resides. 00076 * 00077 * If the landmark database is remote or otherwise the drive letter is 00078 * not applicable, 0 is returned. 00079 * 00080 * This function does not validate the URI. If the URI is invalid, this 00081 * function will just return 0. 00082 * 00083 * @param[in] aDatabaseUri The URI of the database to check drive letter 00084 * for. 00085 * @return The drive letter, or 0 if drive letter is not applicable. 00086 */ 00087 virtual TChar DatabaseDrive( const TDesC& aDatabaseUri ) = 0; 00088 00089 /* 00090 * Returns the protocol which the plug-in handles. 00091 * 00092 * The returned descriptor pointer is valid until the plug-in is 00093 * unloaded. 00094 * 00095 * @return Pointer to the protocol descriptor, e.g. "file" 00096 */ 00097 virtual TPtrC Protocol() = 0; 00098 00099 /* 00100 * Lists the URIs to all landmark databases handled by this 00101 * plug-in. 00102 * 00103 * The client takes ownership of the returned array. 00104 * 00105 * If no databases are found, an empty array is returned. 00106 * 00107 * This function requires @p ReadUserData capability. 00108 * 00109 * @return The list of database URIs. 00110 */ 00111 virtual CDesCArray* ListDatabasesLC() = 0; 00112 00113 /* 00114 * Lists information about each landmark database handled by this 00115 * plug-in. 00116 * 00117 * The client specifies an array which is populated by this function. 00118 * The client takes ownership of all information objects in the array. 00119 * 00120 * If no databases are found, the input array is not modified. 00121 * 00122 * This function requires @p ReadUserData capability. 00123 * 00124 * @param[out] aDatabaseInfoArray On return, contains information about 00125 * the landmark databases. 00126 */ 00127 virtual void ListDatabasesL( 00128 RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray 00129 ) = 0; 00130 00131 /* 00132 * Registers a landmark database. 00133 * 00134 * The landmark database is then returned when listing landmark 00135 * databases. 00136 * 00137 * Some protocols like "file" does not allow registering of databases 00138 * and will leave with error code @p KErrNotSupported. To add a 00139 * database of such protocol, the client must call @ref CreateDatabaseL. 00140 * 00141 * The client supplies an information object containing the URI of the 00142 * database to register. The information object can also contain 00143 * database settings, e.g. a display name for the database. 00144 * 00145 * This function requires @p ReadUserData and @p WriteUserData 00146 * capabilities. 00147 * 00148 * @param[in,out] aDatabaseInfo Information about the landmark database to 00149 * register. 00150 * 00151 * @leave KErrNotSupported The protocol specified in the URI is not 00152 * supported by this plug-in or the protocol does not allow 00153 * registering landmark databases. 00154 * @leave KErrArgument The URI is incorrect. 00155 * @leave KErrAlreadyExists The database already exists in the registry. 00156 */ 00157 virtual void RegisterDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0; 00158 00159 /* 00160 * Unregisters a landmark database. 00161 * 00162 * After this, the landmark database will not be returned when listing 00163 * landmark databases. 00164 * 00165 * Some protocols like "file" does not allow unregistering of databases 00166 * and will leave with error code @p KErrNotSupported. To remove a 00167 * database of such protocol, the client must call @ref DeleteDatabaseL. 00168 * 00169 * This function requires @p ReadUserData and @p WriteUserData 00170 * capabilities. 00171 * 00172 * @param[in] aDatabaseUri The URI of the database to register. 00173 * 00174 * @leave KErrNotSupported The protocol specified in the URI is not 00175 * supported by this plug-in or the protocol does not allow 00176 * unregistering landmark databases. 00177 * @leave KErrArgument The URI is incorrect. 00178 */ 00179 virtual void UnregisterDatabaseL( const TDesC& aDatabaseUri ) = 0; 00180 00181 /* 00182 * Unregisters all landmark database which are accessed through this 00183 * plug-in. 00184 * 00185 * After this, the landmark databases will not be returned when listing 00186 * landmark databases. 00187 * 00188 * Some protocols like "file" does not allow unregistering of databases 00189 * and will leave with error code @p KErrNotSupported. To remove a 00190 * "file"-protocol database, the client must call @ref DeleteDatabaseL. 00191 * 00192 * This function requires @p ReadUserData and @p WriteUserData 00193 * capabilities. 00194 * 00195 * @leave KErrNotSupported This plug-in does not allow unregistering 00196 * landmark databases. 00197 */ 00198 virtual void UnregisterAllDatabasesL() = 0; 00199 00200 /* 00201 * Modifies the settings for a landmark database. 00202 * 00203 * This function requires @p ReadUserData and @p WriteUserData 00204 * capabilities. 00205 * 00206 * @param[in] aDatabaseUri The URI of the database to modify settings for. 00207 * @param[in] aDatabaseSettings The new settings for the database. 00208 * 00209 * @leave KErrNotSupported The protocol specified in the URI is not 00210 * supported by this plug-in. 00211 * @leave KErrNotFound The specified database is not found. 00212 */ 00213 virtual void ModifyDatabaseSettingsL( 00214 const TDesC& aDatabaseUri, 00215 const TPosLmDatabaseSettings& aDatabaseSettings 00216 ) = 0; 00217 00218 /* 00219 * Retrieve information about a landmark database. 00220 * 00221 * This function requires @p ReadUserData capability. 00222 * 00223 * @param[in,out] aDatabaseInfo An information object containing the URI of the 00224 * landmark database. On return, the object contains information about 00225 * the landmark database, including any database settings. 00226 * 00227 * @leave KErrNotSupported The protocol specified in the URI is not 00228 * supported by this plug-in. 00229 * @leave KErrNotFound The specified database is not found. 00230 */ 00231 virtual void GetDatabaseInfoL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0; 00232 00233 /* 00234 * Checks if the specified landmark database exists. 00235 * 00236 * The database to check is specified by passing a URI to this function. 00237 * URI construction is described in the class description for 00238 * @ref CPosLmDatabaseManager. 00239 * 00240 * This function requires @p ReadUserData capability. If the database is 00241 * remote, @p NetworkServices capability is also needed. 00242 * 00243 * @param[in] aDatabaseUri The URI of the database which should be checked 00244 * for existence. 00245 * @return @p ETrue if the database exists, otherwise @p EFalse. 00246 * 00247 * @leave KErrArgument The URI is incorrect or the protocol specified in the 00248 * URI is not supported by this plug-in. 00249 */ 00250 virtual TBool DatabaseExistsL( const TDesC& aDatabaseUri ) = 0; 00251 00252 /* 00253 * Creates a landmark database. 00254 * 00255 * This function requires @p ReadUserData and @p WriteUserData 00256 * capabilities. If the database is remote, @p NetworkServices 00257 * capability is also needed. 00258 * 00259 * @param[in,out] aDatabaseInfo Information about the landmark database to 00260 * create. 00261 * 00262 * @leave KErrNotSupported The protocol is not supported or the create 00263 * operation is not supported by the protocol plug-in. 00264 * @leave KErrArgument The URI is incorrect or the protocol specified in the 00265 * URI is not supported by this plug-in. 00266 * @leave KErrAlreadyExists There is already a database at this URI. 00267 */ 00268 virtual void CreateDatabaseL( HPosLmDatabaseInfo& aDatabaseInfo ) = 0; 00269 00270 /* 00271 * Deletes a landmark database. 00272 * 00273 * The database to delete is specified by passing a URI to this 00274 * function. URI construction is described in the class description for 00275 * @ref CPosLmDatabaseManager. The URI must specify the protocol which 00276 * is handled by this database manager plug-in. 00277 * 00278 * If the specified database does not exist, the call is ignored. 00279 * 00280 * This function requires @p ReadUserData and @p WriteUserData 00281 * capabilities. If the database is remote, @p NetworkServices 00282 * capability is also needed. 00283 * 00284 * @param[in] aDatabaseUri The URI of the database to delete. 00285 * 00286 * @leave KErrNotSupported The protocol is not supported or the delete 00287 * operation is not supported by the plug-in. 00288 * @leave KErrArgument The URI is incorrect or the protocol specified in the 00289 * URI is not supported by this plug-in. 00290 * @leave KErrInUse The database is in use by some client. 00291 * @leave KErrAccessDenied The database is read-only. 00292 */ 00293 virtual void DeleteDatabaseL( const TDesC& aDatabaseUri ) = 0; 00294 00295 /* 00296 * Copies a landmark database to a new location. 00297 * 00298 * Database locations are specified as URIs. URI construction is 00299 * described in the class description for @ref CPosLmDatabaseManager. 00300 * The target and source URIs must specify the protocol which is handled 00301 * by this database manager plug-in. 00302 * 00303 * This function requires @p ReadUserData and @p WriteUserData 00304 * capabilities. If the database is remote, @p NetworkServices 00305 * capability is also needed. 00306 * 00307 * @param[in] aSourceUri The URI of the database to copy. 00308 * @param[in] aTargetUri The URI of the new database location. 00309 * 00310 * @leave KErrNotSupported The operation is not supported by the plug-in. 00311 * @leave KErrArgument A URI is incorrect or the protocol specified in a 00312 * URI is not supported by this plug-in. 00313 * @leave KErrInUse There is a write-lock on the database, e.g. some client 00314 * is currently modifying the database. 00315 * @leave KErrNotFound There is no database at the source URI. 00316 */ 00317 virtual void CopyDatabaseL( 00318 const TDesC& aSourceUri, 00319 const TDesC& aTargetUri 00320 ) = 0; 00321 00322 protected: 00323 00324 /* 00325 * C++ constructor. 00326 */ 00327 IMPORT_C CPosLmDatabaseManagerPluginBase(); 00328 00329 /* 00330 * Creates the internals of the manager. 00331 * 00332 * This function must be called first in the manager's @b ConstructL() 00333 * method. 00334 * 00335 * @param[in] aConstructionParameters The construction parameters supplied 00336 * in the factory call. 00337 */ 00338 IMPORT_C void BaseConstructL( TAny* aConstructionParameters ); 00339 00340 protected: 00341 00342 /* 00343 * Returns a reference to an open landmark server session. 00344 * 00345 * @return The server session. 00346 */ 00347 IMPORT_C RPosLandmarkServer& Session() const; 00348 00349 private: 00350 00351 // Prohibit copy constructor 00352 CPosLmDatabaseManagerPluginBase( 00353 const CPosLmDatabaseManagerPluginBase& ); 00354 // Prohibit assigment operator 00355 CPosLmDatabaseManagerPluginBase& operator=( 00356 const CPosLmDatabaseManagerPluginBase& ); 00357 00358 private: 00359 00360 CPosLmDbManPluginBaseExtension* iExtension; 00361 }; 00362 00363 // CPOSLMDATABASEMANAGERPLUGINBASE_H 00364 #endif 00365 00366