The AssignContext method registers a context and a driver-supplied cleanup callback function for the object.

HRESULT 
  AssignContext(
    IN IObjectCleanup*  pCleanupCallback,
    IN void*  pContext
    );

Parameters

pCleanupCallback

A pointer to the IObjectCleanup interface that contains the cleanup callback function, which performs cleanup operations for the object if it becomes invalid. This parameter is optional. The driver can pass NULL if the driver does not require notification when the object is cleaned up.

pContext

A pointer to the context to register. NULL is a valid context.

Return Value

AssignContext returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Comments

A driver calls AssignContext to register a context and to request notification when the object becomes invalid. In a AssignContext call, the driver passes a pointer to the IObjectCleanup interface in the pCleanupCallback parameter to register IObjectCleanup. Note that the framework internally holds a reference to the supplied IObjectCleanup interface while the object is valid. When the object becomes invalid, the framework calls the IObjectCleanup::OnCleanup method to notify the driver. The framework automatically releases the reference to the supplied IObjectCleanup after calling IObjectCleanup::OnCleanup.

At any given time, only one context that is associated with each object instance can exist. Attempts to register additional contexts fail.

A context can be associated only with an object that is in a valid state. For example, an attempt to associate a context with an object that is in the process of deletion fails.

Because the context is not a Component Object Model (COM) interface, the driver must not treat the context as such. For example, the driver cannot call the AddRef method on the context.

The IWDFObject::RetrieveContext method can be used to retrieve the context that was previously registered through AssignContext.

Example

For a code example of how to use the AssignContext method, see IWDFIoTarget::FormatRequestForWrite.

Requirements

Headers: Declared in Wudfddi.h. Include Wudfddi.h.

See Also

IObjectCleanup, IObjectCleanup::OnCleanup, IWDFObject::RetrieveContext

APIScan Requirements

Header: Wudfddi.h
Function: IWDFObject::AssignContext