Beschreiben von Geräten

Es gibt zwei Möglichkeiten zum Abrufen von Geräteobjekten:

• Verwenden der IUPnPDescriptionDocument-Schnittstelle . Die IUPnPDescriptionDocument-Schnittstelle ist die einzige Schnittstelle, die für skripterstellungssicher ist.
• Verwenden der IUPnPDeviceFinder-Schnittstelle zum Abrufen einer IUPnPDevices-Schnittstelle .

Beide Methoden geben Gerätesammlungen zurück. Anwendungen verwenden dann die Device-Methoden, um Eigenschaften zu Geräten abzurufen.

Anwendungen können die folgenden Arten von Informationen abrufen:

• Informationen zur Gerätehierarchie, einschließlich Stammgeräten, übergeordneten Geräten und untergeordneten Geräten.
• Geräteeigenschaften, einschließlich UDNs, URIs (Uniform Resource Identifiers) und benutzerlesbaren Namen.
• Herstellerinformationen, einschließlich Namen und zugehörige Webseiten.
• Modellinformationen, einschließlich Name, Nummer, UPC, Seriennummern und Gerätebeschreibungen.
• Zeigt Informationen an, einschließlich der URL zum Steuern des Geräts und urLs, von denen Symbole heruntergeladen werden.
• Dienste, die von einem bestimmten Gerät bereitgestellt werden.

Anwendungen rufen auch die URL des Gerätebeschreibungsdokuments mithilfe der IUPnPDeviceDocumentAccess-Schnittstelle ab. Die Anwendung lädt dann das Beschreibungsdokument und arbeitet mit Geräte- und Diensteigenschaften, die nicht von der IUPnPDevice-Schnittstelle verfügbar gemacht werden. Diese Schnittstelle kann nicht für die Skripterstellung verwendet werden, da sie nicht die Standardschnittstelle ist.

Visual Basic-Beispiel

Der folgende Beispielcode zeigt die Verwendung von IUPnPDeviceDocumentAccess::GetDocumentURL.

Sub GetDocumentURL()
Dim pDescDoc As IUPnPDeviceDocumentAccess
Dim strDescDocURL As String

'currentDevice is UPnPDevice object containing the current UPnP Device 
'We are trying to get IUPnPDeviceDocumentAccess interface in the UPnP Device object
Set pDescDoc = currentDevice

If Not (pDescDoc is Nothing) Then
  'Description Document URL is got from device
  strDescDocURL = pDescDoc.GetDocumentURL 
End If

C++-Beispiel

Der folgende Beispielcode zeigt die Verwendung von IUPnPDeviceDocumentAccess::GetDocumentURL.

#include <windows.h>
#include <upnp.h>
#include <stdio.h>

#pragma comment(lib, "ole32.lib")
#pragma comment(lib, "oleaut32.lib")

int GetDeviceDocumentUrl () 
{
  HRESULT hr = S_OK;
  // List of interfaces needed
  IUPnPDeviceFinder *pDevFinder=NULL;
  IUPnPDevice *pDevice =NULL;
  IUPnPDeviceDocumentAccess* pDeviceDocument=NULL;
  BSTR bstrDeviceUDN =NULL;
  BSTR bstrDeviceDocumentURL = NULL; 

  bstrDeviceUDN = SysAllocString(L"uuid:234324234324");
  if(bstrDeviceUDN == NULL){
    printf("ERROR: Could not allocate memory\n");
    return -1;
  }  

  //CoInitialize the program so that we can create COM objects
  CoInitializeEx(NULL, COINIT_MULTITHREADED);

  //now try to instantiate the DeviceFinder object
  hr = CoCreateInstance(  CLSID_UPnPDeviceFinder, 
              NULL,
              CLSCTX_INPROC_SERVER,
              IID_IUPnPDeviceFinder,
              (LPVOID *) &pDevFinder); 

  if(!SUCCEEDED(hr)){
    printf("\nERROR: CoCreateInstance on IUPnPDeviceFinder returned HRESULT %x",hr);
    goto cleanup;
  }

  printf("\nGot a pointer to the IUPnPDeviceFinder Interface");

  printf("\n Finding the device of given UDN\n");
  hr =pDevFinder->FindByUDN(bstrDeviceUDN, &pDevice);
  if(hr!=S_OK)
  {
    printf("\nERROR: FindByUDN for %S returned HRESULT %x", bstrDeviceUDN, hr);
    goto cleanup;
  }

  printf("\n\tFindByUDN for device of UDN %S succeeded", bstrDeviceUDN);
  //Now query pDevice for IUPnPDeviceDocumentAccess
  hr = pDevice->QueryInterface(IID_IUPnPDeviceDocumentAccess, (VOID **)&pDeviceDocument);
  if(SUCCEEDED(hr)){
    // We have got a pointer to the IUPnPDeviceDocumentAccess interface.
    // GetDocumentURL is available only in Windows XP. 
    hr = pDeviceDocument->GetDocumentURL(&bstrDeviceDocumentURL);
    if(SUCCEEDED(hr))
      printf("\nThe Device Document URL is %S \n", bstrDeviceDocumentURL);
  }
    
cleanup:
  //release references to all interfaces 
  if(pDevFinder)
    pDevFinder->Release();
  if(pDevice)
    pDevice->Release();
  if(pDeviceDocument)
    pDeviceDocument->Release();
  
  // Free the bstr strings
  if(bstrDeviceDocumentURL)
    SysFreeString(bstrDeviceDocumentURL);
  if(bstrDeviceUDN)
    SysFreeString(bstrDeviceUDN);
  CoUninitialize();
  return 0;
}