IUPnPServiceAsync::BeginSubscribeToEvents method (upnp.h)

Article
02/22/2024

The BeginSubscribeToEvents initiates event subscription in asynchronous mode and registers the application callback with the UPnP framework.

Syntax

HRESULT BeginSubscribeToEvents(
  [in]           IUnknown         *pUnkCallback,
  [in, optional] IUPnPAsyncResult *pAsyncResult,
  [out]          PULONG64         pullRequestID
);

Parameters

[in] pUnkCallback

Specifies the reference to the interface object that contains the callback to register. This object must either support the IUPnPServiceCallback interface or the IDispatch interface.

[in, optional] pAsyncResult

Specifies a reference to IUPnPAsyncResult object. When the BeginSubscribeToEvents call is complete, UPnP will use the IUPnPAsyncResult::AsyncOperationComplete method to notify the control point.

[out] pullRequestID

Pointer to a 64-bit ULONG value used to identify the asynchronous I/O operation. The control point must use this handle while ending or cancelling the operation via EndSubscribeToEvents or CancelAsyncOperation.

Return value

Returns S_OK on success. Otherwise, the method returns a COM error code defined in WinError.h or one of the following values:

Return code	Description
E_FAIL	Failed to initiate the asynchronous operation.

Note Some values can indicate that an error was received from a UPnP-certified device. For more information, see Device Error Codes.

Remarks

Event subscription should be completed before querying any evented state variables with BeginQueryStateVariable. If this does not occur, UPNP_E_VARIABLE_VALUE_UNKNOWN is returned, and event subscription will take place internally. As a result, the next BeginQueryStateVariable call will succeed.

Note For services without evented variables, BeginQueryStateVariable will always behave as expected.

Calling this method multiple times will result in the addition of multiple callbacks.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	upnp.h
DLL	Upnp.dll