Función DeviceIoControl (ioapiset.h)

Artículo
02/26/2024

Envía un código de control directamente a un controlador de dispositivo especificado, lo que hace que el dispositivo correspondiente realice la operación correspondiente.

Consulte el ejemplo Asignar letra de unidad.

Sintaxis

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

Parámetros

[in] hDevice

Identificador del dispositivo en el que se va a realizar la operación. Normalmente, el dispositivo es un volumen, un directorio, un archivo o una secuencia. Para recuperar un identificador de dispositivo, use la función CreateFile . Para obtener más información, vea la sección Comentarios.

[in] dwIoControlCode

Código de control de la operación. Este valor identifica la operación específica que se va a realizar y el tipo de dispositivo en el que se va a realizar.

Para obtener una lista de los códigos de control, vea Comentarios. La documentación de cada código de control proporciona detalles de uso para los parámetros lpInBuffer, nInBufferSize, lpOutBuffer y nOutBufferSize .

[in, optional] lpInBuffer

Puntero al búfer de entrada que contiene los datos necesarios para realizar la operación. El formato de estos datos depende del valor del parámetro dwIoControlCode .

Este parámetro puede ser NULL si dwIoControlCode especifica una operación que no requiere datos de entrada.

[in] nInBufferSize

Tamaño del búfer de entrada, en bytes.

[out, optional] lpOutBuffer

Puntero al búfer de salida que va a recibir los datos devueltos por la operación. El formato de estos datos depende del valor del parámetro dwIoControlCode .

Este parámetro puede ser NULL si dwIoControlCode especifica una operación que no devuelve datos.

[in] nOutBufferSize

Tamaño del búfer de salida, en bytes.

[out, optional] lpBytesReturned

Puntero a una variable que recibe el tamaño de los datos almacenados en el búfer de salida, en bytes.

Si el búfer de salida es demasiado pequeño para recibir datos, se produce un error en la llamada, GetLastError devuelve ERROR_INSUFFICIENT_BUFFER y lpBytesReturned es cero.

Si el búfer de salida es demasiado pequeño para contener todos los datos, pero puede contener algunas entradas, algunos controladores devolverán tantos datos como se adapten. En este caso, se produce un error en la llamada, GetLastError devuelve ERROR_MORE_DATA y lpBytesReturned indica la cantidad de datos recibidos. La aplicación debe llamar a DeviceIoControl de nuevo con la misma operación, especificando un nuevo punto de partida.

Si lpOverlapped es NULL, lpBytesReturned no puede ser NULL. Incluso cuando una operación no devuelve datos de salida y lpOutBuffer es NULL, DeviceIoControl usa lpBytesReturned. Después de esta operación, el valor de lpBytesReturned no tiene sentido.

Si lpOverlapped no es NULL, lpBytesReturned puede ser NULL. Si este parámetro no es NULL y la operación devuelve datos, lpBytesReturned no tiene sentido hasta que se haya completado la operación superpuesta. Para recuperar el número de bytes devueltos, llame a GetOverlappedResult. Si hDevice está asociado a un puerto de finalización de E/S, puede recuperar el número de bytes devueltos llamando a GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Puntero a una estructura OVERLAPPED.

Si hDevice se abrió sin especificar FILE_FLAG_OVERLAPPED, se omite lpOverlapped.

Si hDevice se abrió con la marca FILE_FLAG_OVERLAPPED, la operación se realiza como una operación superpuesta (asincrónica). En este caso, lpOverlapped debe apuntar a una estructura SUPERPUESTA válida que contenga un identificador para un objeto de evento. De lo contrario, se producirá un error en la función de formas impredecibles.

En el caso de las operaciones superpuestas, se devuelve inmediatamente DeviceIoControl y se señala el objeto de evento cuando se ha completado la operación. De lo contrario, la función no se devuelve hasta que se haya completado la operación o hasta que se produzca un error.

Valor devuelto

Si la operación se completa correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la operación o está pendiente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Para recuperar un identificador del dispositivo, debe llamar a la función CreateFile con el nombre de un dispositivo o el nombre del controlador asociado a un dispositivo. Para especificar un nombre de dispositivo, use el siguiente formato:

\\.\DeviceName

DeviceIoControl puede aceptar un identificador para un dispositivo específico. Por ejemplo, para abrir un identificador en la unidad lógica A: con CreateFile, especifique \\.\a:. Como alternativa, puede usar los nombres \\.\PhysicalDrive0, \\.\PhysicalDrive1, etc., para abrir identificadores en las unidades físicas de un sistema.

Debe especificar las marcas de acceso FILE_SHARE_READ y FILE_SHARE_WRITE al llamar a CreateFile para abrir un identificador en un controlador de dispositivo. Sin embargo, al abrir un recurso de comunicaciones, como un puerto serie, debe especificar el acceso exclusivo. Use los demás parámetros CreateFile como se indica a continuación al abrir un identificador de dispositivo:

El parámetro fdwCreate debe especificar OPEN_EXISTING.
El parámetro hTemplateFile debe ser NULL.
El parámetro fdwAttrsAndFlags puede especificar FILE_FLAG_OVERLAPPED para indicar que el identificador devuelto se puede usar en operaciones de E/S superpuestas (asincrónicas).

Para obtener listas de códigos de control admitidos, consulte los temas siguientes:

Ejemplos

Para obtener un ejemplo que usa DeviceIoControl, consulte Llamada a DeviceIoControl.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP
Servidor mínimo compatible	Windows Server 2003
Plataforma de destino	Windows
Encabezado	ioapiset.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll