1 /*

     2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   This module defines the API to get services from EventMediator.

    15 *

    16 */

    17 

    18 

    19 

    20 /**  

    21  * @file eventmediatorapi.h

    22  *

    23  * This module defines the API to get services from EventMediator.

    24  *

    25  */

    26 

    27 #ifndef __EVENTMEDIATOR_API_H__

    28 #define __EVENTMEDIATOR_API_H__

    29 

    30 #include <es_enum.h>

    31 #include "vpnapidefs.h"

    32 #include "vpnmandefs.h"

    33 

    34 #define EVENTLOG_FILE_HEADER_LTH     16

    35 

    36 /**

    37  *

    38  *  Enumeration of supported events types.

    39  *

    40  */

    41 enum TEventType

    42     {

    43     EUnfoundEvent,

    44     ETestEvent,

    45     ESystemEvents = 10000,

    46     EAllInterfaceEvents,

    47     ESingleInterfaceEvent,

    48     ELogEvent,

    49     EKmdAddressChangeEvent,

    50     EKmdCertificateChangeEvent,

    51     EKmdRealIapConnDownEvent,

    52     // SIT events

    53     EGetProtocolVersionEvent = 20000,

    54     EStartVpnConnEvent,

    55     ECloseVpnConnEvent,

    56     EStartRealIapConnEvent,

    57     EObserveRealIapConnEvent,

    58     // Internal use only

    59     ETaskArrivedEvent = 30000,

    60     EFetchTaskInfoEvent,

    61     EGetProtocolVersionCancelEvent, 

    62     EStartVpnConnCancelEvent,

    63     ECloseVpnConnCancelEvent,

    64     EStartRealIapConnCancelEvent,

    65     EObserveRealIapConnCancelEvent,

    66     EProgressEvent

    67     };

    68 

    69 /**

    70  *

    71  *  Enumeration of log event categories.

    72  *

    73  */

    74 enum TLogCategory

    75     {

    76     EInfo,

    77     EWarning,

    78     EError,

    79     EDebug

    80     };

    81 

    82 /**

    83  * The following definitions are used with TEventType

    84  * ESingleInterfaceEvent and EObserveRealIapConnEvent

    85  */

    86 

    87 enum TSingleConnInterfaceState

    88     {

    89     ESingleInterfaceStateUnknown = -1, 

    90     ESingleInterfaceUp,

    91     ESingleInterfaceDown,

    92     ESingleInterfaceTerminated, // Authoritative stop

    93     };

    94 

    95 class TSingleInterfaceNotification

    96     {

    97 public:

    98     TConnectionInfo iConnectionInfo;

    99     TSingleConnInterfaceState iState;

   100     };

   101 

   102 typedef TPckgBuf<TSingleInterfaceNotification> TSingleInterfaceNotificationBuf;

   103 

   104 /**

   105  * Generic event data definition

   106  */

   107 class TEventSpec

   108     {

   109 public:

   110     inline TEventSpec() : iId(0) {}

   111     TInt iId;

   112     };

   113 

   114 /**

   115  * Generic event data definition

   116  */

   117 class TEventData

   118     {

   119 public:

   120     inline TEventData() : iTaskStatus(KErrNone) {}

   121     TInt iTaskStatus;

   122     };

   123 

   124 /**

   125  * Used by SIT to get informed about new tasks.

   126  */

   127 class TTaskArrivedEventData

   128     {

   129 public:

   130     inline TTaskArrivedEventData()

   131         :iEventType(EUnfoundEvent), iEventSpecId(0)

   132         {}

   133     TEventType iEventType;

   134     TInt iEventSpecId;

   135     };

   136 

   137 /**

   138  * Used by SIT to fetch the event specification of a new task.

   139  */

   140 typedef TTaskArrivedEventData TFetchTaskInfoEventSpec;

   141 

   142 /**

   143  *

   144  *  MEventObserver - This class must be implemented to use ListenToEvent of EventMediatorApi

   145  *

   146  */

   147 class MEventObserver

   148     {

   149 public:

   150     /**

   151      * Called by REventMediator when a listened event has been reported.

   152      * @param aStatus: error code, KErrNone if successfull.

   153      * @param aType: the type of the event.

   154      * @param aData: a pointer to a descriptor containing reported data about the event.

   155      * aData pointer is valid only during the execution of EventOccured.

   156      * A copy of the descriptor must be made to store the data for later use.

   157      */

   158     virtual void EventOccured(TInt aStatus, TEventType aType, TDesC8* aData)=0;

   159     };

   160 

   161 class CEventListener;

   162 

   163 /**

   164  *

   165  *  REventMediator - API class for EventMediator 

   166  *

   167  */

   168 class REventMediator:public RSessionBase

   169     {

   170 /**

   171  ** @internalComponent

   172  */

   173     friend class CEventListener;

   174 public:

   175     /**

   176      * Default constructor

   177      */

   178     IMPORT_C REventMediator(void);

   179 

   180     /**

   181      * Creates session to the EventMediator server. If server is

   182      * not running, it is started.

   183      */

   184     IMPORT_C TInt Connect();

   185 

   186     /**

   187      * Closes the session to the VPN Manager.

   188      */

   189     IMPORT_C void Close();  

   190 

   191     /**

   192      * Sends asynchronous event notification request.

   193      * Called after Connect() request.

   194      * @param aType: the type of the event.

   195      * @param aObserver: object whose EventOccured method is called when an event

   196      * of type aType has been reported.

   197      */

   198     IMPORT_C void ListenToEvent(TEventType aType, MEventObserver& aObserver);

   199 

   200     /**

   201      * Sends asynchronous event notification request.

   202      * Called after Connect() request.

   203      * @param aType: the type of the event.

   204      * @param aEventSpec: specific info on listened event.

   205      * @param aObserver: object whose EventOccured method is called when an event

   206      * of type aType has been reported.

   207      */

   208     IMPORT_C void ListenToEvent(TEventType aType, TDesC8& aEventSpec, MEventObserver& aObserver);

   209 

   210     /**

   211      * Cancels all ListenToEvent requests concerning this event type.

   212      * Called after Connect() request.

   213      * @param aType: the type of the event.

   214      */

   215     IMPORT_C void CancelListening(TEventType aType);

   216 

   217     /**

   218      * Cancels ListenToEvent request geiven with a specification. 

   219      * Notice that this may fail.

   220      * Called after Connect() request.

   221      * @param aEventSpec: specific info on listened event.

   222      * @param aType: the type of the event.

   223      * @return error code, KErrNone if successfull.

   224      */

   225     IMPORT_C TInt CancelListening(TEventType aType, TDesC8& aEventSpec);

   226 

   227     /**

   228      * Cancels all asynchronous ListenToEvent requests.

   229      * Called after Connect() request.

   230      */

   231     IMPORT_C void CancelAllListening();

   232 

   233     /**

   234      * Sends synchronous request to report an event.

   235      * Called after Connect() request.

   236      * @param aType: the type of the event.

   237      * @param aData: a descriptor containing data about the event.

   238      * @return error code, KErrNone if successfull.

   239      */

   240     IMPORT_C TInt ReportEvent(TEventType aType);

   241 

   242     /**

   243      * Sends synchronous request to report an event.

   244      * Called after Connect() request.

   245      * @param aType: the type of the event.

   246      * @param aData: a descriptor containing data about the event.

   247      * @return error code, KErrNone if successfull.

   248      */

   249     IMPORT_C TInt ReportEvent(TEventType aType, TDesC8& aData);

   250 

   251     /**

   252      * Sends synchronous request to report an event.

   253      * Called after Connect() request.

   254      * @param aType: the type of the event.

   255      * @param aEventSpec: specific info on listened event.

   256      * @param aData: a descriptor containing data about the event.

   257      * @return error code, KErrNone if successfull.

   258     */

   259     IMPORT_C TInt ReportEvent(TEventType aType, TDesC8& aEventSpec, TDesC8& aData);

   260 

   261      /**

   262      * Sends synchronous request to report an event.

   263      * Called after Connect() request.

   264      * @param aTSrc: source of the event.

   265      * @param aCategory: category of the log event.

   266      * @param aMsgId: Id of the log message.

   267      * @param aDesCount: number of additional arguments (which must be of type TDesC8*).

   268      * @return error code, KErrNone if successfull.

   269      */

   270     IMPORT_C TInt ReportLogEvent(TUid& aSrc, TLogCategory aCategory, TUint aMsgId,TInt aDesCount,...);

   271 

   272      /**

   273      * Returns a new event specification

   274      * ID to be used with SIT related events.

   275      */

   276     IMPORT_C TInt NewEventSpecId();

   277 

   278      /**

   279      * Requests the Event Mediator to delete the files it owns.

   280      */

   281     IMPORT_C TInt DeletePrivateFiles();

   282 

   283     IMPORT_C TInt GetEventLogSize(TInt& aEventLogSize);

   284 

   285     IMPORT_C TInt GetEventLogHeader(TDes8& aEventLogHeader);

   286 

   287     IMPORT_C TInt GetEventLogData(TDes8& aEventLogData);

   288 

   289     IMPORT_C TInt ClearEventLog();

   290 

   291     /**

   292      * Sends a request to cancel all ListenToEvent requests concerning this

   293      * event type.

   294      * @param aType: the type of the event.

   295      */

   296     void CancelListenToEvent(TEventType aType);

   297 

   298     /**

   299      * Sends a request to cancel all ListenToEvent requests with a given

   300      * specification. 

   301      * @param aEventSpec: specific info on listened event.

   302      * @param aType: the type of the event.

   303      * @return error code, KErrNone if successfull.

   304      */

   305     TInt CancelListenToEvent(TEventType aType, TDesC8& aEventSpec);

   306 

   307 private:

   308     void CreateListenedEventsListL();

   309     

   310     /**

   311      * Sends synchronous request to get data repeorted with an event.

   312      * Called after Connect() request.

   313      * @param aSrvPtr: pointer to the data in the servers address space.

   314      * The server checks whether this pointer is valid before using it.

   315      * @param aData: a descriptor to which the datais written.

   316      * @return Error status

   317      */

   318     TInt FetchData(TAny* aSrvPtr, TDes8& aDataDecriptor);

   319 

   320     /**

   321      * Called by ListenToEvent function.

   322      * Creates a new instance of CEventListener to receive notification about the event.

   323      * Adds thsi object to iListenedEvents.

   324      * @param aType: the type of the event.

   325      * @param aObserver: object whose EventOccured function is called when event is received.

   326      * @return the new listener.

   327      */

   328     CEventListener* NewEventListenerL(TEventType aType, MEventObserver& aObserver);

   329 

   330     /**

   331      * Deletes listener created with NewEventListener

   332      * @param aType: the type of the event.

   333      */

   334     void RemoveListener(CEventListener* aListener);

   335 

   336     /**

   337      * Creates EventMediator.

   338      */

   339     TInt StartEventMediator();

   340 

   341     /**

   342      * Looks up a listener from iListenedEvents.

   343      * @param aType: type of the event the listener is waiting for.

   344      * @param aIndex: the position of the listener in iListenedEvents.

   345      * @return ETrue if listener exists, EFalse if not.

   346      */

   347     TBool FindEventListener(const TEventType aType, TInt& aIndex);

   348     

   349     /**

   350      * Looks up a listener from iListenedEvents.

   351      * @param aType: type of the event the listener is waiting for.

   352      * @param aEventSpec event specification

   353      * @param aIndex: the position of the listener in iListenedEvents.

   354      * @return ETrue if listener exists, EFalse if not.

   355      */

   356     TBool FindEventListener(const TEventType aType, TDesC8& aEventSpec, TInt& aIndex);

   357 

   358     /**

   359      * Reads the variable arguments of ReportLogEvent.

   360      * @param aCount: Number of arguments.

   361      * @param aList: list of arguments.

   362      * @param aPointers: array to be filled with argument pointers.

   363      * @param aLengths: array to be filled with argument lengths.

   364      * @param aOverAllLength: sum of argument lengths

   365      * @return error code, KErrNone if successfull.

   366      */

   367     TInt ReadLogArguments(TInt aCount, VA_LIST aList,TDesC8** aPointers, TInt* aLengths, TInt& aOverAllLength);

   368     

   369 private: //Data

   370     // list of listeners created with function NewEventListener 

   371     CArrayFixFlat<CEventListener*>* iListenedEvents;

   372     TInt64 iRandSeed;

   373     };

   374 

   375 /**

   376  *

   377  *  CEventListener - A class used by REventListener to Store information about the listened events.

   378  *

   379  */

   380 NONSHARABLE_CLASS(CEventListener) : public CActive

   381     {

   382 /**

   383  ** @internalComponent

   384  */

   385     friend class REventMediator;

   386     enum TListenerState { EStateListening = 0, EStateFetchingData};

   387 public:

   388     /**

   389      * standard deconstructor

   390      */

   391     ~CEventListener();

   392 private:

   393     /**

   394      * Constructor.

   395      * @param aType: type of the event that is listened.

   396      * @param aObserver: object whose EventOccured is called when event has occured.

   397      * @param aSession: pointer to the owning REventMediator object.

   398      */

   399     CEventListener(TEventType aType, MEventObserver& aObserver, REventMediator* aSession);

   400 

   401     /**

   402      * Implement RunL of class CActive.

   403      */

   404     void RunL();

   405 

   406     /**

   407      * Handles the completion of event listening request

   408      */

   409     void HandleListeningComplete();

   410 

   411     /**

   412      * Handles the completion of event data fetching request

   413      * @param Error status

   414      */

   415     void HandleFetchingComplete(TInt aError);

   416 

   417     /**

   418      * Implements DoCancel of class CActive.

   419      */

   420     void DoCancel();

   421 

   422 private: //data

   423     // buffer to receive the length of the data descriptor of an reported event.

   424     TPckgBuf<TInt> iDataLengthPckg;

   425     // buffer to receive the pointer to the data descriptor in servers address space.

   426     TPckgBuf<TAny*> iSrvDataPtrPckg;

   427     // type of the event that is listened.

   428     TEventType iType;

   429     // the observer given in constructor.

   430     MEventObserver& iObserver;

   431     // the session given in constructor

   432     REventMediator* iSession;

   433 

   434     // possible extra specifications on listened events

   435     HBufC8* iSpecBuf;

   436 

   437     // Event data

   438     HBufC8* iDataBuf;

   439 

   440     // Event data as a modifiable descriptor

   441     TPtr8 iDataPtr;

   442 

   443     // Internal state

   444     TListenerState iState;

   445     };

   446 

   447 #endif // __EVENTMEDIATOR_API_H__