Partager via

IUPnPDescriptionDocument::LoadAsync

  • Article

This method loads a document asynchronously. It returns control to the caller immediately, and uses the specified callback to notify the caller when the operation is complete.

HRESULT LoadAsync(
  BSTR bstrUrl,
  IUnknown* punkCallback
);

Parameters

  • bstrUrl
    [in] Specifies the URL of the document to load. If the URL specified is a relative URL, the server name is prepended to the value of bstrUrl.
  • punkCallback
    [in] Reference to an IUnknown that specifies the callback UPnP uses to notify the caller when the operation is complete. If the load operation did not fail immediately, this callback indicates whether or not the load operation succeeded or failed.

Return Values

  • S_OK
    This method was successful.

Otherwise, the method returns one of the COM error codes defined in WinError.h, or one of the following UPnP return values.

UPnP-specific Return value Description
UPNP_E_DEVICE_ELEMENT_EXPECTED XML document does not have a device element It is missing either from the root element or the DeviceList element.
UPNP_E_DEVICE_NODE_INCOMPLETE XML document is missing one of the required elements from the Device element.
UPNP_E_ICON_ELEMENT_EXPECTED XML document does not have an icon element. It is missing from the IconList element, or the DeviceList element does not contain an IconList element.
UPNP_E_ICON_NODE_INCOMPLETE XML document is missing one of the required elements from the Icon element.
UPNP_E_ROOT_ELEMENT_EXPECTED XML document does not have a root element at the top level of the document.
UPNP_E_SERVICE_ELEMENT_EXPECTED XML document does not have a service element. It is missing from the ServiceList element, or the DeviceList element does not contain a ServiceList element.
UPNP_E_SERVICE_NODE_INCOMPLETE XML document is missing one of the required elements from the Service element.

Remarks

If you invoke this method for the same object immediately after a previous invocation, the first invocation of LoadAsync is aborted and the second invocation fails. To avoid this problem, wait for the IUPnPDescriptionDocumentCallback::LoadComplete callback, and use IUPnPDescriptionDocument::LoadResult to view the state information.

If the IUPnPDescriptionDocument::LoadAsync method is called by a script within a Web page, bstrUrl may be a relative URL. The address of the current web page is used as the base URL.

If this method is called from a Web page, the URL the caller specifies must refer to the same server from which the Web page was loaded.

The object referred to by pUnkCallback must either support the IUPnPDescriptionDocumentCallback:IDispatch interface, or the IDispatch interface. The IUPnPDescriptionDocument::LoadAsync method first queries pUnkCallback for the IUPnPDescriptionDocumentCallback interface. If this interface is not supported, the IUPnPDescriptionDocument::LoadAsync method then queries pUnkCallback for the IDispatch interface. If the IDispatch interface is not supported, both checks have failed and The IUPnPDescriptionDocument::LoadAsync method returns E_FAIL.

The callback based on IDispatch for the IUPnPDescriptionDocument::LoadAsync method works as a script function that takes one parameter. This parameter is the result of the load operation. If the parameter is 0, the load succeeded, and the user can retrieve device objects from the document. If the parameter is nonzero, it describes the error. The value is the same as the error code that the IUPnPDescriptionDocument::Load method returns.

If this function returns S_OK, IUPnPDescriptionDocumentCallback::LoadComplete is invoked by UPnP.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Upnp.h.
Link Library: Uuid.lib.

See Also

IUPnPDescriptionDocument:IDispatch | IUPnPDescriptionDocument::Load

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.