RBTrace Class Reference

class RBTrace : public RBusLogicalChannel

Interface to the fast-trace memory buffer.

Inherits from

Public Member Functions
IMPORT_C TIntBufferSize()
IMPORT_C voidCancelRequestData()
IMPORT_C voidClose()
RChunk DataChunk()
IMPORT_C voidDataUsed()
IMPORT_C voidEmpty()
TInt Filter(TUint)
IMPORT_C TIntFilter2(TUint32 *&, TInt &)
IMPORT_C TIntGetData(TUint8 *&)
IMPORT_C TUintMode()
IMPORT_C TIntOpen()
IMPORT_C voidRequestData(TRequestStatus &, TInt)
IMPORT_C TIntResizeBuffer(TInt)
IMPORT_C TIntSetFilter(TUint, TInt)
IMPORT_C TIntSetFilter2(TUint32, TBool)
IMPORT_C TIntSetFilter2(const TUint32 *, TInt)
IMPORT_C TIntSetFilter2(TInt)
IMPORT_C voidSetMode(TUint)
TBool SetSerialPortOutput(TBool)
IMPORT_C TBoolSetTimestamp2Enabled(TBool)
Private Member Functions
voidCloseChunk()
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
enumTMode { EEnable = 1<<0, EFreeRunning = 1<<1 }
enumTPanic { ERequestAlreadyPending }
Private Member Enumerations
enumTControl {
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 TIntBufferSize()

Get the current size of trace buffer.

CancelRequestData()

IMPORT_C voidCancelRequestData()

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

Close()

IMPORT_C voidClose()

Close channel to fast-trace driver.

CloseChunk()

voidCloseChunk()[private]

DataChunk()

RChunk DataChunk()[inline]

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

DataUsed()

IMPORT_C voidDataUsed()

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

Empty()

IMPORT_C voidEmpty()

Discard all trace data.

Filter(TUint)

TInt Filter(TUintaCategory)[inline]

Get the trace filter bit for the specified category.

Parameters

TUint aCategoryA category value from enum BTrace::TCategory,

Filter2(TUint32 *&, TInt &)

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

Get the contents of the secondary trace filter.

Parameters

TUint32 *& aUidsPointer 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 & aGlobalFilterSet 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 TIntGetData(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 *& aDataPointer to the first byte of trace data.

Mode()

IMPORT_C TUintMode()

The operational mode for fast-trace.

Name()

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

Open()

IMPORT_C TIntOpen()

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

OpenChunk()

TInt OpenChunk()[private]

RequestData(TRequestStatus &, TInt)

IMPORT_C voidRequestData(TRequestStatus &aStatus,
TIntaSize
)
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 & aStatusRequest status to be complete with KErrNone once data becomes available.
TInt aSizeThe 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 TIntResizeBuffer(TIntaSize)

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 aSizeThe size in bytes for the trace buffer.

SetFilter(TUint, TInt)

IMPORT_C TIntSetFilter(TUintaCategory,
TIntaValue
)

Set the trace filter bit for the specified category.

Parameters

TUint aCategoryA category value from BTrace::TCategories.
TInt aValueThe 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 TIntSetFilter2(TUint32aUid,
TBoolaValue
)

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 aUidThe UID to filter.
TBool aValueThe 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 TIntSetFilter2(const TUint32 *aUids,
TIntaNumUids
)

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

Parameters

const TUint32 * aUidsPointer to array of UIDs.
TInt aNumUidsNumber of UID values pointer to by aUid.

SetFilter2(TInt)

IMPORT_C TIntSetFilter2(TIntaGlobalFilter)

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

Parameters

TInt aGlobalFilterIf 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 voidSetMode(TUintaMode)

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

Parameters

TUint aModeA bitmask of values from TMode.

SetSerialPortOutput(TBool)

TBool SetSerialPortOutput(TBoolaEnable)

Parameters

TBool aEnable

SetTimestamp2Enabled(TBool)

IMPORT_C TBoolSetTimestamp2Enabled(TBoolaEnable)

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]