Export (0) Print
Expand All
Expand Minimize

ExCreateCallback routine

The ExCreateCallback routine either creates a new callback object or opens an existing callback object on behalf of the caller.

Syntax


NTSTATUS ExCreateCallback(
  _Out_  PCALLBACK_OBJECT *CallbackObject,
  _In_   POBJECT_ATTRIBUTES ObjectAttributes,
  _In_   BOOLEAN Create,
  _In_   BOOLEAN AllowMultipleCallbacks
);

Parameters

CallbackObject [out]

A pointer to a location that receives a pointer to a callback object, which is an opaque, system structure. If the ExCreateCallback call succeeds, the routine writes the address of the newly created or opened callback object to this location. The callback object pointer obtained from this routine can be supplied as a parameter to the ExRegisterCallback or ExNotifyCallback routine.

ObjectAttributes [in]

A pointer to an OBJECT_ATTRIBUTES structure that contains the callback object's attributes. This structure was previously initialized by the InitializeObjectAttributes routine.

Create [in]

Whether to create a callback object. Set to TRUE to create a new callback object if the requested object cannot be opened. Otherwise, set to FALSE.

AllowMultipleCallbacks [in]

Whether a newly created callback object should allow multiple registered callback routines. Set to TRUE to allow multiple registered callback routines. Otherwise, set to FALSE. This parameter is ignored when Create is FALSE or when opening an existing object.

Return value

ExCreateCallback returns STATUS_SUCCESS if a callback object was opened or created. Otherwise, it returns an NTSTATUS error code to indicate the nature of the failure.

Remarks

A driver calls ExCreateCallback to create a new callback object or to open an existing callback object. After the object has been created or opened, other components can call the ExRegisterCallback routine to register callback routines with the callback object.

Before calling ExCreateCallback, the driver must call InitializeObjectAttributes to initialize the OBJECT_ATTRIBUTES structure for the callback object. Unnamed callback objects are not permitted. The caller must specify a name for the object; otherwise, the call fails with STATUS_UNSUCCESSFUL. The caller should specify the OBJ_PERMANENT attribute in the callback object to prevent the object from being deleted before it can be registered with the object manager. The caller should also specify any other attributes, such as OBJ_CASE_INSENSITIVE, that might be needed.

When all operations have been completed with the callback object, the driver must delete the object to prevent a memory leak. For information about deleting an object that was created with the OBJ_PERMANENT object attribute, see ObDereferenceObject.

The following table shows the callback objects that the operating system creates for use by drivers.

Callback object nameUsage

\Callback\SetSystemTime

The operating system calls any callback routines registered for this object whenever the system time changes.

\Callback\PowerState

The operating system calls any callback routines registered for this object whenever certain system power characteristics change. When a driver registers for callback notification (by calling ExRegisterCallback), it can specify the changes for which it should be notified.

 

For more information about callback objects, see Callback Objects.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

DDI compliance rules

IrqlExPassive, HwStorPortProhibitedDDIs

See also

ExRegisterCallback
ExNotifyCallback
InitializeObjectAttributes
ObDereferenceObject

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft