Trace modules

Collaboration diagram for Trace modules:

Functions
MLPIRESULT	mlpiTraceActivateModule (const MLPIHANDLE connection, const WCHAR16 *moduleName)
MLPIRESULT	mlpiTraceDeactivateModule (const MLPIHANDLE connection, const WCHAR16 *moduleName)
MLPIRESULT	mlpiTraceActivateAllModules (const MLPIHANDLE connection)
MLPIRESULT	mlpiTraceDeactivateAllModules (const MLPIHANDLE connection)
MLPIRESULT	mlpiTraceGetNumberOfModules (const MLPIHANDLE connection, ULONG *numberOfModules)
MLPIRESULT	mlpiTraceGetModuleList (const MLPIHANDLE connection, MlpiTraceModuleInformation *moduleInfo, const ULONG numElements, ULONG *numElementsRet=0)

Detailed Description

Use the following functions to activate, deactivate and read information about the trace modules.

Function Documentation

MLPIRESULT mlpiTraceActivateModule	(	const MLPIHANDLE	connection,
		const WCHAR16 *	moduleName
	)

This function activates a trace module. Trace messages to modules which are not activated will not be written to the trace buffer. This means, that you have to activate a module to trace its messages. Available Module names can be retrieved with the function mlpiTraceGetModuleList. It is highly recommended to use the macro MLPI_TRACE_MODULE_USER for your code.

Note

Enabling trace modules might cost some CPU performance.

Parameters

[in]	connection	Handle for multiple connections.
[out]	moduleName	Pointer to module name string.

Returns

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

Example:

// Activate only the module 'MLPI_TRACE_MODULE_USER'
MLPIRESULT result = mlpiTraceActivateModule(connection, MLPI_TRACE_MODULE_USER);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

MLPIRESULT mlpiTraceDeactivateModule	(	const MLPIHANDLE	connection,
		const WCHAR16 *	moduleName
	)

This function deactivates a trace module. Messages to a deactivated trace module are ignored by the tracing system and thus will not appear in the trace buffer. Available Module names can be retrieved with the function mlpiTraceGetModuleList.

Parameters

[in]	connection	Handle for multiple connections.
[out]	moduleName	Pointer to module name string.

Returns

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

Example:

// Deactivate only the module 'MLPI_TRACE_MODULE_USER'
MLPIRESULT result = mlpiTraceDeactivateModule(connection, MLPI_TRACE_MODULE_USER);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

MLPIRESULT mlpiTraceActivateAllModules

(

const MLPIHANDLE

connection

)

This function activates all available trace modules.

Note

Enabling all trace modules might result in a performance drop, as tracing costs CPU time. It is not recommended to enable all trace modules on a productive machine. Try activating only the modules of interest, or one module at a time.

Parameters

[in]

connection

Handle for multiple connections.

Returns

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

Example:

// activate all available trace modules (not recommended!)
MLPIRESULT result = mlpiTraceActivateAllModules(connection);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

MLPIRESULT mlpiTraceDeactivateAllModules

(

const MLPIHANDLE

connection

)

This function deactivates all available trace modules.

Parameters

[in]

connection

Handle for multiple connections.

Returns

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

Example:

// activate all available trace modules
MLPIRESULT result = mlpiTraceDeactivateAllModules(connection);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", result);
  return result;
}

MLPIRESULT mlpiTraceGetNumberOfModules	(	const MLPIHANDLE	connection,
		ULONG *	numberOfModules
	)

This function returns the number of registered modules.

Parameters

[in]	connection	Handle for multiple connections.
[out]	numberOfModules	Number of registered modules.

Returns

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

Example:

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

printf("\nNumber of available trace modules: %d", numModules);

MLPIRESULT mlpiTraceGetModuleList	(	const MLPIHANDLE	connection,
		MlpiTraceModuleInformation *	moduleInfo,
		const ULONG	numElements,
		ULONG *	numElementsRet = 0
	)

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

Parameters

[in]	connection	Handle for multiple connections.
[out]	moduleInfo	Pointer to an array which will receive the module information. One element for each module.
[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 numModules=0;
MlpiTraceModuleInformation modules[MLPI_TRACE_MAX_MODULES];

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

// print all modules found
printf("\nFound %d Modules\n", numModules);
printf("\n ModuleName          | Active | StdOut | Main   | Separat| Buffer     ");
printf("\n---------------------+--------+--------+--------+--------+--------    ");
for (ULONG i=0; i<numModules; i++)
{
  printf("\n%20S", modules[i].moduleName);
  printf(" |%7s", (modules[i].isActive) ? "TRUE" : "FALSE");
  printf(" |%7s", (modules[i].toStdOut) ? "TRUE" : "FALSE");
  printf(" |%7s", (modules[i].toMainBuffer) ? "TRUE" : "FALSE");
  printf(" |%7s", (modules[i].toSeparateBuffer) ? "TRUE" : "FALSE");
  printf(" | %s", W2A16(modules[i].bufferName));
}