Uso dell'API Device Power

Usare gli elementi di programmazione Device Power per gestire le prestazioni dei dispositivi mentre il sistema è in stato di sospensione.

Apertura e chiusura dell'elenco dei dispositivi

L'apertura e la chiusura dell'elenco dei dispositivi sono un processo costoso in termini di tempo cpu. Le funzioni DevicePowerOpen e DevicePowerClose che eseguono questa operazione sono necessarie solo se l'applicazione deve eseguire più volte una query nell'elenco dei dispositivi.

Se viene chiamato DevicePowerOpen, DevicePowerClose deve essere chiamato al termine delle query dell'elenco di dispositivi. DevicePowerEnumDevices e DevicePowerSetDeviceState non chiuderanno l'elenco dei dispositivi se è stato aperto esplicitamente da DevicePowerOpen.

Enumerazione dei dispositivi

La funzione DevicePowerEnumDevices rileva se l'elenco dei dispositivi è aperto e, in caso contrario, lo apre. DevicePowerEnumDevices enumera i dispositivi in base ai criteri di ricerca specificati. Se l'elenco di dispositivi è stato aperto dalla funzione, viene chiuso prima che venga restituita la funzione.

Attivazione e disattivazione di un dispositivo per riattivare il sistema

La funzione DevicePowerSetDeviceState, simile a DevicePowerEnumDevices, rileva se l'elenco di dispositivi è aperto e, in caso contrario, lo apre. DevicePowerSetDeviceState quindi imposta i criteri specificati per il dispositivo specificato. Se l'elenco di dispositivi è stato aperto dalla funzione, viene chiuso prima che venga restituita la funzione.

Codice di esempio

L'esempio seguente illustra l'uso dell'API Device Power.

#define _WIN32_WINNT 0x0600
#include <Windows.h>
#include <PowrProf.h>
#include <stdio.h>
#include <tchar.h>

#pragma comment(lib, "PowrProf.lib")

int __cdecl main()
{
 // Define and initialize our return variables.
 LPWSTR  pRetBuf = NULL;
 ULONG bufSize = MAX_PATH * sizeof(WCHAR);
 ULONG uIndex = 0;
 BOOLEAN bRet = FALSE;

 // Open the device list, querying all devices
 if (!DevicePowerOpen(0)) 
  {
   printf("ERROR: The device database failed to initialize.\n");
   return FALSE;
  }

 // Enumerate the device list, searching for devices that support 
 // waking from either the S1 or S2 sleep state and are currently 
 // present in the system, and not devices that have drivers 
 // installed but are not currently attached to the system, such as 
 // in a laptop docking station.

 pRetBuf = (LPWSTR)LocalAlloc(LPTR, bufSize);

 while (NULL != pRetBuf && 
        0 != (bRet = DevicePowerEnumDevices(uIndex,
           DEVICEPOWER_FILTER_DEVICES_PRESENT,
           PDCAP_WAKE_FROM_S1_SUPPORTED|PDCAP_WAKE_FROM_S2_SUPPORTED,
           (PBYTE)pRetBuf,
           &bufSize)))
  {
   printf("Device name: %S\n", pRetBuf);

   // For the devices we found that have support for waking from 
   // S1 and S2 sleep states, disable them from waking the system.
   bRet = (0 != DevicePowerSetDeviceState((LPCWSTR)pRetBuf, 
                                  DEVICEPOWER_CLEAR_WAKEENABLED, 
                                  NULL));

   if (0 != bRet) 
    {
     printf("Warning: Failed to set device state.\n");
    }
   uIndex++;
  }

 // Close the device list.
 DevicePowerClose();
 if (pRetBuf!= NULL) LocalFree(pRetBuf);
 pRetBuf = NULL;

 return TRUE;
}

In questo esempio l'elenco di dispositivi viene aperto una sola volta e chiuso una sola volta. Se le funzioni DevicePowerOpen e DevicePowerClose non fossero state chiamate, l'elenco dei dispositivi sarebbe stato aperto e chiuso per ogni chiamata a DevicePowerEnumDevices e DevicePowerSetDeviceState. Utilizzando DevicePowerOpen e DevicePowerClose, abbiamo evitato di dover aprire l'elenco dei dispositivi due volte inutilmente.