Edit

IUPnPDeviceFinder::CreateAsyncFind method (upnp.h)

  • Article

The CreateAsyncFind method creates an asynchronous search operation.

Syntax

HRESULT CreateAsyncFind(
  [in]  BSTR     bstrTypeURI,
  [in]  DWORD    dwFlags,
  [in]  IUnknown *punkDeviceFinderCallback,
  [out] LONG     *plFindData
);

Parameters

[in] bstrTypeURI

Specifies the uniform resource identifier (URI) for which to search.

[in] dwFlags

Specify zero. This parameter is reserved for future use.

[in] punkDeviceFinderCallback

Reference to an IUnknown interface object that specifies the callback that the UPnP framework must use to communicate the results of this asynchronous search.

The object referred to by pUnkCallback must support either the IUPnPDeviceFinderCallback interface or the IDispatch interface. The object referred to by pUnkCallback might support the IUPnPDeviceFinderAddCallbackWithInterface interface, in addition to the IUPnPDeviceFinderCallback interface.

[out] plFindData

Reference to a LONG that receives the identifier for this particular search. The application must supply this identifier to other asynchronous search methods that are called.

Return value

If the method succeeds, the return value is S_OK. Otherwise, the method returns one of the COM error codes defined in WinError.h.

Remarks

This method returns immediately; the UPnP framework notifies the caller of any search results using the callback specified by pUnkCallback. This method returns a search identifier; the caller must use the IUPnPDeviceFinder::StartAsyncFind to actually begin the search.

In C++, the object referred to by pUnkCallback must support either the IUPnPDeviceFinderCallback interface or the IDispatch interface. Optionally, the object referred to by pUnkCallback might support the IUPnPDeviceFinderAddCallbackWithInterface interface, in addition to the IUPnPDeviceFinderCallback interface. The UPnP framework first queries pUnkCallback for the IUPnPDeviceFinderAddCallbackWithInterface interface. If the interface is not supported, the UPnP framework next queries pUnkCallback for the IUPnPDeviceFinderCallback interface. If it is not supported, the UPnP framework then queries pUnkCallback for the IDispatch interface. If the IDispatch interface is not supported, the UPnP framework returns E_FAIL.

In VBScript, the second argument must be GetRef(funcname), where funcname is the name of the callback subroutine.

In Visual Basic, the callback function must be declared with three parameters. The callback function uses the values specified for each parameter:

  • param1 is the Device object of the new device; it is only valid when param3 is zero.
  • param2 is the UDN of the found or removed device; it is only valid when param3 is zero or one.
  • param3 is the type of callback. Valid values are:
    0—indicates a new device.
    1—indicates a device has been removed.
    2—indicates the search is complete.

Requirements

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

See also

IUPnPDeviceFinder

IUPnPDeviceFinder::StartAsyncFind