Função PcwCreateInstance (wdm.h)

A PcwCreateInstance função cria uma nova instância de contraconjunto. A maioria dos desenvolvedores usará uma função CreateXxx gerada por CTRPP em vez de chamar essa função diretamente.

Sintaxe

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

Parâmetros

[out] Instance

Um ponteiro para receber a instância recém-criada. A instância deve ser fechada usando PcwCloseInstance.

[in] Registration

Um ponteiro para o registro de contador que possui essa instância. O registro é criado usando PcwRegister.

[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] 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. Os blocos de dados referenciados pelos descritores podem ser acessados a qualquer momento e devem permanecer válidos até que a instância seja fechada por PcwCloseInstance ou PcwUnregister.

Retornar valor

PcwCreateInstance retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	A instância foi criada com êxito.
STATUS_INVALID_PARAMETER_4	O número de estruturas, especificadas por Count, não é válido para o provedor registrado.
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 PcwCreateInstance especificar que o primeiro bloco de dados é de 50 bytes, esse erro status será retornado.
STATUS_INTEGER_OVERFLOW	O tamanho da estrutura, especificado por Count, estoura o buffer de dados.

Comentários

Os provedores de contraconjunto podem fornecer informações ao consumidor por meio de dois sistemas diferentes:

• O provedor pode fornecer uma PCW_CALLBACK função que será invocada pela Biblioteca de Contadores de Desempenho, conforme necessário, para coletar dados. Para obter mais informações sobre esse sistema, consulte a documentação para PCW_CALLBACK.
• O provedor pode usar PcwCreateInstance e PcwCloseInstance manter uma lista de instâncias disponíveis e os dados correspondentes do contador. Esse sistema é simples de implementar, mas limitado em flexibilidade.

Antes que o provedor use essa função, o provedor deve chamar a PcwRegister função para criar um registro.

Quando uma nova instância chega (por exemplo, quando um dispositivo está conectado), o provedor deve alocar e inicializar um bloco de dados para a instância, chamar PcwCreateInstance com o nome e o bloco de dados da instância e, em seguida, manter os valores no bloco de dados atualizados com valores de contador para a instância. Quando a instância se torna inválida (por exemplo, quando um dispositivo é desconectado), o provedor deve chamar PcwCloseInstance e, em seguida, excluir o bloco de dados.

O provedor deve manter blocos de dados (geralmente em pool paginado ou nãopagado) contendo os valores atuais do contador para cada instância.

PcwCreateInstance atribuirá automaticamente uma ID exclusiva para a instância. Para fornecer valores específicos para a ID da instância, implemente uma PCW_CALLBACK função em vez de usar PcwCreateInstance.

Use a função PcwCloseInstance para fechar a instância.

Função CreateXxx gerada por CTRPP

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

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

A função Create gerada pelo CTRPP será chamada de PrefixoCreateCounterset. 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á PcwCreateInstance. Observe que a função faz referência a uma variável Counterset (MyCounterset no exemplo), que é uma variável global que contém o identificador de registro de contador inicializado pela função RegisterXxx gerada por CTRPP.

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 PcwCloseInstance

Função PcwRegister