diff -r 000000000000 -r 4e1aa6a622a0 devicesrv_plat/dos_extension_api/inc/dossvrservices.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/devicesrv_plat/dos_extension_api/inc/dossvrservices.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,470 @@ +/* +* Copyright (c) 2002 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: +* This file contains the neccessary clases to access to the Dos Server +* Services. Client side API. +* +*/ + + +#ifndef __DOSSVRSERVICES_H__ +#define __DOSSVRSERVICES_H__ + +// INCLUDES +#include +#include +#include // TBTDevAddr, THCIConnHandle + +/** +* This represents parameter info and it is used when transfering +* paramenter data between client and server in case of extended +* functions i.e. usage of RDosExtension API. +*/ +struct TExtensionPar +{ + // Function flag used to identify between different RDosExtension + // function calls (multiple extensions are supported at the same time). + TInt iFunc; + + // Length or size of the parameter data. + // Can not be negative value, otherwise call to CallFunction will + // return KErrGeneral. + // Server needs to know the size to be able to allocate memory from heap. + TInt iParLength; + + // Auto complete flag. + // ETrue if the function is completed by the server, + // EFalse if it's gonna be completed by the DSY. + TBool iAutoComplete; +}; + +// Convenience type definitions to wrap package buffers: +typedef TPckgBuf TExtensionParPckg; + +/** +* This class represents a session with Dos Server and has some general +* purpose services. +*/ +class RDosServer : public RSessionBase +{ +public: + /** + * Starts the server. + * @return Symbian error code. + */ + IMPORT_C TInt StartServer() const; + + /** + * Connects and registers a session to ther server. + * If the server has not been started before a call to this function + * will start it. + * @return Symbian error code. + */ + IMPORT_C TInt Connect(); + + /** + * Closes the session. + */ + IMPORT_C void Close(); + + /** + * Shuts down the server. + */ + IMPORT_C void ServerShutdown() const; +}; + +/** +* This the base class for all the Dos Server subsessions. +*/ +class RDosSubSession : public RSubSessionBase +{ +public: + /** + * Closes the subsession. + */ + IMPORT_C void Close(); + +protected: + // Deprecated + TPtr8* NewPtr(TAny* aDataPtr,TInt aDataSize); + +protected: + RPointerArray* iParArray; +}; + +/** +* This subsession offers possibilities for licensees to extend the functionality of the +* dos server. +*/ +class RDosExtension : public RDosSubSession +{ +public: + /** + * Opens the subsession. + * @param aServer A connected session with the Server. + * @return Symbian error code. + */ + IMPORT_C TInt Open(RDosServer& aServer); + + //================================================ + // Subsession services + //================================================ + +protected: + /** + * Deprecated, please use the overloaded function taking descriptors; + * TInt CallFunction(const TExtensionParPckg& aParamInfo, TDes8& aParameter) + * + * Implements a synchronous raw function call that has to be implement in the Dsy plug-in. + * Internal implementation creates temporary descriptors and calls the overloaded + * CallFunction -function taking TExtensionParPckg and TDes8 parameters. + * @param aFunc Unique integer among the extended functions what function we are calling. + * @param aParameter A pointer to the parameter. + * @param aParLength Length of the parameter. + * @param aAutoComplete ETrue if the function is completed by the server, EFalse if it's gonna be completed + * in the plug-in. + * @return Symbian error code. + */ + IMPORT_C TInt CallFunction(TInt aFunc, TAny* aParameter=NULL, TInt aParLength=0,TBool aAutoComplete=ETrue); + + /** + * Implements a function call that has to be implement in the Dsy plug-in + * @param aParamInfo Package buffer containing parameter information (see TExtensionPar). + * @param aParameter Reference to a descriptor containing parameter data. + * @return Symbian error code. + */ + IMPORT_C TInt CallFunction(const TExtensionParPckg& aParamInfo, TDes8& aParameter); + + /** + * Implements an asynchronous raw function call that has to be implement in the Dsy plug-in + * @param aStatus Status variable to control the completion of the asynchronous request. + * @param aParamInfo Package buffer containing parameter information (see TExtensionPar). + * @param aParameter Reference to a descriptor containing parameter data. + * @return Symbian error code. + */ + IMPORT_C void CallFunction(TRequestStatus& aStatus, const TExtensionParPckg& aParamInfo, TDes8& aParameter); +}; + +/** +* This enumeration describes the different types of queues when registering for events. +*/ +enum TQueueType +{ + ENoQueue, //The incoming events when the client is busy will be discarded. + EQueue, //The incoming events when the client is busy will be queued. + EOnlyLast //Only the last incoming event will be queued when the client is busy, deleting the previous queued one. +}; + + +/** +* This type represents an event when the client registers for it. +*/ +struct TRegisterEvent +{ + // The unique identifier of the event. + TUint iEvent; + + // The size of the event's parameter. + TInt iParamSize; + + // The type of queue that the client wishes to have for the event. + TQueueType iQueue; +}; + +/** +* This subsession offers services to register and listen for events. +* It should not be used directly. Instead derive your class from CDosEventListenerBase +*/ +class RDosEventRcv : public RDosSubSession +{ +public: + /** + * Constructor + */ + RDosEventRcv(); + + /** + * Desctructor + */ + ~RDosEventRcv(); + + /** + * Opens the subsession. + * @param aServer A connected session with the Server. + * @return Symbian error code. + */ + TInt Open(RDosServer& aServer); + + /** + * Informs the server that the client wished to receive an event. + * @param aEvent The unique identifier of the event. + * @param aParamSize The size of the parameter that event is going to carry. + * @param aQueue The type of queue that the event is going to have. + * @return Symbian error code. + */ + TInt Register(TInt aEvent,TInt aParamSize,TQueueType aQueue); + + /** + * It asynchronously tells the server that the client doesn't wish to receive the event anymore. + */ + void UnRegister(); + + /** + * Puts the client to wait for the event. + * @param aStatus Status varibale that informs about the incoming events. + * @return Symbian error code. + */ + TInt WaitEvent(TRequestStatus& aStatus) const; + + /** + * Cancels outstanding requests. + * @return Symbian error code. + */ + TInt CancelWaitEvent() const; + + + /** + * Returns a pointer to the buffer containing the parameter that came with the latest received event. + * @return A pointer to the paramater buffer. + */ + inline HBufC8* Parameter() const; + + /** + * Returns the size of the parameter that came with the latest received event. + * @return Size of the parameter. + */ + inline TInt ParameterSize() const; + + /** + * Returns the type of queue that the event has. + * @return The type of queue. + */ + inline TQueueType Queue() const; + + /** + * Returns the unique id of the event that the object is listening for. + * @return An event identifier. + */ + inline TUint Event() const; + +private: + + // Pointer to the buffer containing the parameter of the latest received event. + HBufC8* iParamContent; + + //A Descriptor pointer pointing to iParamContent. + TPtr8* iContentPtr; + + //Indicates if the client has been already registerd or not. + TBool iRegistered; + + //Queue type for the event. + TQueueType iQueue; + + //The event. + TUint iDosEvent; +}; + +// +// Events Constants +// + +class CDosEventListenerBase; //Forward declaration + +/** +* This active object is used to wait for the event provided by the server throught the class RDosEventRcv. +* It is not recomended to use this class directly but instead use a derived class from CDosEventListenerBase. +*/ +class CDosEventNotifier : public CActive +{ +public: + /** + * Constructor. + * @param aListener A pointer to the CDosListenerBase-derived object that owns this object. + * @param aPriority The priority of the CActive object. + */ + CDosEventNotifier(CDosEventListenerBase* aListener,TPriority aPriority=EPriorityStandard); + + /** + * Destructor. + */ + ~CDosEventNotifier(); + + /** + * NewL that creates the object. + * @param aServer A connected session to the DosServer. + * @param aListener A pointer to the CDosListenerBase-derived object that owns this object. + * @return A pointer to the created CDosEventNotifier object. + */ + static CDosEventNotifier* NewL(RDosServer& aServer,CDosEventListenerBase* aListener); + + /** + * Registers the event in the Server and starts the listening for incoming events. + * @param aEvent Event to listen to. + * @param aParamSize Size of the parameter that the event is going to carry. + * @param aQueue Desired type of the event queue. + */ + void StartListeningL(TUint aEvent,TInt aParamSize,TQueueType aQueue); + +private: + /** + * Symbian two-phased constructor. + * @param aServer A connected session to the DosServer. + */ + void ConstructL(RDosServer& aServer); + +private: //Inherited from CActive + + /** + * It's called by CActive on error situations. + * @param aError Symbian error code. + * @return Returns KErrNone if the error was handled or aError otherwise. + */ + TInt RunError(TInt aError); + + /** + * It's called by CActive when the active object is scheduled to be executed. + */ + void RunL(); + + /** + * It's called by CActve when Cancel() is called and process the cancelation of the request. + */ + void DoCancel(); + +public: + // To part of a list of Notifiers + TSglQueLink iLink; +private: + //The RDosEventRcv subsession with the server. + RDosEventRcv iReceiver; + + //A pointer to the owner. + CDosEventListenerBase* iListener; +}; + + + +/** +* This class provides with services to listen for events. +* The class is intended for derivation. +* The derived class should override all the events that its objects are going to register to. +*/ +class CDosEventListenerBase : public CBase +{ +public: + /** + * Constructor. + * @param aServer A connected session to the DosServer. + */ + IMPORT_C CDosEventListenerBase(RDosServer& aServer); + + /** + * Constructor. It creates the sessions to the DosServer. + */ + IMPORT_C CDosEventListenerBase(); + + /** + * Destructor. + */ + IMPORT_C ~CDosEventListenerBase(); + + /** + * It registers the object to all the events contained in aEventArray. + * @param aEventArray An array of event for registration. + * @param aEventCount Number of events in the array. + */ + IMPORT_C void StartListeningL(TRegisterEvent* aEventArray, TInt aEventCount); + + /** + * It registers only one event. + * @param aEvent Unique Id of the event. + * @param aParamSize Size of the parameter that the event carries. + * @param aQueue Type of queue wished for the event. + */ + IMPORT_C void StartListeningL(TUint aEvent,TInt aParamSize=0, TQueueType aQueue=EQueue); + + /** + * Stops the listening. + */ + IMPORT_C void Stop(); + + /** + * The function gets called whenever an error occurs and it can be overrided by the derived class. + * @param aError Symbian error code. + * @param aStopListening Put this parameter as ETrue if you wish the Listener to stop listening for the event + * that caused the error. + */ + IMPORT_C virtual void OnError(TInt aError, TBool& aStopListening); + + /** + * Returns the session with the DosServer. + * @return A session with the DosServer. + */ + inline const RDosServer& DosServer() const; + +protected: + + //================================================ + // Events: To be overriden by the derived class + //================================================ + + /** + * This a raw event that is intended for expansion of the event functionality by licensees. + * @param aEvent The event. + * @param aParameter A pointer to the parameter. + */ + IMPORT_C virtual void GeneralEventL(const TRegisterEvent& aEvent,TAny* aParameter); + +private: + + /** + * This function handles the raw event and calls one of the "event functions". + * @param aEvent The event. + * @param aParameter A pointer to the parameter. + */ + void HandleEventL(const TRegisterEvent& aEvent,HBufC8* aParameter); + + /** + * Register the events and start listening for them. + */ + void RegisterAndListenL(); + +private: + friend class CDosEventNotifier; + +private: + //A list of notifiers listening to this event. + TSglQue iNotifierList; + + //The TSglQueIter class to browser iNotifierList. + TSglQueIter iNotifierIter; + + //A pointer to the event list. + TRegisterEvent* iEventList; + + //Number of events to listen to. + TInt iNotifierCount; + + //Session with the DosServer. + RDosServer iDosServer; + + //To check if the server was connected by this object + TBool iOwnServer; +}; + +#include "dossvrservices.inl" + + +#endif // __DOSSVRSERVICES_H__