Funzione PcwAddInstance (wdm.h)

La PcwAddInstance funzione aggiunge l'istanza specificata del contatore al buffer consumer. La maggior parte degli sviluppatori userà una funzione AddXxx generata da CTRPP anziché chiamare direttamente questa funzione. Per altre informazioni, vedere Osservazioni riportate di seguito.

Sintassi

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

Parametri

[in] Buffer

Handle per il buffer gestito dal sistema a cui verrà aggiunta l'istanza del contatore. Quando il buffer proviene da una PcwCallbackEnumerateInstances notifica, PcwAddInstance registra solo il nome e l'ID dell'istanza. Quando il buffer proviene da una PcwCallbackCollectData notifica, PcwAddInstance registra il nome, l'ID e i dati (valori contatori) dell'istanza.

[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] Id

Valore numerico che specifica l'oggetto (identificatore) associato all'istanza Id del contatore.

Id I valori di istanza DEVONO essere stabili nel tempo (la stessa istanza deve usare lo stesso Id valore per tutte le chiamate del callback), deve essere univoco (ad esempio, non usare 0 per tutte le istanze) e deve essere minore di 0xFFFFFFFE (non usare PCW_ANY_INSTANCE_ID per alcuna istanza). Se possibile, l'istanza Id deve essere significativa (ad esempio, un contatore processo potrebbe usare un PID come Id) anziché arbitrario (ad esempio un numero di sequenza).

[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.

Valore restituito

PcwAddInstance restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	L'istanza è stata aggiunta correttamente al buffer.
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 PcwAddInstance specifica che il primo blocco di dati è di 50 byte, viene restituito lo stato di errore.

Commenti

La PcwAddInstance funzione deve essere chiamata dalla routine definita dal provider PCW_CALLBACK quando il tipo di notifica è PcwCallbackEnumerateInstances o PcwCallbackCollectData. L'oggetto BufferInfo da usare proviene dal parametro per la PCW_CALLBACK routine, ad esempio Info->EnumerateInstances.Buffer o Info->CollectData.Buffer.

Quando viene chiamato per una PcwCallbackEnumerateInstances notifica, PcwAddInstance aggiunge i Name valori e Id al buffer. Quando viene chiamato per una PcwCallbackCollectData notifica, aggiunge i Namevalori di PcwAddInstance dati , Ide contatore al buffer.

Funzione Add** generata da CTRPP

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

EXTERN_C __inline NTSTATUS
AddMyCounterset(
    __in PPCW_BUFFER Buffer,
    __in PCUNICODE_STRING Name,
    __in ULONG Id,
    __in_opt const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

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

    return PcwAddInstance(Buffer,
                          Name,
                          Id,
                          1,
                          Data);
}

La funzione Add generate da CTRPP verrà denominata PrefixAddCounterset. 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 PcwAddInstance.

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

PCW_CALLBACK funzione di callback