Compartilhar via

estrutura PCW_REGISTRATION_INFORMATION (wdm.h)

A estrutura PCW_REGISTRATION_INFORMATION fornece detalhes sobre o provedor e o contador. A maioria dos desenvolvedores usará as funções CTRPP-generated RegisterXxx ou InitRegistrationInformationXxx em vez de usar essa estrutura diretamente.

Sintaxe

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

Membros

Version

O valor numérico que especifica a versão dos Contadores de Desempenho para Windows (PCW) que o provedor requer.

Ao executar no Windows antes da 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), o campo Version 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). Se o campo Version estiver definido como um valor não reconhecido, PcwRegister retornará STATUS_INVALID_PARAMETER_2.

Ao usar as funções RegisterXxx ou InitRegistrationInformationXxx geradas por CTRPP, o campo Version será definido como PCW_CURRENT_VERSION, o que equivale a um dos seguintes valores, dependendo do valor de tempo de compilação de NTDDI_VERSION:

Condição PCW_CURRENT_VERSION valor
NTDDI_VERSION < NTDDI_WIN10_FE PCW_VERSION_1 (0x0100)
NTDDI_VERSION >= NTDDI_WIN10_FE PCW_VERSION_2 (0x0200)

Se o código for criado com NTDDI_VERSION >= NTDDI_WIN10_FE mas precisar ser executado em uma versão anterior do Windows, você precisará definir Version = PCW_VERSION_1 conforme descrito na documentação do PcwRegister.

Name

Um ponteiro para a cadeia de caracteres que contém o nome do contador a ser registrado. Essa cadeia de caracteres não deve ser NULL ou em branco.

Observe que as comparações de nome do contador não diferenciam maiúsculas de minúsculas. Se o mesmo nome do contador for usado em dois registros de contador, os consumidores coletarão dados de ambos os registros.

CounterCount

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

Counters

Uma matriz de descritores para os contadores desse contador. As informações dos descritores serão usadas ao extrair valores de contador de blocos de dados fornecidos por chamadas para PcwCreateInstance ou PcwAddInstance.

Callback

Um ponteiro para a função opcional de retorno de chamada PCW_CALLBACK que notifica o provedor sobre eventos relacionados a esse contraconjunto. Esse campo poderá ser NULL se o retorno de chamada não for necessário (ou seja, se as instâncias de contraconjunto forem gerenciadas por meio de PcwCreateInstance e PcwCloseInstance).

CallbackContext

Um valor de ponteiro que será passado para a função de retorno de chamada PCW_CALLBACK definida pelo provedor sempre que ela for invocada.

Flags

O campo Flags só está disponível quando NTDDI_VERSION >= NTDDI_WIN10_MN.

O campo Flags será ignorado se o campo Version for menor que PCW_VERSION_2.

O campo Flags permite um comportamento especial de PcwRegister. Defina como uma combinação de um ou mais valores PCW_REGISTRATION_FLAGS:

PCW_REGISTRATION_FLAGS Significado
PcwRegistrationNone (0x0) Padrão (nenhum comportamento especial é necessário).
PcwRegistrationSiloNeutral (0x1) Indica que esse registro deve estar visível para os consumidores em todos os silos do servidor. Por padrão, um registro é visível apenas para os consumidores no silo do servidor que estava ativo quando o registro foi criado (ou seja, o registro anexado ao thread quando PcwRegister foi chamado).

Observações

A função PcwRegister usa um parâmetro Info que é um ponteiro para essa estrutura.

Função InitRegistrationInformationXxx gerada por CTRPP

A maioria dos desenvolvedores não precisa usar PCW_REGISTRATION_INFORMATION diretamente. Em vez disso, eles compilarão um manifesto com a ferramenta CTRPP e usarão as funções RegisterXxx ou InitRegistrationInformationXxx do cabeçalho gerado por CTRPP. A função Registro gerada chama InitRegistrationInformation e, em seguida, chama PcwRegister (consulte PcwRegister para obter detalhes). A função InitRegistrationInformation gerada terá esta aparência:

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

A função InitRegistrationInformation gerada por CTRPP será nomeada PrefixoInitRegistrationInformationCounterset. prefixo geralmente está em branco, mas pode estar presente se o parâmetro -prefix foi usado na linha de comando CTRPP. counterset é o nome do contador, conforme especificado no manifesto. A função InitRegistrationInformation gerada inicializará a estrutura de PCW_REGISTRATION_INFORMATION fornecida com valores dos parâmetros de função e do manifesto.

A função InitRegistrationInformation gerada por CTRPP pode, opcionalmente, verificar se os tamanhos dos membros da estrutura correspondem aos tamanhos declarados no manifesto. Por padrão, CTRPP_VERIFY_COUNTER_SIZES é definido como 0, desabilitando essa verificação. Para habilitar essa verificação, #define CTRPP_VERIFY_COUNTER_SIZES 1 antes de incluir o cabeçalho gerado por CTRPP. Se a verificação estiver habilitada, uma incompatibilidade de tamanho disparará um erro de compilação devido à falha da condição de C_ASSERT.

Requisitos

Requisito Valor
cabeçalho wdm.h (include Wdm.h, Ntddk.h)

Consulte também

estrutura PCW_COUNTER_DESCRIPTOR

PCW_CALLBACK função de retorno de chamada

função PcwRegister

CTRPP

  • Last updated on