/*

* 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:  A client interface for Mediator Server.

*

*/

#ifndef MEDIATORSERVERSESSION_H

#define MEDIATORSERVERSESSION_H

// INCLUDES

#include <e32base.h>

#include "MediatorCommon.h"

#include "MediatorServiceDefs.h"

// NAMESPACE

using namespace MediatorService;

/**

*  Client API for Mediator Server.

*

*  The Mediator Server is used to pass information between clients. The 

*  services of Mediator Server include passing events and passing commands with

*  respective responses. For events there can be multiple event providers and 

*  consumers. For commands there can be only one initiator and one responder.

*

*  The operations of Mediator server have the following hierarchy.

*  Domain -> Category -> Event/Command -> Data

*

*  The domain means the application domain, the purpose, for which the services 

*  of Mediator Server are used.

*

*  The category means the functionality area within the domain to which an event

*  or a command belongs to.

*

*  An event or a command is a message passed to Mediator server. Each message

*  may have data assosiated with it. For each command exactly one response shall 

*  be sent.

*

*  Before any messages can be sent to Mediator Server, the messages need to be

*  registered. When registering messages, the capabilities required to consume 

*  that message are defined. In case of commands timeout values for responses

*  are also defined.

*

*  @lib MediatorClient.lib

*  @since S60 3.1

*/

////////////////////////////////////////

//	class RMediatorServerSession

////////////////////////////////////////

