Descrizione dei dispositivi

Esistono due modi per ottenere oggetti dispositivo:

• Uso dell'interfaccia IUPnPDescriptionDocument . L'interfaccia IUPnPDescriptionDocument è l'unica interfaccia sicura per lo scripting.
• Uso dell'interfaccia IUPnPDeviceFinder per ottenere un'interfaccia IUPnPDevices .

Entrambi i metodi restituiscono raccolte Dispositivi. Le applicazioni usano quindi i metodi Device per recuperare le proprietà sui dispositivi.

Le applicazioni sono in grado di recuperare i tipi di informazioni seguenti:

• Informazioni sulla gerarchia dei dispositivi, inclusi i dispositivi radice, i dispositivi padre e i dispositivi figlio.
• Proprietà del dispositivo, tra cui UDN, identificatori di risorse uniformi (URI) e nomi leggibili dall'utente.
• Informazioni sul produttore, inclusi i nomi e le pagine Web correlate.
• Informazioni sul modello, tra cui il nome, il numero, l'UPC, i numeri di serie e le descrizioni dei dispositivi.
• Visualizzare informazioni, inclusi l'URL per controllare il dispositivo e gli URL da cui vengono scaricate le icone.
• Servizi forniti da un particolare dispositivo.

Le applicazioni ottengono anche l'URL del documento di descrizione del dispositivo usando l'interfaccia IUPnPDeviceDocumentAccess . L'applicazione carica quindi il documento di descrizione e funziona con le proprietà del dispositivo e del servizio non esposte dall'interfaccia IUPnPDevice . Questa interfaccia non può essere usata nello scripting, perché non è l'interfaccia predefinita.

Esempio di Visual Basic

Il codice di esempio seguente mostra l'utilizzo di 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

Esempio C++

Il codice di esempio seguente mostra l'utilizzo di 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;
}