Trace buffers

Collaboration diagram for Trace buffers:

Functions
MLPIRESULT	mlpiTraceGetNumberOfBuffers (const MLPIHANDLE connection, ULONG *numberOfBuffers)
MLPIRESULT	mlpiTraceGetBufferList (const MLPIHANDLE connection, MlpiTraceBufferInformation *bufferInfo, const ULONG numElements, ULONG *numElementsRet=0)
MLPIRESULT	mlpiTraceReadBuffer (const MLPIHANDLE connection, const WCHAR16 *bufferName, const ULLONG startIndex, MlpiTraceMessage *messages, const ULONG numElements, ULONG *numElementsRet=0)
MLPIRESULT	mlpiTraceGetNewestMessageIndex (const MLPIHANDLE connection, const WCHAR16 *bufferName, ULLONG *newestIndex)
MLPIRESULT	mlpiTraceGetOldestMessageIndex (const MLPIHANDLE connection, const WCHAR16 *bufferName, ULLONG *oldestIndex)
MLPIRESULT	mlpiTraceClearAllBuffers (const MLPIHANDLE connection)

Detailed Description

Use the following functions to read information on or the content of the trace buffers.

Function Documentation

MLPIRESULT mlpiTraceGetNumberOfBuffers	(	const MLPIHANDLE	connection,
		ULONG *	numberOfBuffers
	)

This function returns the number of registered buffers.

Parameters

[in]	connection	Handle for multiple connections.
[out]	numberOfBuffers	Number of registered buffers.

Returns

Return value indicating success (>=0) or error (<0).

Example:

ULONG numBuffers=0;

MLPIRESULT result = mlpiTraceGetNumberOfBuffers(connection, &numBuffers);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

printf("\nNumber of available trace buffers: %d", numBuffers);

MLPIRESULT mlpiTraceGetBufferList	(	const MLPIHANDLE	connection,
		MlpiTraceBufferInformation *	bufferInfo,
		const ULONG	numElements,
		ULONG *	numElementsRet = 0
	)

This function returns a list of all buffers currently available in the tracing system. The buffer information also contains the name of each buffer. This name can be used with other calls to the tracing system.

Parameters

[in]	connection	Handle for multiple connections.
[out]	bufferInfo	Pointer to an array which will receive the buffer information. One element for each buffer.
[in]	numElements	Array size of buffer given to function in number of elements.
[out]	numElementsRet	Returns the actual number of elements returned.

Returns

Return value indicating success (>=0) or error (<0).

Example:

ULONG numBuffers=0;
MlpiTraceBufferInformation buffers[MLPI_TRACE_MAX_BUFFERS];

// read array of available buffers
MLPIRESULT result = mlpiTraceGetBufferList(connection, buffers, _countof(buffers), &numBuffers);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

// print all buffers found
printf("\nFound %d Buffers\n", numBuffers);
printf("\n BufferName          | Locked | MaxSize  | ActSize        ");
printf("\n---------------------+--------+----------+---------       ");
for (ULONG i=0; i<numBuffers; i++)
{
  printf("\n%20s", W2A16(buffers[i].bufferName));
  printf(" |%7s", (buffers[i].isLocked) ? "TRUE" : "FALSE");
  printf(" | % 8d", buffers[i].maximumBufferSize);
  printf(" | % 8d  ", buffers[i].actualBufferSize);
}

MLPIRESULT mlpiTraceReadBuffer	(	const MLPIHANDLE	connection,
		const WCHAR16 *	bufferName,
		const ULLONG	startIndex,
		MlpiTraceMessage *	messages,
		const ULONG	numElements,
		ULONG *	numElementsRet = 0
	)

This functions returns the messages of a given buffer.

Parameters

[in]	connection	Handle for multiple connections.
[in]	bufferName	Name of the buffer to access.
[in]	startIndex	Index of the first message to start reading. Should be between the indices of mlpiTraceGetNewestMessageIndex and mlpiTraceGetOldestMessageIndex.
[out]	messages	Pointer to buffer which will receive the messages.
[in]	numElements	Array size of buffer given to function in number of elements.
[out]	numElementsRet	Returns the actual number of elements(messages) returned.

