1.1 --- a/epoc32/include/eiknotapi.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,270 +0,0 @@
1.4 -// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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
1.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -//
1.18 -
1.19 -#ifndef __EIKNOTAPI_H__
1.20 -#define __EIKNOTAPI_H__
1.21 -
1.22 -#include <e32std.h>
1.23 -#include <e32base.h>
1.24 -#include <f32file.h>
1.25 -
1.26 -/** Defines the second Uid value for plug in notifier DLLs.
1.27 -
1.28 -@publishedAll
1.29 -@released */
1.30 -const TUid KUidNotifierPlugIn = {0x10005522};
1.31 -const TUid KUidNotifierPlugInV2 = {0x101fdfae};
1.32 -
1.33 -/**
1.34 -@publishedAll
1.35 -@released
1.36 -*/
1.37 -enum TEikNotExtStatus
1.38 - {
1.39 - EEikNotExtRequestCompleted = 0,
1.40 - EEikNotExtRequestQueued = 1
1.41 - };
1.42 -
1.43 -/** The Uid that identifies a screen change event.
1.44 -
1.45 -@see MEikSrvNotifierBase2::HandleSystemEventL()
1.46 -@internalTechnology */
1.47 -const TUid KUidEventScreenModeChanged = {0x101F3648};
1.48 -
1.49 -/** A set of flags that define the capabilities of the notifier.
1.50 -
1.51 -Capabilities are returned by calling MEikSrvNotifierBase2::NotifierCapabilites().
1.52 -
1.53 -@publishedAll
1.54 -@released */
1.55 -enum TNotifierCapabilities
1.56 - {
1.57 - /** The notifier has no special capabilities. */
1.58 - ENoSpecialCapabilities = 0x00000000,
1.59 - /** The notifier can handle a change to the screen device. */
1.60 - EScreenDeviceChangeSupported = 0x00000001,
1.61 - };
1.62 -
1.63 -/**
1.64 -Interface to allow notifiers to manage their own startup/shutdown. This class is likely to be of most
1.65 -interest to notifiers that observe engines using publically available APIs rather than those that are run
1.66 -via RNotifier.
1.67 -
1.68 -@publishedAll
1.69 -@released
1.70 -*/
1.71 -class MEikSrvNotifierManager
1.72 - {
1.73 -public:
1.74 - virtual void StartNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
1.75 - virtual void CancelNotifier(TUid aNotifierUid) = 0;
1.76 - virtual void UpdateNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
1.77 -protected:
1.78 - IMPORT_C MEikSrvNotifierManager();
1.79 -private:
1.80 - IMPORT_C virtual void MEikSrvNotifierManager_Reserved1();
1.81 - IMPORT_C virtual void MEikSrvNotifierManager_Reserved2();
1.82 -private:
1.83 - TInt iMEikSrvNotifierManager_Spare1;
1.84 - };
1.85 -
1.86 -
1.87 -/** Interface to a plug-in server side notifier.
1.88 -
1.89 -Any number of MEikSrvNotifierBase2 objects can be included in a single DLL.
1.90 -All notifiers are loaded during device startup and are not destroyed until
1.91 -the Uikon server closes down.
1.92 -
1.93 -All notifiers run in the uikon server thread so are able to directly access
1.94 -server side status panes but cannot call any functions on REikAppUiSession.
1.95 -
1.96 -@publishedAll
1.97 -@released */
1.98 -class MEikSrvNotifierBase2
1.99 - {
1.100 -public:
1.101 - /** Defines a set of notifier priorities. The use and application of these values
1.102 - is implementation-dependent. */
1.103 - enum TNotifierPriority
1.104 - {
1.105 - /** The highest priority value. */
1.106 - ENotifierPriorityAbsolute = 500,
1.107 - /** The second highest priority value. */
1.108 - ENotifierPriorityVHigh = 400,
1.109 - /** The third highest priority value. */
1.110 - ENotifierPriorityHigh = 300,
1.111 - /** The fourth highest priority value. */
1.112 - ENotifierPriorityLow = 200,
1.113 - /** The fifth highest priority value. */
1.114 - ENotifierPriorityVLow = 100,
1.115 - /** The lowest priority value. */
1.116 - ENotifierPriorityLowest = 0
1.117 - };
1.118 -public:
1.119 - /** Contains the notifier parameters.
1.120 -
1.121 - @see TNotifierPriority */
1.122 - class TNotifierInfo
1.123 - {
1.124 - public:
1.125 - /** The Uid that identifies the notifier. */
1.126 - TUid iUid;
1.127 - /** The Uid that identifies the channel to be used by the notifier (e.g. the screen,
1.128 - an LED etc) */
1.129 - TUid iChannel;
1.130 - /** The notifier priority, typically chosen from the standard set.
1.131 -
1.132 - @see TNotifierPriority */
1.133 - TInt iPriority;
1.134 - };
1.135 -
1.136 -public:
1.137 - IMPORT_C MEikSrvNotifierBase2();
1.138 - IMPORT_C virtual ~MEikSrvNotifierBase2();
1.139 -public:
1.140 - /** Frees all resources owned by this notifier.
1.141 -
1.142 - This function is called by the notifier framework when all resources allocated
1.143 - by notifiers should be freed. As a minimum, this function should delete this
1.144 - object (i.e. delete this;).
1.145 -
1.146 - Note that it is important to implement this function correctly to avoid memory
1.147 - leaks. */
1.148 - virtual void Release() = 0;
1.149 - /** Performs any initialisation that this notifier may require.
1.150 -
1.151 - The function is called when the notifier is loaded (when the plug-in DLL is
1.152 - loaded). It is called only once.
1.153 -
1.154 - As a minimum, the function should return a TNotifierInfo instance describing
1.155 - the notifier parameters. A good implementation would be to set this into a
1.156 - data member, and then to return it. This is because the same information is
1.157 - returned by Info().
1.158 -
1.159 - The function is safe to leave from, so it is possible, although rarely necessary,
1.160 - to allocate objects as you would normally do in a ConstructL() function as
1.161 - part of two-phase construction.
1.162 -
1.163 - @return Describes the parameters of the notifier. */
1.164 - virtual TNotifierInfo RegisterL() = 0;
1.165 - /** Gets the notifier parameters.
1.166 -
1.167 - This is usually the same information as returned by RegisterL() but can be
1.168 - varied at run time.
1.169 -
1.170 - @return Describes the parameters of the notifier. */
1.171 - virtual TNotifierInfo Info() const = 0;
1.172 - /** Starts the notifier.
1.173 -
1.174 - This is called as a result of a client-side call to RNotifier::StartNotifier(),
1.175 - which the client uses to start a notifier from which it does not expect a
1.176 - response.
1.177 -
1.178 - The function is synchronous, but it should be implemented so that it completes
1.179 - as soon as possible, allowing the notifier framework to enforce its priority
1.180 - mechanism.
1.181 -
1.182 - It is not possible to to wait for a notifier to complete before returning
1.183 - from this function unless the notifier is likely to finish implementing its
1.184 - functionality immediately.
1.185 -
1.186 - @param aBuffer Data that can be passed from the client-side. The format and
1.187 - meaning of any data is implementation dependent.
1.188 - @return A pointer descriptor representing data that may be returned. The format
1.189 - and meaning of any data is implementation dependent. */
1.190 - virtual TPtrC8 StartL(const TDesC8& aBuffer) = 0;
1.191 - /** Starts the notifier.
1.192 -
1.193 - This is called as a result of a client-side call to the asynchronous function
1.194 - RNotifier::StartNotifierAndGetResponse(). This means that the client is waiting,
1.195 - asynchronously, for the notifier to tell the client that it has finished its
1.196 - work.
1.197 -
1.198 - It is important to return from this function as soon as possible, and derived
1.199 - classes may find it useful to take a copy of the reply-slot number and
1.200 - the RMessage object.
1.201 -
1.202 - The implementation of a derived class must make sure that Complete() is called
1.203 - on the RMessage object when the notifier is deactivated.
1.204 -
1.205 - This function may be called multiple times if more than one client starts
1.206 - the notifier.
1.207 -
1.208 - @param aBuffer Data that can be passed from the client-side. The format and
1.209 - meaning of any data is implementation dependent.
1.210 - @param aReplySlot Identifies which message argument to use for the reply.
1.211 - This message argument will refer to a modifiable descriptor, a TDes8 type,
1.212 - into which data can be returned. The format and meaning of any returned data
1.213 - is implementation dependent.
1.214 - @param aMessage Encapsulates a client request. */
1.215 - virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage) = 0;
1.216 -
1.217 - /** Cancels an active notifier.
1.218 -
1.219 - This is called as a result of a client-side call to RNotifier::CancelNotifier().
1.220 -
1.221 - An implementation should free any relevant resources and complete any outstanding
1.222 - messages, if relevant. */
1.223 - virtual void Cancel() = 0;
1.224 - /** Updates a currently active notifier with new data.
1.225 -
1.226 - This is called as a result of a client-side call to RNotifier::UpdateNotifier().
1.227 -
1.228 - @param aBuffer Data that can be passed from the client-side. The format and
1.229 - meaning of any data is implementation dependent.
1.230 - @return A pointer descriptor representing data that may be returned. The format
1.231 - and meaning of any data is implementation dependent. */
1.232 - virtual TPtrC8 UpdateL(const TDesC8& aBuffer) = 0;
1.233 - /** Updates a currently active notifier with new data.
1.234 -
1.235 - This is called as a result of a client-side call to the asynchronous function
1.236 - RNotifier::UpdateNotifierAndGetResponse(). This means that the client is waiting,
1.237 - asynchronously, for the notifier to tell the client that it has finished its
1.238 - work.
1.239 -
1.240 - It is important to return from this function as soon as possible, and derived
1.241 - classes may find it useful to take a copy of the reply-slot number and
1.242 - the RMessage object.
1.243 -
1.244 - The implementation of a derived class must make sure that Complete() is called
1.245 - on the RMessage object when the notifier is deactivated.
1.246 -
1.247 - This function may be called multiple times if more than one client updates
1.248 - the notifier.
1.249 -
1.250 - @param aBuffer Data that can be passed from the client-side. The format and
1.251 - meaning of any data is implementation dependent.
1.252 - @param aReplySlot Identifies which message argument to use for the reply.
1.253 - This message argument will refer to a modifiable descriptor, a TDes8 type,
1.254 - into which data can be returned. The format and meaning of any returned data
1.255 - is implementation dependent.
1.256 - @param aMessage Encapsulates a client request. */
1.257 - IMPORT_C virtual void UpdateL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
1.258 -public:
1.259 - void SetManager(MEikSrvNotifierManager* aManager);
1.260 -protected:
1.261 - MEikSrvNotifierManager* iManager;
1.262 -private:
1.263 - IMPORT_C virtual void MEikSrvNotifierBase2_Reserved_2();
1.264 -public: // internal
1.265 - IMPORT_C virtual void HandleSystemEventL(TUid aEvent);
1.266 - IMPORT_C virtual TInt NotifierCapabilites();
1.267 -private:
1.268 - TInt iNotBSpare;
1.269 - TInt iMEikSrvNotifierBase2_Spare;
1.270 - };
1.271 -
1.272 -
1.273 -#endif // __EIKNOTAPI_H__