IWDFDevice::PostEvent method (wudfddi.h)

Article
10/21/2021

[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 PostEvent method asynchronously notifies applications that are waiting for the specified event from a driver.

Syntax

HRESULT PostEvent(
  [in] REFGUID        EventGuid,
  [in] WDF_EVENT_TYPE EventType,
  [in] BYTE           *pbData,
  [in] DWORD          cbDataSize
);

Parameters

[in] EventGuid

The GUID for the event. The GUID is determined by the application and the driver and is opaque to the framework.

[in] EventType

A WDF_EVENT_TYPE-typed value that identifies the type of event. In the current version of UMDF, the driver must set EventType to WdfEventBroadcast (1). WdfEventBroadcast indicates that the event is broadcast. Applications can subscribe to WdfEventBroadcast-type events. To receive broadcast events, the application must register for notification through the Microsoft Win32 RegisterDeviceNotification function. WdfEventBroadcast-type events are exposed as DBT_CUSTOMEVENT-type events to applications.

[in] pbData

A pointer to a buffer that contains data that is associated with the event. NULL is a valid value.

[in] cbDataSize

The size, in bytes, of data that pbData points to. Zero is a valid size value if pbData is set to NULL.

The maximum size of the event data is slightly less than MAXUSHORT (64 KB). The precise upper limit is (0xFFFF - FIELD_OFFSET(TARGET_DEVICE_CUSTOM_NOTIFICATION, CustomDataBuffer)).

Return value

PostEvent returns one of the following values:

Return code	Description
S_OK	The event data was successfully sent to the operating system.
HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY)	The data size that the cbDataSize parameter specifies is larger than the maximum allowable size.
E_INVALIDARG	The EventType parameter is not set to WdfEventBroadcast (1).
E_OUTOFMEMORY	PostEvent could not allocate memory that was required for it to complete.

PostEvent might also return other HRESULT values.

Remarks

When the driver calls IWDFDevice::PostEvent to notify the requesting application about an event, UMDF sends the event to the operating system. The operating system sends the event on to the requesting application in an asynchronous operation. If the operating system initially returns no error, the driver receives no error (S_OK). However, later, if the operating system receives an error while it attempts to deliver the event (possibly because of a low memory condition), the operating system is unable to inform the driver about the error. Because of the asynchronous nature of this event notification, delivery of the event to the requesting application is not guaranteed. If event information is lost on its way up to the requesting application, the application should be able to recover from the lost event.

For information about creating device events, see Using Device Interfaces in UMDF Drivers.

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