Funzione DeviceIoControl (ioapiset.h)

Articolo
08/24/2023

Invia un codice di controllo direttamente a un driver di dispositivo specificato, causando l'esecuzione dell'operazione corrispondente da parte del dispositivo corrispondente.

Vedere l'esempio Assegna lettera di unità.

Sintassi

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parametri

[in] hDevice

Handle per il dispositivo in cui eseguire l'operazione. Il dispositivo è in genere un volume, una directory, un file o un flusso. Per recuperare un handle del dispositivo, usare la funzione CreateFile . Per altre informazioni, vedere la sezione Osservazioni.

[in] dwIoControlCode

Codice di controllo per l'operazione. Questo valore identifica l'operazione specifica da eseguire e il tipo di dispositivo su cui eseguirlo.

Per un elenco dei codici di controllo, vedere Osservazioni. La documentazione per ogni codice di controllo fornisce i dettagli sull'utilizzo per i parametri lpInBuffer, nInBufferSize, lpOutBuffer e nOutBufferSize.

[in, optional] lpInBuffer

Puntatore al buffer di input che contiene i dati necessari per eseguire l'operazione. Il formato di questi dati dipende dal valore del parametro dwIoControlCode .

Questo parametro può essere NULL se dwIoControlCode specifica un'operazione che non richiede dati di input.

[in] nInBufferSize

Dimensioni del buffer di input, in byte.

[out, optional] lpOutBuffer

Puntatore al buffer di output che deve ricevere i dati restituiti dall'operazione. Il formato di questi dati dipende dal valore del parametro dwIoControlCode .

Questo parametro può essere NULL se dwIoControlCode specifica un'operazione che non restituisce i dati.

[in] nOutBufferSize

Dimensioni in byte del buffer di output.

[out, optional] lpBytesReturned

Puntatore a una variabile che riceve le dimensioni dei dati archiviati nel buffer di output, in byte.

Se il buffer di output è troppo piccolo per ricevere i dati, la chiamata ha esito negativo, GetLastError restituisce ERROR_INSUFFICIENT_BUFFER e lpBytesReturned è zero.

Se il buffer di output è troppo piccolo per contenere tutti i dati, ma può contenere alcune voci, alcuni driver restituiranno quanti dati si adattano. In questo caso, la chiamata ha esito negativo, GetLastError restituisce ERROR_MORE_DATA e lpBytesReturned indica la quantità di dati ricevuti. L'applicazione deve chiamare di nuovo DeviceIoControl con la stessa operazione, specificando un nuovo punto di partenza.

Se lpOverlapped è NULL, lpBytesReturned non può essere NULL. Anche quando un'operazione non restituisce dati di output e lpOutBuffer è NULL, DeviceIoControl usa lpBytesReturned. Dopo un'operazione di questo tipo, il valore di lpBytesReturned è senza significato.

Se lpOverlapped non è NULL, lpBytesReturned può essere NULL. Se questo parametro non è NULL e l'operazione restituisce dati, lpBytesReturned è senza significato fino al completamento dell'operazione sovrapposta. Per recuperare il numero di byte restituiti, chiamare GetOverlappedResult. Se hDevice è associato a una porta di completamento di I/O, è possibile recuperare il numero di byte restituiti chiamando GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Puntatore a una struttura OVERLAPPED .

Se hDevice è stato aperto senza specificare FILE_FLAG_OVERLAPPED, lpOverlapped viene ignorato .

Se hDevice è stato aperto con il flag FILE_FLAG_OVERLAPPED , l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, lpOverlapped deve puntare a una struttura OVERLAPPED valida che contiene un handle a un oggetto evento. In caso contrario, la funzione non riesce in modi imprevedibili.

Per le operazioni sovrapposte, DeviceIoControl restituisce immediatamente e l'oggetto evento viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.

Valore restituito

Se l'operazione viene completata correttamente, il valore restituito è diverso da zero (TRUE).

Se l'operazione ha esito negativo o è in sospeso, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Per recuperare un handle nel dispositivo, è necessario chiamare la funzione CreateFile con il nome di un dispositivo o il nome del driver associato a un dispositivo. Per specificare un nome del dispositivo, usare il formato seguente:

\\.\DeviceName

DeviceIoControl può accettare un handle in un dispositivo specifico. Ad esempio, per aprire un handle all'unità logica A: con CreateFile, specificare \\.\a:. In alternativa, è possibile usare i nomi \\.\PhysicalDrive0, \\.\PhysicalDrive1 e così via, per aprire handle alle unità fisiche in un sistema.

È necessario specificare i flag di accesso FILE_SHARE_READ e FILE_SHARE_WRITE quando si chiama CreateFile per aprire un handle a un driver di dispositivo. Tuttavia, quando si apre una risorsa di comunicazione, ad esempio una porta seriale, è necessario specificare l'accesso esclusivo. Usare gli altri parametri CreateFile come indicato di seguito quando si apre un handle di dispositivo:

Il parametro fdwCreate deve specificare OPEN_EXISTING.
Il parametro hTemplateFile deve essere NULL.
Il parametro fdwAttrsAndFlags può specificare FILE_FLAG_OVERLAPPED per indicare che l'handle restituito può essere usato nelle operazioni di I/O sovrapposte (asincrone).

Per gli elenchi di codici di controllo supportati, vedere gli argomenti seguenti:

Esempio

Per un esempio che usa DeviceIoControl, vedere Chiamata di DeviceIoControl.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP
Server minimo supportato	Windows Server 2003
Piattaforma di destinazione	Windows
Intestazione	ioapiset.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll