nc-perflib-perflibrequest.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NC:perflib.PERFLIBREQUEST	PERFLIBREQUEST (perflib.h)	Providers can implement this function to receive notification when consumers perform certain actions, such as adding or removing counters from a query.	ControlCallback ControlCallback callback function [Perf] PERFLIBREQUEST PERFLIBREQUEST callback PERF_ADD_COUNTER PERF_COLLECT_END PERF_COLLECT_START PERF_ENUM_INSTANCES PERF_REMOVE_COUNTER base.controlcallback_perflibv2 perf.controlcallback_perflibv2 perflib/ControlCallback	perf\controlcallback_perflibv2.htm	perf	0f771ab7-af42-481b-b2da-20dcdf49b82b	12/05/2018	ControlCallback, ControlCallback callback function [Perf], PERFLIBREQUEST, PERFLIBREQUEST callback, PERF_ADD_COUNTER, PERF_COLLECT_END, PERF_COLLECT_START, PERF_ENUM_INSTANCES, PERF_REMOVE_COUNTER, base.controlcallback_perflibv2, perf.controlcallback_perflibv2, perflib/ControlCallback	perflib.h		Windows	Windows Vista [desktop apps only]	Windows Server 2008 [desktop apps only]													Windows			19H1	PERFLIBREQUEST perflib/PERFLIBREQUEST	c++	APIRef kbSyntax	UserDefined	Perflib.h	ControlCallback

PERFLIBREQUEST callback function

-description

Providers can implement this function to receive notification when consumers perform certain actions, such as adding or removing counters from a query. PERFLIB calls the callback before the consumer's request completes.

The PERFLIBREQUEST type defines a pointer to this callback function. The ControlCallback function is a placeholder for the application-defined function name.

-parameters

-param RequestCode [in]

The request code can be one of the following values.

Value	Meaning
PERF_ADD_COUNTER	The consumer is adding a counter to the query. PERFLIB calls the callback with this request code for each counter being added to the query. The Buffer parameter contains a PERF_COUNTER_IDENTITY structure that identifies the counter being added. Providers can use this notification to start counting.
PERF_REMOVE_COUNTER	The consumer is removing a counter from the query. PERFLIB calls the callback with this request code for each counter being removed from the query. The Buffer parameter contains a PERF_COUNTER_IDENTITY structure that identifies the counter being removed. Providers can use this notification to stop counting.
PERF_ENUM_INSTANCES	The consumer is enumerating instances of the counter set. The Buffer parameter contains a null-terminated Unicode string that identifies the name of the computer (or its IP address) from which the consumer is enumerating the instances.
PERF_COLLECT_START	The consumer is beginning to collect counter data. The Buffer parameter contains a null-terminated Unicode string that identifies the name of the computer (or its IP address) from which the consumer is collecting data. Providers can use this notification if the raw data state is critical (for example, transaction-related counters where partial updates are not allowed). This notification gives the provider a chance to flush all pending updates and lock future updates before collection begins.
PERF_COLLECT_END	The counter data collection is complete. The Buffer parameter contains a null-terminated Unicode string that identifies the name of the computer (or its IP address) from which the consumer collected data. Providers can use this notification to release the update lock imposed by the collection start notification so that updates to the counter data can resume.

-param Buffer [in]

The contents of the buffer depends on the request. For possible content, see the RequestCode parameter.

-param BufferSize [in]

Size, in bytes, of the Buffer parameter.

-returns

Return ERROR_SUCCESS if the callback succeeds.

If the callback fails, PERFLIB will return the error code to the consumer if the request is PERF_ADD_COUNTER, PERF_ENUM_INSTANCES, or PERF_COLLECT_START; otherwise, the error code is ignored.

-remarks

If the callback attribute of the provider element is "custom" or you used the -NotificationCallback argument when calling CTRPP, you must implement this function. You pass the name of your callback function to CounterInitialize.

Windows Vista:  The CounterInitialize function is named PerfAutoInitialize. The CTRPP tool also generates a skeleton of this callback for you that includes all the request codes. You then add code to the request codes that you want to support and remove the others.

The callback must complete within one second. If the callback does not complete in time, PERFLIB continues with the consumer's request and ignores the callback's return value when it completes.

Examples

The following example shows a simple implementation of a ControlCallback function.

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}