Funzione PcwCreateInstance (wdm.h)

La PcwCreateInstance funzione crea una nuova istanza del contatore. La maggior parte degli sviluppatori userà una funzione CreateXxx generata da CTRPP anziché chiamare direttamente questa funzione.

Sintassi

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

Parametri

[out] Instance

Puntatore per ricevere l'istanza appena creata. L'istanza deve essere chiusa usando PcwCloseInstance.

[in] Registration

Puntatore alla registrazione del contatore proprietaria di questa istanza. La registrazione viene creata usando PcwRegister.

[in] Name

Puntatore alla stringa Unicode contenente il nome dell'istanza del contatore. Non deve essere NULL.

I valori di istanza Name DEVONO essere stabili nel tempo (la stessa istanza logica deve usare lo stesso Name valore per tutte le chiamate del callback) e DEVE essere univoco. Se il contatore viene registrato come istanza singola, l'istanza Name deve essere vuota (0-length). Se il contatore registrato come istanza multipla, l'istanza Name non deve essere vuota. La corrispondenza dei nomi dell'istanza non è distinzione tra maiuscole e minuscole, pertanto Name i valori non devono essere diversi solo in base al caso.

[in] Count

Numero di descrittori forniti nel Data parametro.

[in] Data

Matrice di descrittori per i blocchi di dati del provider che contengono i valori del contatore di questa istanza. I blocchi di dati a cui fa riferimento i descrittori possono essere accessibili in qualsiasi momento e devono rimanere validi fino a quando l'istanza non viene chiusa da PcwCloseInstance o PcwUnregister.

Valore restituito

PcwCreateInstance restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'istanza è stata creata correttamente.
STATUS_INVALID_PARAMETER_4	Il numero di strutture, specificato da Count, non è valido per il provider registrato.
STATUS_INVALID_BUFFER_SIZE	Uno dei blocchi di dati del provider è troppo piccolo. Si supponga, ad esempio, che durante la chiamata a PcwRegister, il provider specifica che il contatore X è in corrispondenza dell'offset 100 del primo blocco di dati di dimensioni 4 byte. Se la chiamata a PcwCreateInstance specifica che il primo blocco di dati è di 50 byte, viene restituito lo stato di errore.
STATUS_INTEGER_OVERFLOW	La dimensione della struttura, specificata da Count, esegue il overflow del buffer di dati.

Commenti

I provider di contatori possono fornire informazioni al consumer tramite due sistemi diversi:

• Il provider può fornire una PCW_CALLBACK funzione che verrà richiamata dalla libreria contatore prestazioni in base alle esigenze per raccogliere dati. Per altre informazioni su questo sistema, vedere la documentazione per PCW_CALLBACK.
• Il provider può usare PcwCreateInstance e PcwCloseInstance mantenere un elenco di istanze disponibili e i dati del contatore corrispondenti. Questo sistema è semplice da implementare, ma limitato in flessibilità.

Prima che il provider usi questa funzione, il provider deve chiamare la PcwRegister funzione per creare una registrazione.

Quando una nuova istanza arriva (ad esempio quando un dispositivo è collegato), il provider deve allocare e inizializzare un blocco di dati per l'istanza, chiamare PcwCreateInstance con il nome e il blocco dati per l'istanza e quindi mantenere aggiornati i valori nel blocco dati con valori di contatore per l'istanza. Quando l'istanza diventa non valida(ad esempio quando un dispositivo è scollegato), il provider deve chiamare PcwCloseInstance e quindi eliminare il blocco dati.

Il provider deve mantenere i blocchi di dati (in genere in pool di pagine o non paginati) contenenti i valori di contatore correnti per ogni istanza.

PcwCreateInstance assegna automaticamente un ID univoco per l'istanza. Per specificare valori specifici per l'ID istanza, implementare una PCW_CALLBACK funzione anziché usare PcwCreateInstance.

Usare la funzione PcwCloseInstance per chiudere l'istanza.

Funzione CreateXxx generata da CTRPP

La maggior parte degli sviluppatori non deve chiamare PcwCreateInstance direttamente. Verranno invece compilati un manifesto con lo strumento CTRPP e useranno la funzione CreateXxx dall'intestazione generata da CTRPP. La funzione generata avrà un aspetto simile al seguente:

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

La funzione Create generate da CTRPP verrà denominata PrefixCreateCounterset. Il prefisso è in genere vuoto, ma può essere presente se il -prefix parametro è stato usato nella riga di comando CTRPP. Il contatore è il nome del contatore, come specificato nel manifesto. La funzione avrà parametri di dati in base alle strutture definite nel manifesto. La funzione esegue il wrapping dei blocchi di dati forniti dall'utente in una matrice di PCW_DATA strutture e quindi chiama PcwCreateInstance. Si noti che la funzione fa riferimento a una variabile Counterset (MyCounterset nell'esempio), che è una variabile globale che contiene l'handle di registrazione del contatore inizializzato dalla funzione RegisterXxx generata da CTRPP.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Vedi anche

Funzione PcwCloseInstance

Funzione PcwRegister