Función GetQueuedCompletionStatus (ioapiset.h)

Artículo
05/20/2023

Intenta quitar un paquete de finalización de E/S del puerto de finalización de E/S especificado. Si no hay ningún paquete de finalización en cola, la función espera a que se complete una operación de E/S pendiente asociada al puerto de finalización.

Para desconecte varios paquetes de finalización de E/S a la vez, use la función GetQueuedCompletionStatusEx .

Sintaxis

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

Parámetros

[in] CompletionPort

Identificador del puerto de finalización. Para crear un puerto de finalización, use la función CreateIoCompletionPort .

lpNumberOfBytesTransferred

Puntero a una variable que recibe el número de bytes transferidos en una operación de E/S completada.

[out] lpCompletionKey

Puntero a una variable que recibe el valor de clave de finalización asociado al identificador de archivo cuya operación de E/S se ha completado. Una clave de finalización es una clave por archivo que se especifica en una llamada a CreateIoCompletionPort.

[out] lpOverlapped

Puntero a una variable que recibe la dirección de la estructura SUPERPUESTA que se especificó cuando se inició la operación de E/S completada.

Incluso si ha pasado la función un identificador de archivo asociado a un puerto de finalización y una estructura SUPERPUESTA válida, una aplicación puede impedir la notificación del puerto de finalización. Esto se hace especificando un identificador de evento válido para el miembro hEvent de la estructura SUPERPUESTA y estableciendo su bit de orden bajo. Un identificador de eventos válido cuyo bit de orden bajo se establece impide que la E/S superpuesta entre en cola un paquete de finalización al puerto de finalización.

[in] dwMilliseconds

Número de milisegundos que el autor de la llamada está dispuesto a esperar a que aparezca un paquete de finalización en el puerto de finalización. Si un paquete de finalización no aparece dentro del tiempo especificado, la función agota el tiempo de espera, devuelve FALSE y establece *lpOverlapped en NULL.

Si dwMilliseconds es INFINITE, la función nunca agotará el tiempo de espera. Si dwMilliseconds es cero y no hay ninguna operación de E/S para quitar la cola, la función agotará el tiempo de espera inmediatamente.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: El valor dwMilliseconds incluye el tiempo invertido en estados de bajo consumo. Por ejemplo, el tiempo de espera continúa contando mientras el equipo está dormido.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 y Windows Server 2016: el valor dwMilliseconds no incluye el tiempo invertido en baja potencia Estados. Por ejemplo, el tiempo de espera no continúa contando mientras el equipo está dormido.

Valor devuelto

Devuelve un valor distinto de cero (TRUE) si es correcto o cero (FALSE) de lo contrario.

Para obtener información de error extendida, llame a GetLastError.

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

Comentarios

Esta función asocia un subproceso con el puerto de finalización especificado. Un subproceso se puede asociar como máximo a un puerto de finalización.

Si se produce un error en una llamada a GetQueuedCompletionStatus porque el identificador de puerto de finalización asociado a él está cerrado mientras la llamada está pendiente, la función devuelve FALSE, *lpOverlapped será NULL y GetLastError devolverá ERROR_ABANDONED_WAIT_0.

Windows Server 2003 y Windows XP: Cerrar el identificador del puerto de finalización mientras una llamada está pendiente no dará lugar al comportamiento indicado anteriormente. La función seguirá esperando hasta que se quite una entrada del puerto o hasta que se produzca un tiempo de espera, si se especifica como un valor distinto de INFINITE.

Si la función GetQueuedCompletionStatus se realiza correctamente, desqueuó un paquete de finalización para una operación de E/S correcta desde el puerto de finalización y ha almacenado información en las variables a las que apuntaban los parámetros siguientes: lpNumberOfBytes, lpCompletionKey y lpOverlapped. Tras un error (el valor devuelto es FALSE), esos mismos parámetros pueden contener combinaciones de valores particulares de la siguiente manera:

Si *lpOverlapped es NULL, la función no descontinuó un paquete de finalización desde el puerto de finalización. En este caso, la función no almacena información en las variables a las que apunta el parámetro lpNumberOfBytes y lpCompletionKey , y sus valores son indeterminados.
Si *lpOverlapped no es NULL y la función desquea un paquete de finalización para una operación de E/S con errores desde el puerto de finalización, la función almacena información sobre la operación con errores en las variables a las que apunta lpNumberOfBytes, lpCompletionKey y lpOverlapped. Para obtener información de error extendida, llame a GetLastError.

Para obtener más información sobre la teoría del puerto de finalización de E/S, el uso y las funciones asociadas, consulte Puertos de finalización de E/S.

En Windows 8 y Windows Server 2012, esta función es compatible con las siguientes tecnologías.

Tecnología	Compatible
Protocolo bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Requisitos


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]
Plataforma de destino	Windows
Encabezado	ioapiset.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll