/*
* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: This module defines the API to get services from EventMediator.
*
*/
/**
* @file eventmediatorapi.h
*
* This module defines the API to get services from EventMediator.
*
*/
#ifndef __EVENTMEDIATOR_API_H__
#define __EVENTMEDIATOR_API_H__
#include <es_enum.h>
#include "vpnapidefs.h"
#include "vpnmandefs.h"
#define EVENTLOG_FILE_HEADER_LTH 16
/**
*
* Enumeration of supported events types.
*
*/
enum TEventType
{
EUnfoundEvent,
ETestEvent,
ESystemEvents = 10000,
EAllInterfaceEvents,
ESingleInterfaceEvent,
ELogEvent,
EKmdAddressChangeEvent,
EKmdCertificateChangeEvent,
EKmdRealIapConnDownEvent,
// SIT events
EGetProtocolVersionEvent = 20000,
EStartVpnConnEvent,
ECloseVpnConnEvent,
EStartRealIapConnEvent,
EObserveRealIapConnEvent,
// Internal use only
ETaskArrivedEvent = 30000,
EFetchTaskInfoEvent,
EGetProtocolVersionCancelEvent,
EStartVpnConnCancelEvent,
ECloseVpnConnCancelEvent,
EStartRealIapConnCancelEvent,
EObserveRealIapConnCancelEvent,
EProgressEvent
};
/**
*
* Enumeration of log event categories.
*
*/
enum TLogCategory
{
EInfo,
EWarning,
EError,
EDebug
};
/**
* The following definitions are used with TEventType
* ESingleInterfaceEvent and EObserveRealIapConnEvent
*/
enum TSingleConnInterfaceState
{
ESingleInterfaceStateUnknown = -1,
ESingleInterfaceUp,
ESingleInterfaceDown,
ESingleInterfaceTerminated, // Authoritative stop
};
class TSingleInterfaceNotification
{
public:
TConnectionInfo iConnectionInfo;
TSingleConnInterfaceState iState;
};
typedef TPckgBuf<TSingleInterfaceNotification> TSingleInterfaceNotificationBuf;
/**
* Generic event data definition
*/
class TEventSpec
{
public:
inline TEventSpec() : iId(0) {}
TInt iId;
};
/**
* Generic event data definition
*/
class TEventData
{
public:
inline TEventData() : iTaskStatus(KErrNone) {}
TInt iTaskStatus;
};
/**
* Used by SIT to get informed about new tasks.
*/
class TTaskArrivedEventData
{
public:
inline TTaskArrivedEventData()
:iEventType(EUnfoundEvent), iEventSpecId(0)
{}
TEventType iEventType;
TInt iEventSpecId;
};
/**
* Used by SIT to fetch the event specification of a new task.
*/
typedef TTaskArrivedEventData TFetchTaskInfoEventSpec;
/**
*
* MEventObserver - This class must be implemented to use ListenToEvent of EventMediatorApi
*
*/
class MEventObserver
{
public:
/**
* Called by REventMediator when a listened event has been reported.
* @param aStatus: error code, KErrNone if successfull.
* @param aType: the type of the event.
* @param aData: a pointer to a descriptor containing reported data about the event.
* aData pointer is valid only during the execution of EventOccured.
* A copy of the descriptor must be made to store the data for later use.
*/
virtual void EventOccured(TInt aStatus, TEventType aType, TDesC8* aData)=0;
};
class CEventListener;
/**
*
* REventMediator - API class for EventMediator
*
*/
class REventMediator:public RSessionBase
{
/**
** @internalComponent
*/
friend class CEventListener;
public:
/**
* Default constructor
*/
IMPORT_C REventMediator(void);
/**
* Creates session to the EventMediator server. If server is
* not running, it is started.
*/
IMPORT_C TInt Connect();
/**
* Closes the session to the VPN Manager.
*/
IMPORT_C void Close();
/**
* Sends asynchronous event notification request.
* Called after Connect() request.
* @param aType: the type of the event.
* @param aObserver: object whose EventOccured method is called when an event
* of type aType has been reported.
*/
IMPORT_C void ListenToEvent(TEventType aType, MEventObserver& aObserver);
/**
* Sends asynchronous event notification request.
* Called after Connect() request.
* @param aType: the type of the event.
* @param aEventSpec: specific info on listened event.
* @param aObserver: object whose EventOccured method is called when an event
* of type aType has been reported.
*/
IMPORT_C void ListenToEvent(TEventType aType, TDesC8& aEventSpec, MEventObserver& aObserver);
/**
* Cancels all ListenToEvent requests concerning this event type.
* Called after Connect() request.
* @param aType: the type of the event.
*/
IMPORT_C void CancelListening(TEventType aType);
/**
* Cancels ListenToEvent request geiven with a specification.
* Notice that this may fail.
* Called after Connect() request.
* @param aEventSpec: specific info on listened event.
* @param aType: the type of the event.
* @return error code, KErrNone if successfull.
*/
IMPORT_C TInt CancelListening(TEventType aType, TDesC8& aEventSpec);
/**
* Cancels all asynchronous ListenToEvent requests.
* Called after Connect() request.
*/
IMPORT_C void CancelAllListening();
/**
* Sends synchronous request to report an event.
* Called after Connect() request.
* @param aType: the type of the event.
* @param aData: a descriptor containing data about the event.
* @return error code, KErrNone if successfull.
*/
IMPORT_C TInt ReportEvent(TEventType aType);
/**
* Sends synchronous request to report an event.
* Called after Connect() request.
* @param aType: the type of the event.
* @param aData: a descriptor containing data about the event.
* @return error code, KErrNone if successfull.
*/
IMPORT_C TInt ReportEvent(TEventType aType, TDesC8& aData);
/**
* Sends synchronous request to report an event.
* Called after Connect() request.
* @param aType: the type of the event.
* @param aEventSpec: specific info on listened event.
* @param aData: a descriptor containing data about the event.
* @return error code, KErrNone if successfull.
*/
IMPORT_C TInt ReportEvent(TEventType aType, TDesC8& aEventSpec, TDesC8& aData);
/**
* Sends synchronous request to report an event.
* Called after Connect() request.
* @param aTSrc: source of the event.
* @param aCategory: category of the log event.
* @param aMsgId: Id of the log message.
* @param aDesCount: number of additional arguments (which must be of type TDesC8*).
* @return error code, KErrNone if successfull.
*/
IMPORT_C TInt ReportLogEvent(TUid& aSrc, TLogCategory aCategory, TUint aMsgId,TInt aDesCount,...);
/**
* Returns a new event specification
* ID to be used with SIT related events.
*/
IMPORT_C TInt NewEventSpecId();
/**
* Requests the Event Mediator to delete the files it owns.
*/
IMPORT_C TInt DeletePrivateFiles();
IMPORT_C TInt GetEventLogSize(TInt& aEventLogSize);
IMPORT_C TInt GetEventLogHeader(TDes8& aEventLogHeader);
IMPORT_C TInt GetEventLogData(TDes8& aEventLogData);
IMPORT_C TInt ClearEventLog();
/**
* Sends a request to cancel all ListenToEvent requests concerning this
* event type.
* @param aType: the type of the event.
*/
void CancelListenToEvent(TEventType aType);
/**
* Sends a request to cancel all ListenToEvent requests with a given
* specification.
* @param aEventSpec: specific info on listened event.
* @param aType: the type of the event.
* @return error code, KErrNone if successfull.
*/
TInt CancelListenToEvent(TEventType aType, TDesC8& aEventSpec);
private:
void CreateListenedEventsListL();
/**
* Sends synchronous request to get data repeorted with an event.
* Called after Connect() request.
* @param aSrvPtr: pointer to the data in the servers address space.
* The server checks whether this pointer is valid before using it.
* @param aData: a descriptor to which the datais written.
* @return Error status
*/
TInt FetchData(TAny* aSrvPtr, TDes8& aDataDecriptor);
/**
* Called by ListenToEvent function.
* Creates a new instance of CEventListener to receive notification about the event.
* Adds thsi object to iListenedEvents.
* @param aType: the type of the event.
* @param aObserver: object whose EventOccured function is called when event is received.
* @return the new listener.
*/
CEventListener* NewEventListenerL(TEventType aType, MEventObserver& aObserver);
/**
* Deletes listener created with NewEventListener
* @param aType: the type of the event.
*/
void RemoveListener(CEventListener* aListener);
/**
* Creates EventMediator.
*/
TInt StartEventMediator();
/**
* Looks up a listener from iListenedEvents.
* @param aType: type of the event the listener is waiting for.
* @param aIndex: the position of the listener in iListenedEvents.
* @return ETrue if listener exists, EFalse if not.
*/
TBool FindEventListener(const TEventType aType, TInt& aIndex);
/**
* Looks up a listener from iListenedEvents.
* @param aType: type of the event the listener is waiting for.
* @param aEventSpec event specification
* @param aIndex: the position of the listener in iListenedEvents.
* @return ETrue if listener exists, EFalse if not.
*/
TBool FindEventListener(const TEventType aType, TDesC8& aEventSpec, TInt& aIndex);
/**
* Reads the variable arguments of ReportLogEvent.
* @param aCount: Number of arguments.
* @param aList: list of arguments.
* @param aPointers: array to be filled with argument pointers.
* @param aLengths: array to be filled with argument lengths.
* @param aOverAllLength: sum of argument lengths
* @return error code, KErrNone if successfull.
*/
TInt ReadLogArguments(TInt aCount, VA_LIST aList,TDesC8** aPointers, TInt* aLengths, TInt& aOverAllLength);
private: //Data
// list of listeners created with function NewEventListener
CArrayFixFlat<CEventListener*>* iListenedEvents;
TInt64 iRandSeed;
};
/**
*
* CEventListener - A class used by REventListener to Store information about the listened events.
*
*/
NONSHARABLE_CLASS(CEventListener) : public CActive
{
/**
** @internalComponent
*/
friend class REventMediator;
enum TListenerState { EStateListening = 0, EStateFetchingData};
public:
/**
* standard deconstructor
*/
~CEventListener();
private:
/**
* Constructor.
* @param aType: type of the event that is listened.
* @param aObserver: object whose EventOccured is called when event has occured.
* @param aSession: pointer to the owning REventMediator object.
*/
CEventListener(TEventType aType, MEventObserver& aObserver, REventMediator* aSession);
/**
* Implement RunL of class CActive.
*/
void RunL();
/**
* Handles the completion of event listening request
*/
void HandleListeningComplete();
/**
* Handles the completion of event data fetching request
* @param Error status
*/
void HandleFetchingComplete(TInt aError);
/**
* Implements DoCancel of class CActive.
*/
void DoCancel();
private: //data
// buffer to receive the length of the data descriptor of an reported event.
TPckgBuf<TInt> iDataLengthPckg;
// buffer to receive the pointer to the data descriptor in servers address space.
TPckgBuf<TAny*> iSrvDataPtrPckg;
// type of the event that is listened.
TEventType iType;
// the observer given in constructor.
MEventObserver& iObserver;
// the session given in constructor
REventMediator* iSession;
// possible extra specifications on listened events
HBufC8* iSpecBuf;
// Event data
HBufC8* iDataBuf;
// Event data as a modifiable descriptor
TPtr8 iDataPtr;
// Internal state
TListenerState iState;
};
#endif // __EVENTMEDIATOR_API_H__