WdfObjectAllocateContext function (wdfobject.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfObjectAllocateContext method allocates context space for a specified framework object.

Syntax

NTSTATUS WdfObjectAllocateContext(
  [in]  WDFOBJECT              Handle,
  [in]  PWDF_OBJECT_ATTRIBUTES ContextAttributes,
  [out] PVOID                  *Context
);

Parameters

[in] Handle

A handle to a framework object.

[in] ContextAttributes

A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that describes the context space.

[out] Context

A pointer to a location that receives a pointer to the allocated context space.

Return value

WdfObjectAllocateContext returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_OBJECT_NAME_INVALID	The ContextTypeInfo member of the WDF_OBJECT_ATTRIBUTES structure that the ContextAttributes parameter specified was invalid.
STATUS_INSUFFICIENT_RESOURCES	Context space could not be allocated.
STATUS_OBJECT_NAME_EXISTS	The driver has already allocated context space that matches the ContextTypeInfo member of the WDF_OBJECT_ATTRIBUTES structure that ContextAttributes specifies. In this situation, the pointer in the Context parameter receives a pointer to the existing context space and does not allocate duplicate context space.
STATUS_DELETE_PENDING	The object that the Handle parameter specifies is being deleted. In this situation, the framework does not allocate context space.

This method might also return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

Typically, drivers create object context space by specifying a WDF_OBJECT_ATTRIBUTES structure when they call a framework object's creation method, such as WdfDeviceCreate.

If you want your driver to allocate more than one type of context space to some of its objects, the driver can call WdfObjectAllocateContext one or more times after it has called an object's creation method. Each call to WdfObjectAllocateContext must specify a different context type. (The ContextTypeInfo member of the WDF_OBJECT_ATTRIBUTES structure identifies the context type.)

If your driver calls WdfObjectAllocateContext more than once for a given object, you can provide separate EvtCleanupCallback and EvtDestroyCallback callback functions for each context.

When calling WdfObjectAllocateContext, do not specify a ParentObject in the WDF_OBJECT_ATTRIBUTES structure.

When the framework allocates context space for an object, it also zero-initializes the context space.

For more information about object context space, see Framework Object Context Space.

For more information about the cleanup rules for a framework object hierarchy, see Framework Object Life Cycle.

Examples

The following code example creates context space for a request object. The context space is based on the example's REQUEST_CONTEXT structure.

typedef struct _REQUEST_CONTEXT {
  WDFMEMORY InputMemoryBuffer;
  WDFMEMORY OutputMemoryBuffer;
} REQUEST_CONTEXT, *PREQUEST_CONTEXT;

PREQUEST_CONTEXT  reqContext = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &attributes,
                                        REQUEST_CONTEXT
                                        );
status = WdfObjectAllocateContext(
                                  Request,
                                  &attributes,
                                  &reqContext
                                  );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfobject.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf)