Função ExCreateCallback (wdm.h)
A rotina ExCreateCallback cria um novo objeto de retorno de chamada ou abre um objeto de retorno de chamada existente em nome do chamador.
Sintaxe
NTSTATUS ExCreateCallback(
[out] PCALLBACK_OBJECT *CallbackObject,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN Create,
[in] BOOLEAN AllowMultipleCallbacks
);
Parâmetros
[out] CallbackObject
Um ponteiro para um local que recebe um ponteiro para um objeto de retorno de chamada, que é uma estrutura opaca do sistema. Se a chamada ExCreateCallback for bem-sucedida, a rotina gravará o endereço do objeto de retorno de chamada recém-criado ou aberto nesse local. O ponteiro do objeto de retorno de chamada obtido dessa rotina pode ser fornecido como um parâmetro para a rotina exRegisterCallback ou ExNotifyCallback.
[in] ObjectAttributes
Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que contém os atributos do objeto de retorno de chamada. Essa estrutura foi inicializada anteriormente pela rotina de InitializeObjectAttributes.
[in] Create
Se um objeto de retorno de chamada deve ser criado. Defina como TRUE para criar um novo objeto de retorno de chamada se o objeto solicitado não puder ser aberto. Caso contrário, defina como FALSE.
[in] AllowMultipleCallbacks
Se um objeto de retorno de chamada recém-criado deve permitir várias rotinas de retorno de chamada registradas. Defina como TRUE para permitir várias rotinas de retorno de chamada registradas. Caso contrário, defina como FALSE. Esse parâmetro é ignorado quando Criar é FALSE ou ao abrir um objeto existente.
Valor de retorno
ExCreateCallback retorna STATUS_SUCCESS se um objeto de retorno de chamada foi aberto ou criado. Caso contrário, ele retornará um código de erro NTSTATUS para indicar a natureza da falha.
Observações
Um driver chama ExCreateCallback para criar um novo objeto de retorno de chamada ou abrir um objeto de retorno de chamada existente. Depois que o objeto tiver sido criado ou aberto, outros componentes poderão chamar a rotina ExRegisterCallback para registrar rotinas de retorno de chamada com o objeto de retorno de chamada.
Antes de chamar ExCreateCallback, o driver deve chamar InitializeObjectAttributes para inicializar a estrutura OBJECT_ATTRIBUTES do objeto de retorno de chamada. Objetos de retorno de chamada sem nome não são permitidos. O chamador deve especificar um nome para o objeto; caso contrário, a chamada falhará com STATUS_UNSUCCESSFUL. O chamador deve especificar o atributo OBJ_PERMANENT no objeto de retorno de chamada para impedir que o objeto seja excluído antes que ele possa ser registrado no gerenciador de objetos. O chamador também deve especificar quaisquer outros atributos, como OBJ_CASE_INSENSITIVE, que possam ser necessários.
Quando todas as operações tiverem sido concluídas com o objeto de retorno de chamada, o driver deverá excluir o objeto para evitar uma perda de memória. Para obter informações sobre como excluir um objeto que foi criado com o atributo de objeto OBJ_PERMANENT, consulte ObDereferenceObject.
A tabela a seguir mostra os objetos de retorno de chamada que o sistema operacional cria para uso por drivers.
| Nome do objeto de retorno de chamada | Uso |
|---|---|
| \Callback\SetSystemTime | O sistema operacional chama todas as rotinas de retorno de chamada registradas para esse objeto sempre que o tempo do sistema é alterado. |
| \Callback\PowerState | O sistema operacional chama todas as rotinas de retorno de chamada registradas para esse objeto sempre que determinadas características de energia do sistema forem alteradas. Quando um driver se registra para notificação de retorno de chamada (chamando ExRegisterCallback), ele pode especificar as alterações para as quais deve ser notificado. |
Para obter mais informações sobre objetos de retorno de chamada, consulte Objetos de Retorno de Chamada.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 2000. |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm), IrqlExPassive |