Função PcwRegister (wdm.h)

A PcwRegister função cria um novo registro de contador. A maioria dos desenvolvedores usará uma função RegisterXxx gerada por CTRPP em vez de chamar essa função diretamente.

Sintaxe

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

Parâmetros

[out] Registration

Um ponteiro para um PPCW_REGISTRATION. Recebe o identificador para o novo registro. O registro deve ser fechado usando PcwUnregister.

[in] Info

Um ponteiro para uma estrutura PCW_REGISTRATION_INFORMATION que contém os detalhes sobre o contador que está sendo registrado.

Retornar valor

PcwRegister retorna um dos seguintes valores:

PcwRegister pode retornar STATUS_INVALID_PARAMETER_2 nos seguintes casos:

• O Info->Name->Length campo é 0 ou não é um múltiplo de sizeof(WCHAR).

• O Info->Version campo não corresponde a um valor com suporte para esta versão do Windows. Ao ser executado no Windows antes da 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), o Version campo deve ser definido como PCW_VERSION_1 (0x100). Ao executar no Windows 10.0.19645 e posterior (NTDDI_VERSION >= NTDDI_VERSION_MN), isso pode ser definido como PCW_VERSION_1 (0x100) ou PCW_VERSION_2 (0x200).

• O Info->Flags campo contém um valor não reconhecido pela versão em execução do Windows.

Comentários

O provedor chama essa função para criar um novo registro de contador. Todos os argumentos de entrada são capturados para que o chamador não precise manter uma cópia deles.

Por padrão, o novo contador é visível apenas para o silo do servidor que estava ativo no momento do registro (ou seja PcwRegister , associa o registro recém-criado ao silo do servidor que foi anexado ao thread quando PcwRegister é chamado). Se estiver em execução no Windows 10.0.19645 e posterior (NTDDI_VERSION >= NTDDI_VERSION_MN) você poderá criar um registro de contador visível para todos os silos do servidor definindo PCW_REGISTRATION_INFORMATION::Version como PCW_VERSION_2 e definindo PCW_REGISTRATION_INFORMATION::Flags como PcwRegistrationSiloNeutral.

Função RegisterXxx gerada por CTRPP

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

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

A função Registro gerada por CTRPP será chamadade Prefix Register Counterset. 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 Register gerada invocará a função PrefixInitRegistrationInformationCounterset para inicializar uma PCW_REGISTRATION_INFORMATION estrutura e, em seguida, invocará PcwRegister para criar um novo registro e armazenará o identificador na variável Counterset global (declarada no cabeçalho gerado por CTRPP, MyCounterset no exemplo).

Em alguns casos, a função Adicionar gerada por CTRPP pode não ser apropriada.

• Se você precisar compilar com NTDDI_VERSION >= NTDDI_VERSION_FE , mas precisar ser executado em versões anteriores do Windows, a função Registrar gerada pelo CTRPP não funcionará porque define RegInfo.Version = PCW_CURRENT_VERSION. Quando NTDDI_VERSION >= NTDDI_VERSION_FE, PCW_CURRENT_VERSION será definido como PCW_VERSION_2, causando o retorno de PcwRegister um erro.

• Se você precisar dar suporte a vários registros de contraconjunto (por exemplo, para dar suporte a um registro separado por silo de servidor), a função Registrar gerada por CTRPP não funcionará porque armazenará o identificador retornado em uma variável global.

• Se você quiser criar um registro de contraconjunto neutro de silo, a função Registrar gerada por CTRPP não funcionará porque não há como alterar o valor de antes de RegInfo.Flags chamar PcwRegister.

Nesses casos, use código como o seguinte em vez de chamar a função Registro gerada pelo CTRPP:

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

A função InitRegistrationInformationXxxx gerada por CTRPP inicializa a RegInfo estrutura com base em declarações do manifesto. Para obter mais informações sobre a função InitRegistrationInformation gerada, consulte a documentação para PCW_REGISTRATION_INFORMATION.

Se estiver usando suas próprias variáveis de identificador em vez de Counterset para armazenar o identificador, talvez você também precise chamar PcwUnregister e PcwCreateInstance diretamente em vez de usar as funções UnregisterXxx e CreateXxx geradas por CTRPP.

Requisitos

Confira também

PcwUnregister

_PCW_REGISTRATION_INFORMATION