IUPnPDescriptionDocument::LoadAsync method (upnp.h)
The LoadAsync method loads a document asynchronously. This method returns control to the caller immediately, and uses the specified callback to notify the caller when the operation is complete.
Syntax
HRESULT LoadAsync(
[in] BSTR bstrUrl,
[in] IUnknown *punkCallback
);
Parameters
[in] bstrUrl
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.
[in] punkCallback
Reference to an IUnknown specifying the callback that the UPnP framework 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. The object referred to by pUnkCallback must support either the IUPnPDescriptionDocumentCallback interface or the IDispatch interface.
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, or one of the following UPnP return values.
| Return code | Description |
|---|---|
|
The XML document does not have a device element It is missing either from the root element or the DeviceList element. |
|
The XML document is missing one of the required elements from the Device element. |
|
The 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. |
|
The XML document is missing one of the required elements from the Icon element. |
|
The XML document does not have a root element at the top level of the document. |
|
The 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. |
|
The XML document is missing one of the required elements from the Service element. |
Remarks
This method should not be called from a user interface thread because it can take a long time for the method to return.
If you invoke this method for the same object immediately after a previous invocation, the first invocation of LoadAsync is aborted. To avoid this, wait for the IUPnPDescriptionDocumentCallback::LoadComplete callback, and then use LoadResult to view the state information.
If the LoadAsync method is called by a script within a Web page, bstrUrl might 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 that 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 interface or the IDispatch interface. The LoadAsync method first queries pUnkCallback for the IUPnPDescriptionDocumentCallback interface. If this interface is not supported, the LoadAsync method then queries pUnkCallback for the IDispatch interface. If the IDispatch interface is not supported, both checks have failed and the LoadAsync method returns E_FAIL.
The callback based on IDispatch for the LoadAsync method works as a script function that takes one parameter. This parameter is the result of the load operation. If the parameter is zero, the load succeeded, and the user can retrieve device objects from the document. If the parameter is non-zero, it describes the error. The value is the same as the error code that the IUPnPDescriptionDocument::Load method returns.
In Visual Basic Scripting Edition (VBScript) development software, the second argument must be GetRef(funcname), where funcname is the name of the callback subroutine.
If this function returns S_OK, IUPnPDescriptionDocumentCallback::LoadComplete is invoked by the UPnP framework.
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 |