DeviceIoControl, fonction (ioapiset.h)

Article
08/24/2023

Envoie un code de contrôle directement à un pilote de périphérique spécifié, ce qui entraîne l’exécution de l’opération correspondante par l’appareil correspondant.

Consultez l’exemple Affecter une lettre de lecteur.

Syntaxe

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
);

Paramètres

[in] hDevice

Handle de l’appareil sur lequel l’opération doit être effectuée. L’appareil est généralement un volume, un répertoire, un fichier ou un flux. Pour récupérer un handle d’appareil, utilisez la fonction CreateFile . Pour plus d'informations, consultez la section Notes.

[in] dwIoControlCode

Code de contrôle de l’opération. Cette valeur identifie l’opération spécifique à effectuer et le type d’appareil sur lequel l’effectuer.

Pour obtenir la liste des codes de contrôle, consultez Remarques. La documentation de chaque code de contrôle fournit des détails d’utilisation pour les paramètres lpInBuffer, nInBufferSize, lpOutBuffer et nOutBufferSize .

[in, optional] lpInBuffer

Pointeur vers la mémoire tampon d’entrée qui contient les données requises pour effectuer l’opération. Le format de ces données dépend de la valeur du paramètre dwIoControlCode .

Ce paramètre peut être NULL si dwIoControlCode spécifie une opération qui ne nécessite pas de données d’entrée.

[in] nInBufferSize

Taille, en octets, de la mémoire tampon d’entrée.

[out, optional] lpOutBuffer

Pointeur vers la mémoire tampon de sortie qui doit recevoir les données retournées par l’opération. Le format de ces données dépend de la valeur du paramètre dwIoControlCode .

Ce paramètre peut être NULL si dwIoControlCode spécifie une opération qui ne retourne pas de données.

[in] nOutBufferSize

Taille de la mémoire tampon de sortie en octets.

[out, optional] lpBytesReturned

Pointeur vers une variable qui reçoit la taille des données stockées dans la mémoire tampon de sortie, en octets.

Si la mémoire tampon de sortie est trop petite pour recevoir des données, l’appel échoue, GetLastError retourne ERROR_INSUFFICIENT_BUFFER et lpBytesReturned est égal à zéro.

Si la mémoire tampon de sortie est trop petite pour contenir toutes les données, mais peut contenir certaines entrées, certains pilotes retournent autant de données que d’ajustements. Dans ce cas, l’appel échoue, GetLastError retourne ERROR_MORE_DATA et lpBytesReturned indique la quantité de données reçues. Votre application doit appeler à nouveau DeviceIoControl avec la même opération, en spécifiant un nouveau point de départ.

Si lpOverlapped a la valeur NULL, lpBytesReturned ne peut pas être NULL. Même quand une opération ne retourne aucune donnée de sortie et que lpOutBuffer a la valeur NULL, DeviceIoControl utilise lpBytesReturned. Après une telle opération, la valeur de lpBytesReturned n’a pas de sens.

Si lpOverlapped n’a pas la valeur NULL, lpBytesReturned peut être NULL. Si ce paramètre n’est pas NULL et que l’opération retourne des données, lpBytesReturned n’a pas de sens tant que l’opération superposée n’est pas terminée. Pour récupérer le nombre d’octets retournés, appelez GetOverlappedResult. Si hDevice est associé à un port de réalisation des E/S, vous pouvez récupérer le nombre d’octets retournés en appelant GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Pointeur vers une structure OVERLAPPED.

Si hDevice a été ouvert sans spécifier FILE_FLAG_OVERLAPPED, lpOverlapped est ignoré.

Si hDevice a été ouvert avec l’indicateur FILE_FLAG_OVERLAPPED, l’opération est effectuée en tant qu’opération superposée (asynchrone). Dans ce cas, lpOverlapped doit pointer vers une structure OVERLAPPED valide qui contient le descripteur d’un objet d’événement. Sinon, la fonction échoue de façon imprévisible.

Pour les opérations superposées, DeviceIoControl est immédiatement retourné, et l’objet d’événement est signalé une fois l’opération terminée. Sinon, la fonction n’est pas retournée tant que l’opération n’est pas terminée ou si une erreur se produit.

Valeur retournée

Si l’opération se termine correctement, la valeur de retour est différente de zéro (TRUE).

Si l’opération échoue ou est en attente, la valeur de retour est zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour récupérer un handle sur l’appareil, vous devez appeler la fonction CreateFile avec le nom d’un appareil ou le nom du pilote associé à un appareil. Pour spécifier un nom d’appareil, utilisez le format suivant :

\\.\DeviceName

DeviceIoControl peut accepter un handle pour un appareil spécifique. Par exemple, pour ouvrir un handle sur le lecteur logique A : avec CreateFile, spécifiez \\.\a :. Vous pouvez également utiliser les noms \\.\PhysicalDrive0, \\.\PhysicalDrive1, etc., pour ouvrir des descripteurs aux lecteurs physiques d’un système.

Vous devez spécifier les indicateurs d’accès FILE_SHARE_READ et FILE_SHARE_WRITE lors de l’appel de CreateFile pour ouvrir un handle à un pilote de périphérique. Toutefois, lorsque vous ouvrez une ressource de communication, telle qu’un port série, vous devez spécifier l’accès exclusif. Utilisez les autres paramètres CreateFile comme suit lors de l’ouverture d’un handle d’appareil :

Le paramètre fdwCreate doit spécifier OPEN_EXISTING.
Le paramètre hTemplateFile doit être NULL.
Le paramètre fdwAttrsAndFlags peut spécifier FILE_FLAG_OVERLAPPED pour indiquer que le handle retourné peut être utilisé dans des opérations d’E/S (asynchrones) qui se chevauchent.

Pour obtenir la liste des codes de contrôle pris en charge, consultez les rubriques suivantes :

Exemples

Pour obtenir un exemple qui utilise DeviceIoControl, consultez Appel de DeviceIoControl.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Serveur minimal pris en charge	Windows Server 2003
Plateforme cible	Windows
En-tête	ioapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll