Class CLogClient

class CLogClient : public CLogBase;

Description

Log Engine implementation.

It creates a shared session on the log database and allows log viewers to retrieve events from the log.

The class also provides log administration functions.

Wherever time values are used by this class, they must be specified as UTC rather than local time.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

• CLogActive - Common active object behaviour.

• CLogBase - Base class for the log engine implementation.

• CLogClient - Log Engine implementation.

Members

Defined in CLogClient:

• AddEvent(CLogEvent &,TRequestStatus &)Adds an event to the log database. This is an asynchronous request.
• AddEventType(const CLogEventType &,TRequestStatus &)Registers a new event type. This is an asynchronous request.
• CLogBase_Reserved1()
• ChangeConfig(const TLogConfig &,TRequestStatus &)Changes the Log Engine configuration. This is an asynchronous request.
• ChangeEvent(const CLogEvent &,TRequestStatus &)Changes the details of an existing event. This is an asynchronous request.
• ChangeEventType(const CLogEventType &,TRequestStatus &)Changes the details of an existing event type. This is an asynchronous request.
• ClearLog(TInt,TRequestStatus &)Clears the specified recent event list. This is an asynchronous request.
• ClearLog(const TTime &,TRequestStatus &)Clears all events from the main event log that occurred before the specified dat...
• DeleteEvent(TLogId,TRequestStatus &)Deletes the event with the specified unique event ID, from the main event log.
• DeleteEventType(TUid,TRequestStatus &)Removes an existing event type. This is an asynchronous request.
• DoCancel()Implements cancellation of an outstanding request.
• DoRunL()
• GetConfig(TLogConfig &,TRequestStatus &)Gets the Log Engine configuration. This is an asynchronous request.
• GetEvent(CLogEvent &,TRequestStatus &)Gets the details of the specified event. This is an asynchronous request.
• GetEventType(CLogEventType &,TRequestStatus &)Gets the details of an event type. This is an asynchronous request.
• GetString(TDes &,TInt)constGets a standard string from the specified resource in logwrap.dll resource file.
• NewL(RFs &,TInt)
• NotifyChange(TTimeIntervalMicroSeconds32,TRequestStatus &)Requests notification of changes to the Log Engine database. This is an asynchro...
• NotifyChangeCancel()Cancels any outstanding notification request for changes to Log Engine database.
• SetGlobalChangeObserverL(MLogClientChangeObserver *)
• ~CLogClient()Frees all resources owned by the Log Engine object prior to its destruction. In ...

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• RunL()Handles an active object's request completion event.
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from CLogActive:

• CLogActive(TInt)
• Complete(TInt)
• Queue(TRequestStatus &)

Inherited from CLogBase:

• CLogBase(TInt)Sets the priority of this active object.
• LoadResourcesL(RFs &)
• ResourceFile()const

See also:

• CLogWrapperThe log wrapper.

IMPORT_C static CLogClient* NewL(RFs &aFs, TInt aPriority=CActive::EPriorityStandard);

Description

Parameters

RFs &aFs TInt aPriority

Return value

CLogClient *

IMPORT_C ~CLogClient();

Description

Frees all resources owned by the Log Engine object prior to its destruction. In particular, any outstanding asynchronous request is cancelled, the database, the database session and the resource file are all closed.

Capability:

Security policy note:

For built-in event types, the required capability level is defined in the event type's write access policy.

IMPORT_C virtual void AddEvent(CLogEvent &aEvent, TRequestStatus &aStatus);

Description

Adds an event to the log database. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

CLogEvent &aEvent A log event detail object containing the attributes of the event to be added. The Log Engine sets the unique event ID, the UTC time and the event description, replacing any supplied values. The caller must ensure that this object remains in existence and valid until the request is complete. TRequestStatus &aStatus The request status. On request completion,contains: KErrNone, if the event has been successfully added to the log database; KErrNotFound, if the event type is not registered with the Log Engine; KErrNotSupported, if the logging of events of this type has been disabled; otherwise, one of the other system wide error codes.

See also:

• CLogEventType::SetLoggingEnabled(TBool)Enables or disables logging for this event type.

Capability:

Security policy note:

For built-in event types, the required capability level is defined in the event type's read access policy.

IMPORT_C virtual void GetEvent(CLogEvent &aEvent, TRequestStatus &aStatus);

Description

Gets the details of the specified event. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

CLogEvent &aEvent A reference to a log event detail object. Before calling the function, this object must contain the appropriate unique event ID; if no unique event ID is set, the function raises a LogCli 13 panic. The caller must ensure that this object remains in existence and valid until the request is complete. On successful completion of the request, it contains the appropriate log event detail. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• TLogIdType definitions The unique event ID associated with a log event.

Capability:

Security policy note:

For built-in event types, the required capability level is defined in the event type's write access policy.

IMPORT_C virtual void ChangeEvent(const CLogEvent &aEvent, TRequestStatus &aStatus);

Description

Changes the details of an existing event. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Note that it is not possible to change the event type using this function.

Parameters

const CLogEvent &aEvent The event detail object containing the attributes of the event to be changed. Before calling the function, this object must contain the appropriate unique event ID; if no unique event ID is set, the function raises a LogCli 13 panic. The caller must ensure that this object remains in existence and valid until the request is complete. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• TLogIdType definitions The unique event ID associated with a log event.

Capability:

Security policy note:

For built-in event types, the required capability level is defined in the event type's write access policy.

IMPORT_C virtual void DeleteEvent(TLogId aId, TRequestStatus &aStatus);

Description

Deletes the event with the specified unique event ID, from the main event log.

