RBTrace Class Reference

class RBTrace : public RBusLogicalChannel

Interface to the fast-trace memory buffer.

Public Member Functions
IMPORT_C TInt BufferSize ()
IMPORT_C void CancelRequestData ()
IMPORT_C void Close ()
RChunk DataChunk ()
IMPORT_C void DataUsed ()
IMPORT_C void Empty ()
TInt Filter ( TUint )
IMPORT_C TInt Filter2 ( TUint32 *&, TInt &)
IMPORT_C TInt GetData ( TUint8 *&)
IMPORT_C TUint Mode ()
IMPORT_C TInt Open ()
IMPORT_C void RequestData ( TRequestStatus &, TInt )
IMPORT_C TInt ResizeBuffer ( TInt )
IMPORT_C TInt SetFilter ( TUint , TInt )
IMPORT_C TInt SetFilter2 ( TUint32 , TBool )
IMPORT_C TInt SetFilter2 (const TUint32 *, TInt )
IMPORT_C TInt SetFilter2 ( TInt )
IMPORT_C void SetMode ( TUint )
TBool SetSerialPortOutput ( TBool )
IMPORT_C TBool SetTimestamp2Enabled ( TBool )
Private Member Functions
void CloseChunk ()
const TDesC & Name ()
TInt OpenChunk ()
Inherited Functions
RBusLogicalChannel::DoCancel(TUint)
RBusLogicalChannel::DoControl(TInt)
RBusLogicalChannel::DoControl(TInt,TAny *)
RBusLogicalChannel::DoControl(TInt,TAny *,TAny *)
RBusLogicalChannel::DoCreate(const TDesC &,const TVersion &,TInt,const TDesC *,const TDesC8 *,TOwnerType,TBool)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *,TAny *)
RBusLogicalChannel::DoSvControl(TInt)
RBusLogicalChannel::DoSvControl(TInt,TAny *)
RBusLogicalChannel::DoSvControl(TInt,TAny *,TAny *)
RBusLogicalChannel::Open(RMessagePtr2,TInt,TOwnerType)
RBusLogicalChannel::Open(TInt,TOwnerType)
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RHandleBase::SetReturnedHandle(TInt)
RHandleBase::SetReturnedHandle(TInt,RHandleBase &)
Public Member Enumerations
enum TMode { EEnable  = 1<<0, EFreeRunning  = 1<<1 }
enum TPanic { ERequestAlreadyPending }
Private Member Enumerations
enum TControl {
EOpenBuffer , EResizeBuffer , ESetFilter , ESetFilter2 , ESetFilter2Array , ESetFilter2Global , EGetFilter2Part1 , EGetFilter2Part2 , ERequestData , ECancelRequestData , ESetSerialPortOutput , ESetTimestamp2Enabled
}
Inherited Enumerations
RHandleBase:TAttributes
Private Attributes
TBTraceBuffer * iBuffer
RChunk iDataChunk
TInt iLastGetDataSize
TUint32 iSpare
Inherited Attributes
RHandleBase::iHandle

Member Functions Documentation

BufferSize()

IMPORT_C TInt BufferSize ( )

Get the current size of trace buffer.

CancelRequestData()

IMPORT_C void CancelRequestData ( )

Cancel any previous RequestData() , completing it with KErrCancel.

Close()

IMPORT_C void Close ( )

Close channel to fast-trace driver.

CloseChunk()

void CloseChunk ( ) [private]

DataChunk()

RChunk DataChunk ( ) [inline]

The chunk in which trace data returned by GetData() resides.

DataUsed()

IMPORT_C void DataUsed ( )

Remove from the trace buffer all of the data returned by the last call to GetData() .

Empty()

IMPORT_C void Empty ( )

Discard all trace data.

Filter(TUint)

TInt Filter ( TUint aCategory ) [inline]

Get the trace filter bit for the specified category.

Parameters

TUint aCategory A category value from enum BTrace::TCategory,

Filter2(TUint32 *&, TInt &)

IMPORT_C TInt Filter2 ( TUint32 *& aUids,
TInt & aGlobalFilter
)

Get the contents of the secondary trace filter.

Parameters

TUint32 *& aUids Pointer to array of UIDs contained in the secondary filter. Ownership of this array is passed to the caller of this function, which is then responsible for deleting it. If filter is empty, aUid equals zero.
TInt & aGlobalFilter Set to 1 if the secondary filter passes all traces. Set to 0 if the secondary filter rejects all traces. Set to -1 if the secondary filter operates by UIDs contained in traces.

GetData(TUint8 *&)

IMPORT_C TInt GetData ( TUint8 *& aData )
Get pointer to as much contiguous trace data as is available. This data resides in the shared chunk DataChunk() . The data returned will always be a whole number of trace records, i.e. trace records will not be split between successive calls to this method. Once the data is no loger required, DataUsed() must be called. This method can be called repeatedly to get more trace data. E.g.
         RBTrace trace;
		TInt error = trace.Open();
		if(error!=KErrNone)
			return error;
		const TInt KTraceDataBlockSize = 65536; // size of data we ideally want to process in one go
		TUint8* data;
		TInt size;
		do
			{
			while((size=trace.GetData(data))!=0)
				{
				ProcessTheTraceData(data,size);
				trace.DataUsed();
				}
			TRequestStatus waitStatus;
			trace.RequestData(waitStatus,KTraceDataBlockSize);
			User::WaitForRequest(waitStatus);
			error = waitStatus.Int();
			}
		while(error==KErrNone);
		trace.Close();
		return error;
        

