Função PcwAddInstance (wdm.h)

A PcwAddInstance função adiciona a instância especificada do contador ao buffer do consumidor. A maioria dos desenvolvedores usará uma função AddXxx gerada por CTRPP em vez de chamar essa função diretamente. Consulte Comentários abaixo para obter mais informações.

Sintaxe

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

Parâmetros

[in] Buffer

Um identificador para o buffer gerenciado pelo sistema ao qual a instância do contador será adicionada. Quando o buffer vem de uma PcwCallbackEnumerateInstances notificação, PcwAddInstance registrará apenas o Nome e a ID da instância. Quando o buffer for proveniente de uma PcwCallbackCollectData notificação, PcwAddInstance registrará o Nome, a ID e os Dados (valores de contador) da instância.

[in] Name

Um ponteiro para a cadeia de caracteres Unicode que contém o nome da instância do contador. Isso não deve ser NULL.

Os valores de instância Name DEVEM ser estáveis ao longo do tempo (a mesma instância lógica deve usar o mesmo Name valor para todas as invocações do retorno de chamada) e DEVE ser exclusiva. Se o contador for registrado como instância única, a instância Name deverá estar em branco (0 comprimento). Se o contador registrado como várias instâncias, a instância Name não deverá estar em branco. A correspondência de nomes de instância não diferencia maiúsculas de minúsculas, portanto Name , os valores não devem ser diferentes apenas por caso.

[in] Id

Um valor numérico que especifica o Id (identificador) associado à instância do contador.

Os valores de instância Id DEVEM ser estáveis ao longo do tempo (a mesma instância deve usar o mesmo Id valor para todas as invocações do retorno de chamada), deve ser exclusivo (por exemplo, não usar 0 para todas as instâncias) e deve ser menor que 0xFFFFFFFE (não use PCW_ANY_INSTANCE_ID para instâncias). Quando possível, a instância Id deve ser significativa (por exemplo, um contador de processo pode usar um PID como o Id) em vez de arbitrário (por exemplo, um número de sequência).

[in] Count

O número de descritores fornecidos no Data parâmetro .

[in] Data

Uma matriz de descritores para os blocos de dados do provedor que contêm os valores de contador dessa instância.

Retornar valor

PcwAddInstance retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	A instância foi adicionada com êxito ao buffer.
STATUS_INVALID_BUFFER_SIZE	Um dos blocos de dados do provedor é muito pequeno. Por exemplo, suponha que durante a chamada para PcwRegister, o provedor especifique que o contador X está no deslocamento de 100 do primeiro bloco de dados do tamanho 4 bytes. Se a chamada para PcwAddInstance especificar que o primeiro bloco de dados é de 50 bytes, esse erro status será retornado.

Comentários

A PcwAddInstance função deve ser chamada pela rotina de PCW_CALLBACK definida pelo provedor quando o tipo de notificação for PcwCallbackEnumerateInstances ou PcwCallbackCollectData. O Buffer a ser usado vem do Info parâmetro para a PCW_CALLBACK rotina, por exemplo Info->EnumerateInstances.Buffer , ou Info->CollectData.Buffer.

Quando chamado para uma PcwCallbackEnumerateInstances notificação, PcwAddInstance adiciona os Name valores e Id ao buffer. Quando chamado para uma PcwCallbackCollectData notificação, PcwAddInstance adiciona os Namevalores de dados do contador , Ide ao buffer.

Função Add*** gerada pelo CTRPP

A maioria dos desenvolvedores não precisa chamar PcwAddInstance diretamente. Em vez disso, eles compilarão um manifesto com a ferramenta CTRPP e usarão a função Add*** do cabeçalho gerado por CTRPP. A função gerada terá esta aparência:

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

A função Adicionar gerada por CTRPP será denominada PrefixoAddCounterset. O prefixo geralmente está em branco, mas pode estar presente se o -prefix parâmetro tiver sido usado na linha de comando CTRPP. Counterset é o nome do contador, conforme especificado no manifesto. A função terá parâmetros de dados com base nas estruturas definidas no manifesto. A função encapsulará os blocos de dados fornecidos pelo usuário em uma matriz de PCW_DATA estruturas e, em seguida, chamará PcwAddInstance.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (inclua Wdm.h, Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Confira também

função de retorno de chamada PCW_CALLBACK