IWDFObject::AssignContext method (wudfddi.h)
[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]
The AssignContext method registers a context and a driver-supplied cleanup callback function for the object.
Syntax
HRESULT AssignContext(
[in, optional] __drv_aliasesMem IObjectCleanup *pCleanupCallback,
[in, optional] __drv_aliasesMem void *pContext
);
Parameters
[in, optional] 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.
[in, optional] 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.
Remarks
A driver calls AssignContext to register a context and to request notification when the object becomes invalid. In an 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.
Examples
For a code example of how to use the AssignContext method, see IWDFIoTarget::FormatRequestForWrite.
Requirements
| Requirement | Value |
|---|---|
| End of support | Unavailable in UMDF 2.0 and later. |
| Target Platform | Desktop |
| Minimum UMDF version | 1.5 |
| Header | wudfddi.h (include Wudfddi.h) |
| DLL | WUDFx.dll |