IUPnPDescriptionDocument::LoadAsync
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.