williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __EIKNOTAPI_H__
williamr@2: #define __EIKNOTAPI_H__
williamr@2: 
williamr@2: #include <e32std.h>
williamr@2: #include <e32base.h>
williamr@2: #include <f32file.h>
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <uikon/eikscchange.h>
williamr@4: #endif
williamr@4: 
williamr@2: /** Defines the second Uid value for plug in notifier DLLs. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: const TUid KUidNotifierPlugIn = {0x10005522}; 
williamr@2: const TUid KUidNotifierPlugInV2 = {0x101fdfae};
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: enum TEikNotExtStatus
williamr@2: 	{
williamr@2: 	EEikNotExtRequestCompleted = 0,
williamr@2: 	EEikNotExtRequestQueued = 1
williamr@2: 	};
williamr@2: 
williamr@2: /** A set of flags that define the capabilities of the notifier.
williamr@2: 
williamr@2: Capabilities are returned by calling MEikSrvNotifierBase2::NotifierCapabilites(). 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: enum TNotifierCapabilities
williamr@2: 	{
williamr@2: 	/** The notifier has no special capabilities. */
williamr@2: 	ENoSpecialCapabilities			= 0x00000000,
williamr@2: 	/** The notifier can handle a change to the screen device. */
williamr@2: 	EScreenDeviceChangeSupported	= 0x00000001,
williamr@2: 	};
williamr@2: 	
williamr@2: /** 
williamr@2: Interface to allow notifiers to manage their own startup/shutdown.  This class is likely to be of most
williamr@2: interest to notifiers that observe engines using publically available APIs rather than those that are run
williamr@2: via RNotifier.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released 
williamr@2: */
williamr@2: class MEikSrvNotifierManager
williamr@2: 	{
williamr@2: public:
williamr@2: 	virtual void StartNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
williamr@2: 	virtual void CancelNotifier(TUid aNotifierUid) = 0;
williamr@2: 	virtual void UpdateNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
williamr@2: protected:
williamr@2: 	IMPORT_C MEikSrvNotifierManager();
williamr@2: private:
williamr@2: 	IMPORT_C virtual void MEikSrvNotifierManager_Reserved1();
williamr@2: 	IMPORT_C virtual void MEikSrvNotifierManager_Reserved2();
williamr@2: private:
williamr@2: 	TInt iMEikSrvNotifierManager_Spare1;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /** Interface to a plug-in server side notifier.
williamr@2: 
williamr@2: Any number of MEikSrvNotifierBase2 objects can be included in a single DLL. 
williamr@2: All notifiers are loaded during device startup and are not destroyed until 
williamr@2: the Uikon server closes down.
williamr@2: 
williamr@2: All notifiers run in the uikon server thread so are able to directly access 
williamr@2: server side status panes but cannot call any functions on REikAppUiSession. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: class MEikSrvNotifierBase2
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Defines a set of notifier priorities. The use and application of these values 
williamr@2: 	is implementation-dependent. */
williamr@2: 	enum TNotifierPriority
williamr@2: 		{
williamr@2: 		/** The highest priority value. */
williamr@2: 		ENotifierPriorityAbsolute = 500,
williamr@2: 		/** The second highest priority value. */
williamr@2: 		ENotifierPriorityVHigh = 400,	
williamr@2: 		/** The third highest priority value. */
williamr@2: 		ENotifierPriorityHigh = 300,	
williamr@2: 		/** The fourth highest priority value. */
williamr@2: 		ENotifierPriorityLow = 200,	
williamr@2: 		/** The fifth highest priority value. */
williamr@2: 		ENotifierPriorityVLow = 100,	
williamr@2: 		/** The lowest priority value. */
williamr@2: 		ENotifierPriorityLowest = 0	
williamr@2: 		};
williamr@2: public:
williamr@2: 	/** Contains the notifier parameters.
williamr@2: 
williamr@2: 	@see TNotifierPriority */
williamr@2: 	class TNotifierInfo
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		/** The Uid that identifies the notifier. */
williamr@2: 		TUid iUid;
williamr@2: 		/** The Uid that identifies the channel to be used by the notifier (e.g. the screen, 
williamr@2: 		an LED etc) */
williamr@2: 		TUid iChannel;
williamr@2: 		/** The notifier priority, typically chosen from the standard set.
williamr@2: 	
williamr@2: 		@see TNotifierPriority */
williamr@2: 		TInt iPriority;
williamr@2: 		};
williamr@2: 
williamr@2: public:
williamr@2: 	IMPORT_C MEikSrvNotifierBase2();
williamr@2: 	IMPORT_C virtual ~MEikSrvNotifierBase2();
williamr@2: public:
williamr@2: 	/** Frees all resources owned by this notifier.
williamr@2: 	
williamr@2: 	This function is called by the notifier framework when all resources allocated 
williamr@2: 	by notifiers should be freed. As a minimum, this function should delete this 
williamr@2: 	object (i.e. delete this;).
williamr@2: 	
williamr@2: 	Note that it is important to implement this function correctly to avoid memory 
williamr@2: 	leaks. */
williamr@2: 	virtual void Release() = 0;
williamr@2: 	/** Performs any initialisation that this notifier may require.
williamr@2: 	
williamr@2: 	The function is called when the notifier is loaded (when the plug-in DLL is 
williamr@2: 	loaded). It is called only once.
williamr@2: 	
williamr@2: 	As a minimum, the function should return a TNotifierInfo instance describing 
williamr@2: 	the notifier parameters. A good implementation would be to set this into a 
williamr@2: 	data member, and then to return it. This is because the same information is 
williamr@2: 	returned by Info().
williamr@2: 	
williamr@2: 	The function is safe to leave from, so it is possible, although rarely necessary, 
williamr@2: 	to allocate objects as you would normally do in a ConstructL() function as 
williamr@2: 	part of two-phase construction.
williamr@2: 	
williamr@2: 	@return Describes the parameters of the notifier. */
williamr@2: 	virtual TNotifierInfo RegisterL() = 0;
williamr@2: 	/** Gets the notifier parameters.
williamr@2: 	
williamr@2: 	This is usually the same information as returned by RegisterL() but can be 
williamr@2: 	varied at run time.
williamr@2: 	
williamr@2: 	@return Describes the parameters of the notifier. */
williamr@2: 	virtual TNotifierInfo Info() const = 0;
williamr@2: 	/** Starts the notifier.
williamr@2: 	
williamr@2: 	This is called as a result of a client-side call to RNotifier::StartNotifier(), 
williamr@2: 	which the client uses to start a notifier from which it does not expect a 
williamr@2: 	response.
williamr@2: 	
williamr@2: 	The function is synchronous, but it should be implemented so that it completes 
williamr@2: 	as soon as possible, allowing the notifier framework to enforce its priority 
williamr@2: 	mechanism.
williamr@2: 	
williamr@2: 	It is not possible to to wait for a notifier to complete before returning 
williamr@2: 	from this function unless the notifier is likely to finish implementing its 
williamr@2: 	functionality immediately.
williamr@2: 	
williamr@2: 	@param aBuffer Data that can be passed from the client-side. The format and 
williamr@2: 	meaning of any data is implementation dependent.
williamr@2: 	@return A pointer descriptor representing data that may be returned. The format 
williamr@2: 	and meaning of any data is implementation dependent. */
williamr@2: 	virtual TPtrC8 StartL(const TDesC8& aBuffer) = 0;
williamr@2: 	/** Starts the notifier.
williamr@2: 	
williamr@2: 	This is called as a result of a client-side call to the asynchronous function 
williamr@2: 	RNotifier::StartNotifierAndGetResponse(). This means that the client is waiting, 
williamr@2: 	asynchronously, for the notifier to tell the client that it has finished its 
williamr@2: 	work.
williamr@2: 	
williamr@2: 	It is important to return from this function as soon as possible, and derived 
williamr@2: 	classes may find it useful to take a copy of the reply-slot number and 
williamr@2: 	the RMessage object.
williamr@2: 	
williamr@2: 	The implementation of a derived class must make sure that Complete() is called 
williamr@2: 	on the RMessage object when the notifier is deactivated.
williamr@2: 	
williamr@2: 	This function may be called multiple times if more than one client starts 
williamr@2: 	the notifier.
williamr@2: 	
williamr@2: 	@param aBuffer Data that can be passed from the client-side. The format and 
williamr@2: 	meaning of any data is implementation dependent.
williamr@2: 	@param aReplySlot Identifies which message argument to use for the reply.
williamr@2:     This message argument will refer to a modifiable descriptor, a TDes8 type, 
williamr@2: 	into which data can be returned. The format and meaning of any returned data 
williamr@2: 	is implementation dependent.
williamr@2: 	@param aMessage Encapsulates a client request. */
williamr@2: 	virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage) = 0;
williamr@2: 	
williamr@2: 	/** Cancels an active notifier.
williamr@2: 	
williamr@2: 	This is called as a result of a client-side call to RNotifier::CancelNotifier().
williamr@2: 	
williamr@2: 	An implementation should free any relevant resources and complete any outstanding 
williamr@2: 	messages, if relevant. */
williamr@2: 	virtual void Cancel() = 0;
williamr@2: 	/** Updates a currently active notifier with new data.
williamr@2: 	
williamr@2: 	This is called as a result of a client-side call to RNotifier::UpdateNotifier().
williamr@2: 	
williamr@2: 	@param aBuffer Data that can be passed from the client-side. The format and 
williamr@2: 	meaning of any data is implementation dependent.
williamr@2: 	@return A pointer descriptor representing data that may be returned. The format 
williamr@2: 	and meaning of any data is implementation dependent. */
williamr@2: 	virtual TPtrC8 UpdateL(const TDesC8& aBuffer) = 0;
williamr@2: 	/** Updates a currently active notifier with new data.
williamr@2: 	
williamr@2: 	This is called as a result of a client-side call to the asynchronous function 
williamr@2: 	RNotifier::UpdateNotifierAndGetResponse(). This means that the client is waiting, 
williamr@2: 	asynchronously, for the notifier to tell the client that it has finished its 
williamr@2: 	work.
williamr@2: 	
williamr@2: 	It is important to return from this function as soon as possible, and derived 
williamr@2: 	classes may find it useful to take a copy of the reply-slot number and 
williamr@2: 	the RMessage object.
williamr@2: 	
williamr@2: 	The implementation of a derived class must make sure that Complete() is called 
williamr@2: 	on the RMessage object when the notifier is deactivated.
williamr@2: 	
williamr@2: 	This function may be called multiple times if more than one client updates 
williamr@2: 	the notifier.
williamr@2: 	
williamr@2: 	@param aBuffer Data that can be passed from the client-side. The format and 
williamr@2: 	meaning of any data is implementation dependent.
williamr@2: 	@param aReplySlot Identifies which message argument to use for the reply.
williamr@2:     This message argument will refer to a modifiable descriptor, a TDes8 type, 
williamr@2: 	into which data can be returned. The format and meaning of any returned data 
williamr@2: 	is implementation dependent.
williamr@2: 	@param aMessage Encapsulates a client request. */
williamr@2: 	IMPORT_C virtual void UpdateL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
williamr@2: public:
williamr@2: 	void SetManager(MEikSrvNotifierManager* aManager);
williamr@2: protected:
williamr@2: 	MEikSrvNotifierManager* iManager;
williamr@2: private:
williamr@2: 	IMPORT_C virtual void MEikSrvNotifierBase2_Reserved_2();
williamr@2: public:	// internal
williamr@2: 	IMPORT_C virtual void HandleSystemEventL(TUid aEvent);
williamr@2: 	IMPORT_C virtual TInt NotifierCapabilites();
williamr@2: private:
williamr@2: 	TInt iNotBSpare;
williamr@2: 	TInt iMEikSrvNotifierBase2_Spare;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: #endif	// __EIKNOTAPI_H__