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 RegisterXxx ou InitRegistrationInformationXxx geradas por CTRPP em vez de usar essa estrutura diretamente.
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;
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). |
A função PcwRegister usa um Info
parâmetro que é um ponteiro para essa estrutura.
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.
Requisito | Valor |
---|---|
Cabeçalho | wdm.h (inclua Wdm.h, Ntddk.h) |
estrutura PCW_COUNTER_DESCRIPTOR