/*

* 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 <e32base.h>

#include <psvariables.h>

#include <bttypes.h> // 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<TExtensionPar> 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<TPtr8>* 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<CDosEventNotifier> iNotifierList; 

	//The TSglQueIter class to browser iNotifierList.

    TSglQueIter<CDosEventNotifier> 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__