estrutura PCW_REGISTRATION_INFORMATION (wdm.h)

Artigo
08/08/2023

A estrutura PCW_REGISTRATION_INFORMATION fornece detalhes sobre o provedor e o contador. A maioria dos desenvolvedores usará as funções RegisterXxx ou InitRegistrationInformationXxx geradas por CTRPP 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 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). Se o Version campo for 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 Version campo será definido como PCW_CURRENT_VERSION, que é equivalente 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 compilado 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 de 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 de conjunto de contadores for usado em dois registros de contraconjunto, os consumidores coletarão dados de ambos os registros.

CounterCount

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

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 de retorno de chamada opcional 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 contador forem gerenciadas por meio PcwCreateInstance de e PcwCloseInstance).

CallbackContext

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

Flags

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

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

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

PCW_REGISTRATION_FLAGS	Significado
PcwRegistrationNone (0x0)	Padrão (nenhum comportamento especial é necessário).
PcwRegistrationSiloNeutral (0x1)	Indica que esse registro deve ser 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 que foi anexado ao thread quando `PcwRegister` foi chamado).

Comentários

A função PcwRegister usa um Info parâmetro 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 Register 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á denominada PrefixInitRegistrationInformationCounterset. 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 InitRegistrationInformation gerada inicializará a estrutura fornecida PCW_REGISTRATION_INFORMATION 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 esse marcar. Para habilitar esse marcar, #define CTRPP_VERIFY_COUNTER_SIZES 1 antes de incluir o cabeçalho gerado por CTRPP. Se o marcar estiver habilitado, uma incompatibilidade de tamanho disparará um erro de compilação devido à falha da condição de C_ASSERT.