Estructura SUPERPUESTA (minwinbase.h)

Artículo
02/29/2024

Contiene información usada en la entrada y salida (E/S) asincrónicas (o superpuestas).

Sintaxis

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

Miembros

Internal

Código de estado de la solicitud de E/S. Cuando se emite la solicitud, el sistema establece este miembro en STATUS_PENDING para indicar que la operación aún no se ha iniciado. Una vez completada la solicitud, el sistema establece este miembro en el código de estado de la solicitud completada.

El miembro Interno se reservó originalmente para el uso del sistema y su comportamiento puede cambiar.

InternalHigh

Número de bytes transferidos para la solicitud de E/S. El sistema establece este miembro si la solicitud se completa sin errores.

El miembro InternalHigh se reservó originalmente para el uso del sistema y su comportamiento puede cambiar.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Parte de orden bajo de la posición del archivo en la que se va a iniciar la solicitud de E/S, según lo especificado por el usuario.

Este miembro es distinto de cero solo al realizar solicitudes de E/S en un dispositivo que busca que admita el concepto de desplazamiento (también denominado mecanismo de puntero de archivo), como un archivo. De lo contrario, este miembro debe ser cero.

Para obtener más información, vea Comentarios.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Parte de orden superior de la posición del archivo en la que se inicia la solicitud de E/S, según lo especificado por el usuario.

Para obtener más información, vea Comentarios.

DUMMYUNIONNAME.Pointer

Reservado para uso del sistema; no use después de la inicialización en cero.

hEvent

Identificador del evento que se establecerá en un estado señalado por el sistema cuando se haya completado la operación. El usuario debe inicializar este miembro en cero o en un identificador de eventos válido mediante la función CreateEvent antes de pasar esta estructura a las funciones superpuestas. A continuación, este evento se puede usar para sincronizar solicitudes de E/S simultáneas para un dispositivo. Para obtener más información, vea Comentarios.

Las funciones como ReadFile y WriteFile establecen este identificador en el estado no asignado antes de iniciar una operación de E/S. Una vez completada la operación, el identificador se establece en el estado señalado.

Funciones como GetOverlappedResult y las funciones de espera de sincronización restablecen los eventos de restablecimiento automático al estado no asignado. Por lo tanto, debe usar un evento de restablecimiento manual; Si usa un evento de restablecimiento automático, la aplicación puede dejar de responder si espera a que se complete la operación y, a continuación, llame a GetOverlappedResult con el parámetro bWait establecido en TRUE.

Comentarios

Los miembros no usados de esta estructura siempre deben inicializarse en cero antes de que la estructura se use en una llamada de función. De lo contrario, la función puede producir un error y devolver ERROR_INVALID_PARAMETER.

Los miembros Offset y OffsetHigh representan una posición de archivo de 64 bits. Es un desplazamiento de bytes desde el inicio del archivo o del dispositivo similar al archivo, y lo especifica el usuario; el sistema no modificará estos valores. El proceso de llamada debe establecer este miembro antes de pasar la estructura SUPERPUESTA a funciones que usan un desplazamiento, como las funciones ReadFile o WriteFile (y relacionadas).

Puede usar la macro HasOverlappedIoCompleted para comprobar si se ha completado una operación de E/S asincrónica si GetOverlappedResult es demasiado complicado para la aplicación.

Puede usar la función CancelIo para cancelar una operación de E/S asincrónica.

Un error común es reutilizar una estructura SUPERPUESTA antes de que se haya completado la operación asincrónica anterior. Debe usar una estructura independiente para cada solicitud. También debe crear un objeto de evento para cada subproceso que procese los datos. Si almacena los identificadores de eventos en una matriz, puede esperar fácilmente a que todos los eventos se señalen mediante la función WaitForMultipleObjects .

Para obtener información adicional y posibles problemas de uso asincrónico de E/S, vea CreateFile, ReadFile, WriteFile y funciones relacionadas.

Para obtener información general sobre la sincronización y la información conceptual sobre el uso superpuesta , consulte Sincronización y entrada superpuesta y salida y temas relacionados.

Para obtener información general orientada a E/S de archivos de E/S sincrónica y asincrónica, consulte E /S sincrónica y asincrónica.

Ejemplos

Para obtener un ejemplo, vea Servidor de canalización con nombre mediante E/S superpuesta.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Encabezado	minwinbase.h (incluye Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)