--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mediator/inc/Client/MediatorServerClient.h Tue Feb 02 00:53:00 2010 +0200
@@ -0,0 +1,449 @@
+/*
+* 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