Funzione di callback PERFLIBREQUEST (perflib.h)

Articolo
08/25/2023

I provider possono implementare questa funzione per ricevere una notifica quando i consumer eseguono determinate azioni, ad esempio l'aggiunta o la rimozione di contatori da una query. PERFLIB chiama il callback prima del completamento della richiesta del consumer.

Il tipo PERFLIBREQUEST definisce un puntatore a questa funzione di callback. La funzione ControlCallback è un segnaposto per il nome della funzione definita dall'applicazione.

Sintassi

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

Parametri

[in] RequestCode

Il codice della richiesta può essere uno dei valori seguenti.

Valore	Significato
PERF_ADD_COUNTER	Il consumer aggiunge un contatore alla query. PERFLIB chiama il callback con questo codice di richiesta per ogni contatore aggiunto alla query. Il parametro Buffer contiene una struttura PERF_COUNTER_IDENTITY che identifica il contatore da aggiungere. I provider possono usare questa notifica per iniziare a contare.
PERF_REMOVE_COUNTER	Il consumer rimuove un contatore dalla query. PERFLIB chiama il callback con questo codice di richiesta per ogni contatore rimosso dalla query. Il parametro Buffer contiene una struttura PERF_COUNTER_IDENTITY che identifica il contatore rimosso. I provider possono usare questa notifica per arrestare il conteggio.
PERF_ENUM_INSTANCES	Il consumer enumera le istanze del set di contatori. Il parametro Buffer contiene una stringa Unicode con terminazione null che identifica il nome del computer (o il relativo indirizzo IP) da cui il consumer enumera le istanze.
PERF_COLLECT_START	Il consumer sta iniziando a raccogliere i dati del contatore. Il parametro Buffer contiene una stringa Unicode con terminazione null che identifica il nome del computer (o il relativo indirizzo IP) da cui il consumer raccoglie i dati. I provider possono usare questa notifica se lo stato dei dati non elaborati è critico(ad esempio, contatori correlati alle transazioni in cui gli aggiornamenti parziali non sono consentiti). Questa notifica consente al provider di scaricare tutti gli aggiornamenti in sospeso e bloccare gli aggiornamenti futuri prima dell'inizio della raccolta.
PERF_COLLECT_END	La raccolta dati del contatore è completa. Il parametro Buffer contiene una stringa Unicode con terminazione null che identifica il nome del computer (o il relativo indirizzo IP) da cui il consumer ha raccolto i dati. I provider possono usare questa notifica per rilasciare il blocco di aggiornamento imposto dalla notifica di avvio della raccolta in modo che gli aggiornamenti ai dati del contatore possano riprendere.

[in] Buffer

Il contenuto del buffer dipende dalla richiesta. Per il contenuto possibile, vedere il parametro RequestCode .

[in] BufferSize

Dimensioni, in byte, del parametro Buffer .

Valore restituito

Restituisce ERROR_SUCCESS se il callback ha esito positivo.

Se il callback ha esito negativo, PERFLIB restituirà il codice di errore al consumer se la richiesta è PERF_ADD_COUNTER, PERF_ENUM_INSTANCES o PERF_COLLECT_START; in caso contrario, il codice di errore viene ignorato.

Commenti

Se l'attributo callback dell'elemento del provider è "personalizzato" o è stato usato l'argomento -NotificationCallback quando si chiama CTRPP, è necessario implementare questa funzione. Passare il nome della funzione di callback a CounterInitialize.

Windows Vista: La funzione CounterInitialize è denominata PerfAutoInitialize. Lo strumento CTRPP genera anche uno scheletro di questo callback che include tutti i codici di richiesta. Si aggiunge quindi il codice ai codici di richiesta che si desidera supportare e rimuovere gli altri.

Il callback deve essere completato entro un secondo. Se il callback non viene completato in tempo, PERFLIB continua con la richiesta del consumer e ignora il valore restituito del callback al termine.

Esempio

Nell'esempio seguente viene illustrata una semplice implementazione di una funzione ControlCallback .

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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	perflib.h

Condividi tramite