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@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 williamr@2: #include williamr@2: #include williamr@2: 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: /** The Uid that identifies a screen change event. williamr@2: williamr@2: @see MEikSrvNotifierBase2::HandleSystemEventL() williamr@2: @internalTechnology */ williamr@2: const TUid KUidEventScreenModeChanged = {0x101F3648}; 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__