DataChunk() ;

Parameters

TUint8 *& aData Pointer to the first byte of trace data.

Mode()

IMPORT_C TUint Mode ( )

The operational mode for fast-trace.

Name()

const TDesC & Name ( ) [private, static, inline]

Open()

IMPORT_C TInt Open ( )

Open channel to fast-trace driver. Must be called before any other methods are used.

OpenChunk()

TInt OpenChunk ( ) [private]

RequestData(TRequestStatus &, TInt)

IMPORT_C void RequestData ( TRequestStatus & aStatus,
TInt aSize
)
Request notification when trace data becomes available. Only one outstanding request may be present at any one time.
panic
BTRACE 0 if a previous request is still pending

Parameters

TRequestStatus & aStatus Request status to be complete with KErrNone once data becomes available.
TInt aSize The minimum number of bytes of trace data required. This is intended to improve performance by only signalling the client once a suitably large amount of trace data is available. However, this request may complete before this amount of trace data is available, therefore a client must be able to handle this situation. If aSize is zero or negative, then the request completes as soon as any trace data is available.

ResizeBuffer(TInt)

IMPORT_C TInt ResizeBuffer ( TInt aSize )

Change size of trace buffer. This causes all current data in the trace buffer to be lost. If this method fails then the trace buffer may no longer exist.

Parameters

TInt aSize The size in bytes for the trace buffer.

SetFilter(TUint, TInt)

IMPORT_C TInt SetFilter ( TUint aCategory,
TInt aValue
)

Set the trace filter bit for the specified category.

Parameters

TUint aCategory A category value from BTrace::TCategories.
TInt aValue The new filter value for the category. 1 means traces of this category are output, 0 means they are suppressed. Any other value will be ignored, and this method will just return the current value of the filter.

SetFilter2(TUint32, TBool)

IMPORT_C TInt SetFilter2 ( TUint32 aUid,
TBool aValue
)

Set the trace secondary trace filter for the specified UID.

This method can not be used to disable a UID key if SetFilter2(TInt aGlobalFilter) has been used to set the filter to pass all traces. Such attempts result in a return code of KErrNotSupported.

Parameters

TUint32 aUid The UID to filter.
TBool aValue The new filter value for the UID. 1 means traces with this UID are output, 0 means they are suppressed. Other values must not be used.

SetFilter2(const TUint32 *, TInt)

IMPORT_C TInt SetFilter2 ( const TUint32 * aUids,
TInt aNumUids
)

Set the secondary trace filter to include only the specified UIDs.

Parameters

const TUint32 * aUids Pointer to array of UIDs.
TInt aNumUids Number of UID values pointer to by aUid.

SetFilter2(TInt)

IMPORT_C TInt SetFilter2 ( TInt aGlobalFilter )

Set the secondary trace filter to pass or reject every trace.

Parameters

TInt aGlobalFilter If 0, the secondary filter will reject all traces; if 1, all traces are passed by the filter. Other values have no effect.

SetMode(TUint)

IMPORT_C void SetMode ( TUint aMode )

Set the operational mode for fast-trace. Calling this method, invalidates the trace data returned by the last call to GetData() .

Parameters

TUint aMode A bitmask of values from TMode.

SetSerialPortOutput(TBool)

TBool SetSerialPortOutput ( TBool aEnable )

Parameters

TBool aEnable

SetTimestamp2Enabled(TBool)

IMPORT_C TBool SetTimestamp2Enabled ( TBool aEnable )

Controls whether Timestamp2 field is added to trace record headers.

Parameters

TBool aEnable

Member Enumerations Documentation

Enum TControl

Enumerators

EOpenBuffer
EResizeBuffer
ESetFilter
ESetFilter2
ESetFilter2Array
ESetFilter2Global
EGetFilter2Part1
EGetFilter2Part2
ERequestData
ECancelRequestData
ESetSerialPortOutput
ESetTimestamp2Enabled

Enum TMode

Bit flags indicating the operational mode of the fast-trace buffer.

Enumerators

EEnable = 1<<0

Flag set to enable trace to be stored in the buffer. If this is not set, all trace records are discarded.

EFreeRunning = 1<<1

This flag dictates the behaviour which occurs when the trace buffer is too full to accomodate a new record. When this flag is set, new trace records will overwrite the oldest ones. When this flag is not set, new trace records are discard. (This latter mode provides the best performance.)

Enum TPanic

Enumeration of panic reasons for category 'BTRACE'.

Enumerators

ERequestAlreadyPending

A call to RequestData() was made whist a request was already pending.

Member Data Documentation

TBTraceBuffer * iBuffer

TBTraceBuffer * iBuffer [private]

RChunk iDataChunk

RChunk iDataChunk [private]

TInt iLastGetDataSize

TInt iLastGetDataSize [private]

TUint32 iSpare

TUint32 iSpare [private]