/*
* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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:
*
* Description: Declaration of Client API for the landmark server.
*
*
*/


#ifndef RPOSLANDMARKSERVER_H
#define RPOSLANDMARKSERVER_H

//  INCLUDES
#include <e32base.h>
#include <badesca.h>
#include "EPos_TPosLmDatabaseEvent.h"
#include "EPos_TPosLmDatabaseSettings.h"
#include "EPos_HPosLmDatabaseInfo.h"

// FORWARD DECLARATIONS
class CPosLandmarkServerExtension;

// CLASS DECLARATION

/**
*  Client API for the landmark server.
*
*  @lib eposlmservlib.lib
*  @since S60 3.0
*  @version $Revision: 1.4 $, $Date: 2005/07/07 13:40:03 $
*/
class RPosLandmarkServer : public RSessionBase
    {
    public:  // Constructors and destructor

        /**
        * C++ default constructor.
        */
        IMPORT_C RPosLandmarkServer();

    public: // New functions


        /**
        * Connect to the landmark server.
        *
        * The server is started if it is not already running.
        *
        * This function requires @p ReadUserData capability.
        *
        * @since S60 3.0
        * @return @p KErrNone if successful, otherwise a system-wide error
        *   code.
        */
        IMPORT_C TInt Connect();

        /**
        * Closes the session to the server
        *
        * @since S60 3.0
        */
        IMPORT_C void Close();

        /**
        * Lists all URIs in the server's database registry for a certain
        * protocol.
        *
        * The client specifies a protocol string as input to this function.
        * The function only returns a list of the databases which are
        * accessed through this protocol.
        *
        * The client takes ownership of the returned array.
        *
        * This function requires @p ReadUserData capability.
        *
        * @since S60 3.0
        * @param aProtocol The protocol for which database URIs should be
        *   listed.
        * @return The list of database URIs.
        */
        IMPORT_C CDesCArray* ListDatabasesLC(
        /* IN  */       const TDesC& aProtocol
        );

        /**
        * Lists information about each landmark database in the
        * server's database registry.
        *
        * The client specifies a protocol string as input to this function.
        * The function 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.
        *
        * This function requires @p ReadUserData capability.
        *
        * @since S60 3.0
        * @param aDatabaseInfoArray On return, contains information about
        *   the landmark databases. Any objects which are in the array when
        *   it is passed to this function will be not be removed.
        * @param aProtocol The protocol for which database URIs should be
        *   listed.
        */
        IMPORT_C void ListDatabasesL(
        /* OUT */       RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,
        /* IN  */       const TDesC& aProtocol = KNullDesC
        );

        /**
        * Registers a landmark database.
        *
        * The landmark database is then returned when listing landmark
        * databases.
        *
        * 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 @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @since S60 3.0
        * @param aDatabaseInfo Information about the landmark database to
        *   register.
        * @return @p KErrNone if successful.\n
        *   @p KErrArgument if the URI is incorrect.\n
        *   @p KErrAlreadyExists if the database has already been registered.
        */
        IMPORT_C TInt RegisterDatabase(
        /* IN/OUT */       HPosLmDatabaseInfo& aDatabaseInfo
        );

        /**
        * Unregisters a landmark database.
        *
        * After this, the landmark database will not be returned when listing
        * landmark databases.
        *
        * If the database has not been registered, nothing happens.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @since S60 3.0
        * @param aDatabaseUri The URI of the database to unregister.
        * @param aDriveLetter The drive where the database resides. If
        *   drive is not applicable, 0 should be specified.
        * @return @p KErrNone if successful.\n
        *   @p KErrArgument if the URI is incorrect.
        */
        IMPORT_C TInt UnregisterDatabase(
        /* IN  */       const TDesC& aDatabaseUri,
        /* IN  */       TChar aDriveLetter = 0
        );

        /**
        * Unregisters all landmark databases which are accessed through a
        * certain protocol.
        *
        * After this, the landmark databases will not be returned when listing
        * landmark databases.
        *
        * If the protocol is not known or if there are no databases for
        * the protocol, nothing happens.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @since S60 3.0
        * @param aProtocol The protocol to unregister all databases for.
        * @return @p KErrNone if successful, otherwise a system-wide error
        *   code.
        */
        IMPORT_C TInt UnregisterAllDatabases(
        /* IN  */       const TDesC& aProtocol
        );

        /**
        * Modifies the settings for a landmark database.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @since S60 3.0
        * @param aDatabaseUri The URI of the database to modify settings for.
        * @param aDatabaseSettings The new settings for the database.
        * @param aDriveLetter The drive where the database resides. If
        *   drive is not applicable, 0 should be specified.
        * @return @p KErrNone if successful.\n
        *   @p KErrArgument if the URI is incorrect.\n
        *   @p KErrNotFound if the URI does not exist in the registry.
        */
        IMPORT_C TInt ModifyDatabaseSettings(
        /* IN  */       const TDesC& aDatabaseUri,
        /* IN  */       const TPosLmDatabaseSettings& aDatabaseSettings,
        /* IN  */       TChar aDriveLetter = 0
        );

        /**
        * Retrieve information about a landmark database.
        *
        * This function requires @p ReadUserData capability.
        *
        * @since S60 3.0
        * @param aDatabaseInfo An information object containing the URI of the
        *   landmark database. On return, the object contains information about
        *   the landmark database, including any database settings.
        * @return @p KErrNone if successful.\n
        *   @p KErrArgument if the URI is incorrect.\n
        *   @p KErrNotFound if the URI does not exist in the registry.
        */
        IMPORT_C TInt GetDatabaseInfo(
        /* IN/OUT */    HPosLmDatabaseInfo& aDatabaseInfo
        );

        /**
        * Reports a database management event.
        *
        * The event is distributed to all listening clients.
        *
        * A database URI can be specified to indicate which database the
        * event is about.
        *
        * This function requires @p ReadUserData and @p WriteUserData
        * capabilities.
        *
        * @since S60 3.0
        * @param aEvent Event information
        * @param aDatabaseUri The URI of the database which the event is about.
        * @return @p KErrNone if successful, otherwise a system-wide error
        *   code.
        */
        IMPORT_C TInt ReportEvent(
        /* IN  */       const TPosLmDatabaseEvent& aEvent,
        /* IN  */       const TDesC& aDatabaseUri = KNullDesC
        );

    private:

        HBufC8* SendMessageLC(
        /* IN  */       TInt aFunction,
        /* IN  */       const TDesC& aDes,
        /* IN  */       TInt aLength,
        /* IN/OUT */    TInt& aAllocLength
        );

        void PopulateArrayL(
        /* OUT */       RPointerArray<HPosLmDatabaseInfo>& aDatabaseInfoArray,
        /* IN  */       HBufC8* aBuffer
        );

        void PopulateArrayL(
        /* OUT */       CDesCArray* aArray,
        /* IN  */       HBufC8* aBuffer
        );

        void FreeResources();

        static void FreeRsc(TAny* aParam);
        /**
        * Starts the server.
        *
        * @return KErrNone on success, otherwise any system wide error.
        */
        TInt StartServer();

    private:    // Data

        CPosLandmarkServerExtension* iExtension;
    };

#endif      // RPOSLANDMARKSERVER_H

// End of File