CPosLmDatabaseManager Class Reference

#include <mw/EPos_CPosLmDatabaseManager.h>

Link against: eposlmdbmanlib.lib

class CPosLmDatabaseManager : public CBase

Inherits from

  • CPosLmDatabaseManager
    Public Member Functions
    virtual ~CPosLmDatabaseManager()
    pure virtual TInt CancelNotifyDatabaseEvent()
    pure virtual voidCopyDatabaseL(const TDesC &, const TDesC &)
    pure virtual voidCreateDatabaseL(HPosLmDatabaseInfo &)
    pure virtual TBool DatabaseExistsL(const TDesC &)
    pure virtual HBufC *DatabaseUriFromLastEventLC()
    pure virtual HBufC *DefaultDatabaseUriLC()
    pure virtual voidDeleteDatabaseL(const TDesC &)
    pure virtual voidGetDatabaseInfoL(HPosLmDatabaseInfo &)
    pure virtual voidListDatabasesL(RPointerArray< HPosLmDatabaseInfo > &, const TDesC &)
    pure virtual CDesCArray *ListDatabasesLC(const TDesC &)
    pure virtual voidModifyDatabaseSettingsL(const TDesC &, const TPosLmDatabaseSettings &)
    IMPORT_C CPosLmDatabaseManager *NewL()
    pure virtual voidNotifyDatabaseEvent(TPosLmDatabaseEvent &, TRequestStatus &)
    pure virtual voidRegisterDatabaseL(HPosLmDatabaseInfo &)
    pure virtual voidSetDefaultDatabaseUriL(const TDesC &)
    pure virtual voidUnregisterAllDatabasesL(const TDesC &)
    pure virtual voidUnregisterDatabaseL(const TDesC &)
    Protected Member Functions
    CPosLmDatabaseManager()
    Inherited Functions
    CBase::CBase()
    CBase::Delete(CBase *)
    CBase::Extension_(TUint,TAny *&,TAny *)
    CBase::operator new(TUint)
    CBase::operator new(TUint,TAny *)
    CBase::operator new(TUint,TLeave)
    CBase::operator new(TUint,TLeave,TUint)
    CBase::operator new(TUint,TUint)
    CBase::~CBase()

    Detailed Description

    This class is used to manage landmark databases.

    CPosLmDatabaseManager contains functions for listing registering, unregistering, creating, deleting, copying landmark databases, etc. It also has functions for managing the default landmark database. The client can listen to events related to database management.

    A database is local if it resides in the phone or in some device which is mapped to the phones file system. If a database is not local, it is remote.

    The client refers to a database by URI. The URI consists of a protocol specifier and the database location: "protocol://location". If the client does not specify a protocol, "file://" is assumed.

    For local landmark databases, the URI consists of the drive and the database file name, e.g. "c:landmarks.ldb". The path cannot be specified by the client. The extension of the database file name must be "ldb". If a path is included or if the file name extension is not .ldb", the client receives the error code KErrArgument. For local landmark databases, the client receives the error code KErrBadName if the file name is invalid and KErrNotReady if the drive specified in the URI does not exist.

    If the client specifies a local database URI and does not specify the drive letter, e.g. "landmarks.ldb", default database drive is assumed.

    Local databases are created by calling CreateDatabaseL . "Bookmarks" to remote databases are created by calling RegisterDatabaseL . After this they are listed by the database manager.

    If CPosLmDatabaseManager is used, the client must call the global function ReleaseLandmarkResources before terminating, in order to release all used landmark resources, otherwise the client may receive an ALLOC panic.

    Since
    S60 3.0

    Constructor & Destructor Documentation

    CPosLmDatabaseManager ( )

    IMPORT_CCPosLmDatabaseManager()[protected]

    ~CPosLmDatabaseManager ( )

    IMPORT_C~CPosLmDatabaseManager()[virtual]

    Destructor.

    Member Function Documentation

    CancelNotifyDatabaseEvent ( )

    TInt CancelNotifyDatabaseEvent()[pure virtual]

    Cancels a call to NotifyDatabaseEvent .

    Returns: KErrNone if the request was successfully cancelled, otherwise a system wide error code.

    CopyDatabaseL ( const TDesC &, const TDesC & )

    voidCopyDatabaseL(const TDesC &aSourceUri,
    const TDesC &aTargetUri
    )[pure virtual]

    Copies a landmark database to a new location.

    Database locations are specified as URIs. URI construction is described in the class description for CPosLmDatabaseManager . Target URI protocol must be the same as source URI protocol.

    This function requires ReadUserData and WriteUserData capabilities. If the databases are remote, NetworkServices capability is also needed.

    leave
    KErrNotSupported The protocol specified in the a URI is not supported.
    leave
    KErrArgument A URI is incorrect.
    leave
    KErrAlreadyExists There is already a database at the target URI.
    leave
    KErrInUse There is a write-lock on the database, e.g. some client is currently modifying the database.
    leave
    KErrNotFound There is no database at the source URI.
    ParameterDescription
    aSourceUriThe URI of the database to copy.
    aTargetUriThe URI of the new database location.

    CreateDatabaseL ( HPosLmDatabaseInfo & )

    voidCreateDatabaseL(HPosLmDatabaseInfo &aDatabaseInfo)[pure virtual]

    Creates a landmark database.

    This function requires ReadUserData and WriteUserData capabilities. If the database is remote, NetworkServices capability is also needed.

    leave
    KErrNotSupported The protocol specified in the URI is not supported.
    leave
    KErrArgument The URI is incorrect.
    leave
    KErrAlreadyExists There is already a database at this URI.
    ParameterDescription
    aDatabaseInfoInformation about the landmark database to create. The information object will be updated with media type and drive information.

    DatabaseExistsL ( const TDesC & )

    TBool DatabaseExistsL(const TDesC &aDatabaseUri)[pure virtual]

    Checks if the specified landmark database exists.

    The database to check is specified by passing a URI to this function. URI construction is described in the class description for CPosLmDatabaseManager . The URI must point to a database which is handled by this database manager, i.e. not a remote location.

    This function requires ReadUserData capability. If the database is remote, NetworkServices capability is also needed.

    leave
    KErrNotSupported The protocol specified in the URI is not supported.
    leave
    KErrArgument The URI is incorrect.
    ParameterDescription
    aDatabaseUriThe URI of the database which should be checked for existence.

    Returns: ETrue if the database exists, otherwise EFalse.

    DatabaseUriFromLastEventLC ( )

    HBufC *DatabaseUriFromLastEventLC()[pure virtual]

    Retrieves the database URI associated with the last event.

    Some events, e.g. EPosLmDbDatabaseRegistered and EPosLmDbDatabaseUnregistered, refer to a specific database. The URI of the database can be retrieved through this function.

    If the URI should be retrieved, this function must be called before NotifyDatabaseEvent is called again to listen for the next event.

    This function requires ReadUserData capability.

    leave
    KErrNotFound There is no database URI associated with the event or, the database URI has been discarded because the client has called NotifyDatabaseEvent again.

    Returns: The database URI associated with the event. The client takes ownership of the descriptor object.

    DefaultDatabaseUriLC ( )

    HBufC *DefaultDatabaseUriLC()[pure virtual]

    Retrieves the URI of the default landmark database.

    The default landmark database is the one which is opened when calling CPosLandmarkDatabase::OpenL without any parameters.

    Only "file"-protocol databases can be set as default.

    This function requires ReadUserData capability.

    Returns: The URI of the default landmark database. The client takes ownership of the descriptor object.

    DeleteDatabaseL ( const TDesC & )

    voidDeleteDatabaseL(const TDesC &aDatabaseUri)[pure virtual]

    Deletes a landmark database.

    The database to delete is specified by passing a URI to this function. URI construction is described in the class description for CPosLmDatabaseManager .

    If the specified database does not exist, the call is ignored.

    This function requires ReadUserData and WriteUserData capabilities. If the database is remote, NetworkServices capability is also needed.

    leave
    KErrNotSupported The protocol specified in the URI is not supported.
    leave
    KErrArgument The URI is incorrect.
    leave
    KErrInUse The database is in use by some client.
    leave
    KErrAccessDenied The database is read-only.
    ParameterDescription
    aDatabaseUriThe URI of the database to delete.

    GetDatabaseInfoL ( HPosLmDatabaseInfo & )

    voidGetDatabaseInfoL(HPosLmDatabaseInfo &aDatabaseInfo)[pure virtual]

    Retrieve information about a landmark database.

    This function requires ReadUserData capability.

    leave
    KErrNotSupported The protocol specified in the URI is not supported in the platform.
    leave
    KErrNotFound The specified database is not found.
    leave
    KErrArgument The URI is incorrect.
    ParameterDescription
    aDatabaseInfoAn information object containing the URI of the landmark database. On return, the object contains information about the landmark database, including any database settings.

    ListDatabasesL ( RPointerArray< HPosLmDatabaseInfo > &, const TDesC & )

    voidListDatabasesL(RPointerArray< HPosLmDatabaseInfo > &aDatabaseInfoArray,
    const TDesC &aProtocol =  KNullDesC
    )[pure virtual]

    Lists information about each landmark database known by the Landmarks system.

    The client can specify a protocol string as input to this function. The function then only returns information about the databases which are accessed through this protocol.

    The client specifies an array which is populated by this function. The client takes ownership of all information objects in the array.

    If no databases are found, an empty array is returned.

    This function requires ReadUserData capability.

    leave
    KErrNotSupported The protocol is not supported in the platform.
    ParameterDescription
    aDatabaseInfoArrayOn return, contains information about the landmark databases. Any objects which are in the array when it is passed to this function are not removed.
    aProtocolThe protocol for which database URIs should be listed. If no protocol is specified, i.e. if an empty string is specified, all known database URIs are listed.

    ListDatabasesLC ( const TDesC & )

    CDesCArray *ListDatabasesLC(const TDesC &aProtocol =  KNullDesC )[pure virtual]

    Lists the URIs to all landmark databases known by the Landmarks system.

    The client can specify a protocol string as input to this function. The function then only returns a list of the databases which are accessed through this protocol.

    The client takes ownership of the returned array.

    If no databases are found, an empty array is returned.

    This function requires ReadUserData capability.

    leave
    KErrNotSupported The protocol is not supported in the platform.
    ParameterDescription
    aProtocolThe protocol for which database URIs should be listed. If no protocol is specified, i.e. if an empty string is specified, all known database URIs are listed.

    Returns: The list of database URIs.

    ModifyDatabaseSettingsL ( const TDesC &, const TPosLmDatabaseSettings & )

    voidModifyDatabaseSettingsL(const TDesC &aDatabaseUri,
    const TPosLmDatabaseSettings &aDatabaseSettings
    )[pure virtual]

    Modifies the settings for a landmark database.

    This function requires ReadUserData and WriteUserData capabilities.

    leave
    KErrNotSupported The protocol specified in the URI is not supported in the platform.
    leave
    KErrNotFound The specified database is not found.
    leave
    KErrArgument The URI is incorrect.
    ParameterDescription
    aDatabaseUriThe URI of the database to modify settings for.
    aDatabaseSettingsThe new settings for the database.

    NewL ( )

    IMPORT_C CPosLmDatabaseManager *NewL()[static]

    Two-phased constructor.

    This function requires ReadUserData capability.

    NotifyDatabaseEvent ( TPosLmDatabaseEvent &, TRequestStatus & )

    voidNotifyDatabaseEvent(TPosLmDatabaseEvent &aEvent,
    TRequestStatus &aStatus
    )[pure virtual]

    Listens for database management events.

    This function is asynchronous and it completes the request status when an event occurs. At this time, the client can read event information from the retrieved event object.

    Event listening can be canceled by calling CancelNotifyDatabaseEvent .

    This function requires ReadUserData capability.

    ParameterDescription
    aEventContains the event information when an event occurs (request completes).
    aStatusIs completed with KErrNone if an event occurs or an error code if some error is encountered.

    RegisterDatabaseL ( HPosLmDatabaseInfo & )

    voidRegisterDatabaseL(HPosLmDatabaseInfo &aDatabaseInfo)[pure virtual]

    Registers a landmark database.

    The landmark database is then returned when listing landmark databases.

    For local landmark databases, this function leaves with error code KErrNotSupported. To add a local database, the client must call CreateDatabaseL .

    The client supplies an information object containing the URI of the database to register. The information object can also contain database settings, e.g. a display name for the database.

    This function requires ReadUserData and WriteUserData capabilities.

    leave
    KErrNotSupported The protocol specified in the URI is not supported in the platform or the protocol does not allow registering landmark databases.
    leave
    KErrArgument The URI is incorrect.
    leave
    KErrAlreadyExists The database already exists in the registry.
    ParameterDescription
    aDatabaseInfoInformation about the landmark database to register. The information object will be updated with media type and drive information.

    SetDefaultDatabaseUriL ( const TDesC & )

    voidSetDefaultDatabaseUriL(const TDesC &aDatabaseUri)[pure virtual]

    Sets a landmark database as default.

    This database is opened the next time CPosLandmarkDatabase::OpenL() called without parameters.

    To move the current default database to another drive, first use CopyDatabaseL to copy the database to the new drive, then use SetDefaultDatabaseUriL to set the new database as default and finally, use DeleteDatabaseL if the old default database should be deleted.

    Only "file"-protocol databases can be set as default.

    This function requires WriteDeviceData capability.

    leave
    KErrNotSupported The protocol specified something else than "file://" as protocol in the URI.
    leave
    KErrArgument The URI is incorrect.
    leave
    KErrNotFound The landmark database which should be set as default does not exist.
    ParameterDescription
    aDatabaseUriThe URI of the database which should be set as default.

    UnregisterAllDatabasesL ( const TDesC & )

    voidUnregisterAllDatabasesL(const TDesC &aProtocol)[pure virtual]

    Unregisters all landmark database which are accessed through a certain protocol.

    After this, the landmark databases are not be returned when listing landmark databases.

    For local landmark databases, this function leaves with error code KErrNotSupported. To remove a local database, the client must call DeleteDatabaseL .

    This function requires ReadUserData and WriteUserData capabilities.

    leave
    KErrNotSupported The protocol is not supported in the platform or the protocol does not allow unregistering landmark databases.
    leave
    KErrArgument The protocol is an empty string.
    ParameterDescription
    aProtocolThe protocol to unregister all databases for.

    UnregisterDatabaseL ( const TDesC & )

    voidUnregisterDatabaseL(const TDesC &aDatabaseUri)[pure virtual]

    Unregisters a landmark database.

    After this, the landmark database is not returned when listing landmark databases.

    For local landmark databases, this function leaves with error code KErrNotSupported. To remove a local database, the client must call DeleteDatabaseL .

    This function requires ReadUserData and WriteUserData capabilities.

    leave
    KErrNotSupported The protocol specified in the URI is not supported in the platform or the protocol does not allow unregistering landmark databases.
    leave
    KErrArgument The URI is incorrect.
    ParameterDescription
    aDatabaseUriThe URI of the database to register.
    © Nokia 2011.