Edit

Share via

IUPnPServiceAsync::BeginSubscribeToEvents method (upnp.h)

  • Article

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

See also

IUPnPServiceAsync

IUPnPServiceAsync::CancelAsyncOperation

IUPnPServiceAsync::EndSubscribeToEvents