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 InitializeObjectAttributes .
[in] Create
Se deseja criar um objeto de retorno de chamada. 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 Create é FALSE ou ao abrir um objeto existente.
Retornar valor
ExCreateCallback retornará STATUS_SUCCESS se um objeto de retorno de chamada tiver sido aberto ou criado. Caso contrário, ele retorna um código de erro NTSTATUS para indicar a natureza da falha.
Comentários
Um driver chama ExCreateCallback para criar um novo objeto de retorno de chamada ou para abrir um objeto de retorno de chamada existente. Depois que o objeto for 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 para o 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 um vazamento 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 a hora do sistema é alterada. |
| \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 são alteradas. Quando um driver se registra para notificação de retorno de chamada (chamando ExRegisterCallback), ele pode especificar as alterações para as quais ele deve ser notificado. |
Para obter mais informações sobre objetos de retorno de chamada, consulte Objetos de retorno de chamada.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 2000. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| Regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm), IrqlExPassive |