NONSHARABLE_CLASS(RMediatorServer) : public RSessionBase

	{

    public:

        /**

        * Session constructor.

        */

	    RMediatorServer();

    public:

        /**

        * Creates a connection to server. If server is not started,

        * method will start the server first and then create a new session.

        * 

        * @since S60 3.1

        * @param none

        * @return TInt indicating the success of the call.

        */

        TInt Connect();

        /**

        * Closes the session to server

        * 

        * @since S60 3.1

        * @param none

        * @return None.

        */

        void Close();

        /**

        * Cancels all ongoing async operations

        * 

        * @since S60 3.1

        * @return None

        */                  

        void Cancel();

    public: // Mediator Service Registration API        

        /**

        * Registers an event list. After registering the list 

        * clients can provide and consume the events.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEvents    List of events to be registered

        * @return TInt      an error value.

        */

        TInt RegisterEventList( TUid aDomain,  

                                TUid aCategory, 

                                const REventList& aEvents );

        /**

        * Register a command list. After registering the list 

        * clients can initiate and respond the commands.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommands  List of commands to be registered

        * @return TInt      an error value.

        */

        TInt RegisterCommandList( TUid aDomain, 

                                  TUid aCategory, 

                                  const RCommandList& aCommands );

        /**

        * Unregister an event list. After unregistering no clients can consume

        * or provide these events.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEvents    List of events to be unregistered.

        * @return TInt      an error value.

        */

        TInt UnregisterEventList( TUid aDomain,  

                                  TUid aCategory,

                                  const REventList& aEvents );

        /**

        * Unregister a command list. After unregistering no clients can initiate

        * or respond to these events.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommands  List of commands to be unregistered.

        * @return TInt      an error value.

        */

        TInt UnregisterCommandList( TUid aDomain, 

                                    TUid aCategory,

                                    const RCommandList& aCommands );

    public: // Mediator Service Notification API - Event Provider   

        /**

        * Raise an event.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEventId   The identifier of the event.

        * @param aVersion   The version of the event.

        * @param aData      The parameters of the event.

        * @return TInt      an error value.

        */

        TInt RaiseEvent( TUid aDomain, 

                         TUid aCategory, 

                         TInt aEventId,

                         TVersion aVersion, 

                         const TDesC8& aData );

    public: // Mediator Service Notification API - Event Consumer

        /**

        * Subscribes a list of events. Raised events will be

        * delivered via the observer interface.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEvents    List of the events to be subscribed.

        * @return TInt      an error value.

        */

        TInt SubscribeEventList( TUid aDomain, 

                                 TUid aCategory, 

                                 const REventList& aEvents );

        /**

        * Unsubscribe an event list.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEvents    The list of events.

        * @return TInt      an error value.

        */

        TInt UnsubscribeEventList( TUid aDomain, 

                                   TUid aCategory, 

                                   const REventList& aEvents );

        /**

        * Unsubscribe an event.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEventId   The identifier of the event.

        * @return TInt      an error value.

        */

        TInt UnsubscribeEvent( TUid aDomain, TUid aCategory, TInt aEventId );

        /**

        * Start to receive events from Mediator Server

        * 

        * @since S60 3.1

        * @param aStatus            TRequestStatus of the AO to be completed when event occurs.

        * @param aCategoryBuffer    Category buffer.

        * @param aEventData         Pointer descriptor to buffer where event data is written.

        * @return TInt indicating the status of the operation

        */

        void ReceiveEvents( TRequestStatus& aStatus, 

                            TMediatorCategoryRetBuffer& aCategoryBuffer,

                            TEventRetBuffer& aEventBuffer,

                            TPtr8& aEventData );

    public: // Mediator Service Command API - Command Initiatior

        /**

        * Issue a command.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommandId The identifier of the command.

        * @param aVersion   The version of the command.

        * @param aData      The parameters of the command.        

        * @return TInt indicating the success of the call.

        */

        TInt IssueCommand( TUid aDomain,

                           TUid aCategory, 

                           TInt aCommandId,

                           TVersion aVersion, 

                           const TDesC8& aData );

        /**

        * Wait for command response.

        * 

        * @since S60 3.1

        * @param aStatus            TRequestStatus of the AO to be completed when command response is received.

        * @param aCategoryBuffer    Category buffer.

        * @param aCommandBuffer     Command buffer

        * @param aCommandData       Pointer descriptor to buffer where command data is written.

        * @param aStatusBuffer      Status buffer.

        * @return None.

        */                  

        void WaitForCommandResponse( TRequestStatus& aStatus,

                                     TMediatorCategoryRetBuffer& aCategoryBuffer,

                                     TCommandRetBuffer& aCommandBuffer,

                                     TPtr8& aCommandData,

                                     TPckg<TInt>& aStatusBuffer );

        /**

        * Cancel a command.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommandId The identifier of the command.        

        * @return TInt indicating the status of the call.

        */

        TInt CancelCommand( TUid aDomain, TUid aCategory, TInt aCommandId );

    public: // Mediator Service Command API - Command Responder

        /**

        * Issue a response to a command.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommandId The identifier of the command.

        * @param aStatus    Processing status of the command

        * @param aData      The parameters of the response.        

        * @return TInt indicating the status of the operation.

        */

        TInt IssueResponse( TUid aDomain, 

                            TUid aCategory, 

                            TInt aCommandId,

                            TInt aStatus,

                            const TDesC8& aData );

        /**

        * Get command requests.

        * 

        * @since S60 3.1

        * @param aCategoryBuffer    Category buffer.

        * @param aCommandBuffer     Command buffer

        * @param aCommandData       Pointer descriptor to buffer where command data is written.

        * @return TInt indicating the status of the operation.

        */                  

        void ReceiveCommands( TRequestStatus& aStatus,

                              TMediatorCategoryRetBuffer& aCategoryBuffer,

                              TCommandRetBuffer& aCommandBuffer,

                              TPtr8& aCommandData );

    public: // Mediator Service  - Notifications

        /**

        * Get registered domains

        * 

        * @since S60 3.1

        * @param aDomains   The list of registered domains.

        * @return TInt indicating the success of the call.

        */

        TInt GetDomains( RDomainList& aDomains );

        /**

        * Get registered categories for the domain

        * 

        * @since S60 3.1

        * @param aDomain        UID for the domain.

        * @param aCategories    List of registered categories within the domain.

        * @return TInt indicating the success of the call.

        */

        TInt GetCategories( TUid aDomain, RCategoryList& aCategories );

        /**

        * Get a list of registered events.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aEvents    The list of registered events for the category.

        * @return TInt indicating the status of the operation.

        */

        TInt GetEvents( TUid aDomain, 

                        TUid aCategory,

                        REventList& aEvents );

        /**

        * Get a list of registered commands.

        * 

        * @since S60 3.1

        * @param aDomain    The identifier of the domain.

        * @param aCategory  The identifier of the category.

        * @param aCommands  The list of registered commands for the category.

        * @return TInt indicating the status of the operation.

        */

        TInt GetCommands( TUid aDomain, 

                          TUid aCategory,

                          RCommandList& aCommands );

        /**

        * Get a list of registered commands.

        * 

        * @since S60 3.1

        * @param aStatus            TRequestStatus of the operation to be completed when notification is received.

        * @param aCategoryBuffer    Category buffer.

        * @param aTypeBuffer        Type buffer

        * @param aEventArrayPtr     Pointer descriptor to buffer where event data is written.

        * @param aCommandArrayPtr   Pointer descriptor to buffer where command data is written.

        * @return None.

        */                  

        void ReceiveNotifications( TRequestStatus& aStatus,

                                   TMediatorCategoryRetBuffer& aCategoryBuffer,

                                   TNotificationTypeRetBuffer& aTypeBuffer,

                                   TPtr8& aEventArrayPtr, 

                                   TPtr8& aCommandArrayPtr );

        /**

        * Get a list of registered commands.

        * 

        * @since S60 3.1

        * @return TInt indicating the status of the operation.

        */                  

        TInt CancelNotifications();

    public: // Mediator Service  - Common

        /**

        * Fetch parameter data, if data size was larger than default boundary.

        * 

        * @since S60 3.1

        * @param aParameterData pointer to data buffer where Mediator writes data

        * @return TInt indicating the status of the operation.

        */                  

        TInt FetchParameterData( TPtr8& aParameterData );

        /**

        * Fetch event list, if list size was larger than default boundary.

        * 

        * @since S60 3.1

        * @param aEventArrayPtr pointer to data buffer where Mediator writes data

        * @return TInt indicating the status of the operation.

        */  

        TInt FetchNotificationEventList( TPtr8& aEventArrayPtr );

        /**

        * Fetch command list, if list size was larger than default boundary.

        * 

        * @since S60 3.1

        * @param aCommandArrayPtr pointer to data buffer where Mediator writes data

        * @return TInt indicating the status of the operation.

        */  

        TInt FetchNotificationCommandList( TPtr8& aCommandArrayPtr );

    private:

        /**

        * Gets server version information.

        * @since S60 3.1

        * @param None

        * @return Version structure

        */

	    TVersion Version() const;

        /**

        * Server start function

        *

        * @since S60 3.1

        * @param None

        * @return KErrNone          server process was succesfully started

        *         KErrAlreadyExists server process was already running

        *         TInt              other system wide error code

        */

        TInt StartServer();

    private: // Data        

	};

#endif  // MEDIATORSERVERSESSION_H

// End of file