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