Returns

Return value indicating success (>=0) or error (<0).

Example

WCHAR16 bufferName[] = L"MAIN";   // let's read the buffer called 'MAIN'. Should be available on most targets.
MlpiTraceMessage messages[150];   // let's read 150 messages
ULLONG oldestIndex = 0;
ULLONG newestIndex = 0;

// read message index of the newest and oldest available message in the buffer.
// We use this information to calculate how many messages are available and to
// read the 150 latest messages later on.
MLPIRESULT result = mlpiTraceGetOldestMessageIndex(connection, bufferName, &oldestIndex);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}
result = mlpiTraceGetNewestMessageIndex(connection, bufferName, &newestIndex);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

ULLONG numMessages = newestIndex-oldestIndex;
printf("\nFound %d messages in buffer %s\n", (ULONG)numMessages, W2A16(bufferName));
if (numMessages == 0) {
  printf("\n->currently no messages to read :-( (tip: enable some modules!)");
}
else {
  // limit to array size
  if (numMessages > _countof(messages)) {
    numMessages = _countof(messages);
  }
}


// now read the buffer to our array
ULONG numMessagesReturned = 0;
result = mlpiTraceReadBuffer(connection, bufferName, newestIndex, messages, numMessages, &numMessagesReturned);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

// print all messages to console.
// messages in the array are sorted from newest to oldest.
// Therefore, inverse the array when printing to console to get newest message
// printed last and to read output from top to bottom (oldest to newest).
printf("\n Filename                    | Line | Module            | Type | Message      ");
printf("\n-----------------------------+------+-------------------+------+------------- ");

for (LONG i=numMessagesReturned-1; i>=0; i--) {
  printf("\n%-*s %-*d %-*s %-*d %s",
    MLPI_TRACE_FUNCTION_NAME_SIZE, W2A16(messages[i].functionName),
    5, messages[i].lineNumber,
    MLPI_TRACE_MODULE_NAME_SIZE, W2A16(messages[i].moduleName),
    5, messages[i].type,
    W2A16(messages[i].text)
    );
}

MLPIRESULT mlpiTraceGetNewestMessageIndex	(	const MLPIHANDLE	connection,
		const WCHAR16 *	bufferName,
		ULLONG *	newestIndex
	)

This function returns the message index of the newest message available in the given trace buffer. You can use this information for subsequent calls to mlpiTraceReadBuffer to read the newest messages in the buffer.

Note

Each new message that gets added to the trace buffer gets a new unique index. Indices are given in ascending order.

Parameters

[in]	connection	Handle for multiple connections.
[in]	bufferName	Name of the buffer to access.
[out]	newestIndex	Index of the newest available trace message.

Returns

Return value indicating success (>=0) or error (<0).

See also

mlpiTraceReadBuffer

MLPIRESULT mlpiTraceGetOldestMessageIndex	(	const MLPIHANDLE	connection,
		const WCHAR16 *	bufferName,
		ULLONG *	oldestIndex
	)

This function returns the message index of the oldest message available in the given trace buffer. You can use this information for subsequent calls to mlpiTraceReadBuffer to read the oldest messages in the buffer.

Note

Each new message that gets added to the trace buffer gets a new unique index. Indices are given in ascending order.

Parameters

[in]	connection	Handle for multiple connections.
[in]	bufferName	Name of the buffer to access.
[out]	oldestIndex	Index of the oldest available trace message. (newestIndex > oldestIndex).

Returns

Return value indicating success (>=0) or error (<0).

See also

mlpiTraceReadBuffer

MLPIRESULT mlpiTraceClearAllBuffers

(

const MLPIHANDLE

connection

)

This function clears all buffers. This means that all trace messages currently available and stored in the system will be deleted.

Parameters

[in]

connection

Handle for multiple connections.

Returns

Return value indicating success (>=0) or error (<0).

Example:

// Clear all buffers
MLPIRESULT result = mlpiTraceClearAllBuffers(connection);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}