Parameters

TLogId aId The unique event ID of the event to be deleted. This must not be the null unique event ID, KLogNullId, otherwise the function raises a LogCli 13 panic. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

WriteDeviceData

IMPORT_C void AddEventType(const CLogEventType &aType, TRequestStatus &aStatus);

Description

Registers a new event type. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

const CLogEventType &aType The event type detail object containing the attributes of the event type to be registered. The caller must ensure that this object remains in existence and valid until the request is complete. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• TUidA globally unique 32-bit number.

Capability:

Security policy note:

None required.

IMPORT_C void GetEventType(CLogEventType &aType, TRequestStatus &aStatus);

Description

Gets the details of an event type. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

CLogEventType &aType A reference to an event type detail object. Before calling the function, this object must contain the UID identifying the event type; if no UID is set, the function raises a LogCli 13 panic. The caller must ensure that this object remains in existence and valid until the request is complete. On successful completion of the request, it contains the appropriate event type detail. TRequestStatus &aStatus The request status. On request completion, contains: KErrNone, if successful; otherwise one of the other system wide error codes.

See also:

• TUidA globally unique 32-bit number.

Capability:

WriteDeviceData

IMPORT_C void ChangeEventType(const CLogEventType &aType, TRequestStatus &aStatus);

Description

Changes the details of an existing event type. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

const CLogEventType &aType The event type detail object containing the attributes of the event type to be changed. Before calling the function, this object must contain the UID identifying the event type; if no UID is set, the function raises a LogCli 13 panic. The caller must ensure that this object remains in existence and valid until the request is complete. TRequestStatus &aStatus The request status. On request completion, contains: KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• TUidA globally unique 32-bit number.

Capability:

WriteDeviceData

IMPORT_C void DeleteEventType(TUid aId, TRequestStatus &aStatus);

Description

Removes an existing event type. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Note that this function does not remove events from the event log, so it is possible to have events in the log that are of an unknown type. This function allows an event type associated with a component to be removed when that component is uninstalled.

Parameters

TUid aId The UID of the event type to be deleted. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

Security policy note:

None required.

IMPORT_C void GetConfig(TLogConfig &aConfig, TRequestStatus &aStatus);

Description

Gets the Log Engine configuration. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

TLogConfig &aConfig A reference to a Log Engine configuration object. The caller must ensure that this object remains in existence and valid until the request is complete. On successful completion of the request, it contains the Log Engine configuration data. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

WriteDeviceData

IMPORT_C void ChangeConfig(const TLogConfig &aConfig, TRequestStatus &aStatus);

Description

Changes the Log Engine configuration. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

const TLogConfig &aConfig The new configuration values for the Log Engine. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

WriteDeviceData

IMPORT_C void ClearLog(const TTime &aDate, TRequestStatus &aStatus);

Description

Clears all events from the main event log that occurred before the specified date and time. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

const TTime &aDate The UTC date and time. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

WriteDeviceData

IMPORT_C void ClearLog(TInt aRecentList, TRequestStatus &aStatus);

Description

Clears the specified recent event list. This is an asynchronous request.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Parameters

TInt aRecentList Identifies the recent event list to be cleared. The value KlogNullRecentList indicates that all recent event lists are to be cleared. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful; otherwise, one of the other system wide error codes.

Capability:

Security policy note:

None required.

IMPORT_C void NotifyChange(TTimeIntervalMicroSeconds32 aDelay, TRequestStatus &aStatus);

Description

Requests notification of changes to the Log Engine database. This is an asynchronous request.

The function requires the caller to specify a minimum time that must elapse before this notification request can complete. The Log Engine buffers all changes that occur during this time; the request, then completes after this minimum time period has elapsed. If no changes occur within this time period, then the request completes when the next change to the database occurs.

There must be no asynchronous request outstanding when this function is called, otherwise the function raises a LogCli 0 panic.

Note that once a notification request has completed, this function must be called again to get further change notifications.

Parameters

TTimeIntervalMicroSeconds32 aDelay The minimum time, in microseconds, that elapses before the notification request can complete. TRequestStatus &aStatus The request status. On request completion, contains:KErrNone, if successful;KErrCancel, if an outstanding notification request is cancelled; otherwise, one of the other system wide error codes.

Capability:

Security policy note:

None required

IMPORT_C void NotifyChangeCancel();

Description

Cancels any outstanding notification request for changes to Log Engine database.

This function can be called even if there is no outstanding notification request.

Capability:

Security policy note:

None required

IMPORT_C void SetGlobalChangeObserverL(MLogClientChangeObserver *aObserver);

Description

Parameters

MLogClientChangeObserver *aObserver

Capability:

Security policy note:

None required.

IMPORT_C virtual TInt GetString(TDes &aString, TInt aId) const;

Description

Gets a standard string from the specified resource in logwrap.dll resource file.

The function can be used to populate some of the event fields in a CLogEvent object before creating or changing an event.

Note that TLogString is a modifiable buffer descriptor that is guaranteed to be large enough to contain all standard strings used in the Log Engine; pass an instance of this type to this function.

Parameters

TDes16 &aString A modifiable descriptor into which the string is copied. TInt aId The resource id.

Return value

TInt KErrNone, if successful; otherwise, one of the other system wide error codes.

See also:

• TLogStringBig enough to contain any of the above strings Defines a modifiable buffer descr...

private: virtual void DoRunL();

Description

private: virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's CActive::Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

CLogClient::DoCancel() must not wait for event completion; this is handled by CActive::Cancel().

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

private: IMPORT_C virtual void CLogBase_Reserved1();

Description