Función CreateIoCompletionPort (ioapiset.h)
Crea un puerto de finalización de entrada/salida (E/S) y lo asocia a un identificador de archivos especificado, o crea un puerto de finalización de E/S que aún no está asociado a un identificador de archivos, lo que permite la asociación en un momento posterior.
La asociación de la instancia de un identificador de archivo abierto con un puerto de finalización de E/S permite que un proceso reciba una notificación de la finalización de operaciones de E/S asincrónicas que impliquen ese identificador de archivo.
El término identificador de archivo que se usa aquí hace referencia a una abstracción del sistema que representa un punto de conexión de E/S superpuesto, no solo un archivo en el disco. Cualquier objeto del sistema que admita E/S superpuesta (como puntos de conexión de red, sockets TCP, canalizaciones con nombre y ranuras de correo) se puede usar como identificadores de archivo. Para obtener más información, consulte la sección Comentarios.
Sintaxis
HANDLE CreateIoCompletionPort(
[in] HANDLE FileHandle,
[in, optional] HANDLE ExistingCompletionPort,
[in] ULONG_PTR CompletionKey,
[in] DWORD NumberOfConcurrentThreads
);
Parámetros
[in] FileHandle
Identificador de archivos abierto o INVALID_HANDLE_VALUE.
El identificador debe ser para un objeto que admita E/S superpuesta.
Si se proporciona un identificador, debe haberse abierto para la finalización de E/S superpuesta. Por ejemplo, debe especificar la marca FILE_FLAG_OVERLAPPED al usar la función CreateFile para obtener el identificador.
Si se especifica INVALID_HANDLE_VALUE, la función crea un puerto de finalización de E/S sin asociarlo a un identificador de archivos. En este caso, el parámetro ExistingCompletionPort debe ser NULL y se omite el parámetro CompletionKey.
[in, optional] ExistingCompletionPort
Identificador de un puerto de finalización de E/S existente o NULL.
Si este parámetro especifica un puerto de finalización de E/S existente, la función la asocia al identificador especificado por el parámetro FileHandle. La función devuelve el identificador del puerto de finalización de E/S existente si es correcto; no crea un puerto de finalización de E/S.
Si este parámetro es NULL, la función crea un nuevo puerto de finalización de E/S y, si el parámetro FileHandle es válido, lo asocia al nuevo puerto de finalización de E/S. De lo contrario, no se produce ninguna asociación de identificadores de archivo. La función devuelve el identificador al nuevo puerto de finalización de E/S si se realiza correctamente.
[in] CompletionKey
Clave de finalización por identificador definida por el usuario que se incluye en los paquetes de finalización de E/S para el identificador de archivos especificado. Para obtener más información, vea la sección Comentarios.
[in] NumberOfConcurrentThreads
Número máximo de subprocesos que el sistema operativo puede permitir para procesar simultáneamente paquetes de finalización de E/S para el puerto de finalización de E/S. Este parámetro se omite si el parámetro ExistingCompletionPort no es NULL.
Si este parámetro es cero, el sistema permite tantos subprocesos en ejecución simultáneos como procesadores haya en el sistema.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es el identificador de un puerto de finalización de E/S:
- Si el parámetro ExistingCompletionPort fue NULL, el valor devuelto es un nuevo identificador.
- Si el parámetro ExistingCompletionPort era un identificador de puerto de finalización de E/S válido, el valor devuelto es ese mismo identificador.
- Si el parámetro FileHandle era un identificador válido, ese identificador de archivo ahora está asociado al puerto de finalización de E/S devuelto.
Comentarios
Se puede indicar al sistema de E/S que envíe paquetes de notificación de finalización de E/S a puertos de finalización de E/S, donde se ponen en cola. La función CreateIoCompletionPort proporciona esta funcionalidad.
Un puerto de finalización de E/S y el identificador están asociados al proceso que lo creó y no se pueden compartir entre procesos. Sin embargo, un único identificador se puede compartir entre subprocesos en el mismo proceso.
CreateIoCompletionPort se puede usar en tres modos distintos:
- Cree solo un puerto de finalización de E/S sin asociarlo a un identificador de archivo.
- Asocie un puerto de finalización de E/S existente con un identificador de archivo.
- Realice la creación y la asociación en una sola llamada.
El identificador pasado en el parámetro FileHandle puede ser cualquier identificador que admita E/S superpuesta. Normalmente, se trata de un identificador abierto por la función CreateFile mediante la marca FILE_FLAG_OVERLAPPED (por ejemplo, archivos, ranuras de correo y canalizaciones). Los objetos creados por otras funciones, como socket también se pueden asociar a un puerto de finalización de E/S. Para obtener un ejemplo de uso de sockets, consulte AcceptEx. Un identificador solo se puede asociar a un puerto de finalización de E/S y, una vez realizada la asociación, el identificador permanece asociado a ese puerto de finalización de E/S hasta que se cierra.
Para obtener más información sobre la teoría, el uso y las funciones asociadas de los puertos de finalización de E/S, consulte Puertos de finalización de E/S.
Se pueden asociar varios identificadores de archivo a un único puerto de finalización de E/S llamando a CreateIoCompletionPort varias veces con el mismo identificador de puerto de finalización de E/S en el parámetro ExistingCompletionPort y un identificador de archivo diferente en el parámetro FileHandle cada vez.
Use el parámetro CompletionKey para ayudar a la aplicación a realizar el seguimiento de las operaciones de E/S que se han completado. CreateIoCompletionPort no usa este valor para el control funcional; más bien, se adjunta al identificador de archivo especificado en el parámetro FileHandle en el momento de la asociación con un puerto de finalización de E/S. Esta clave de finalización debe ser única para cada identificador de archivos y acompaña al identificador de archivos a lo largo del proceso de puesta en cola de finalización interna. Se devuelve en la llamada de función GetQueuedCompletionStatus cuando llega un paquete de finalización. El parámetro CompletionKey también lo usa la función PostQueuedCompletionStatus para poner en cola sus propios paquetes de finalización con propósito especial.
Después de asociar una instancia de un identificador abierto a un puerto de finalización de E/S, no se puede usar en la función ReadFileEx o WriteFileEx porque estas funciones tienen sus propios mecanismos de E/S asincrónicos.
Es mejor no compartir un identificador de archivos asociado a un puerto de finalización de E/S mediante la herencia de identificadores o una llamada a la función DuplicateHandle. Las operaciones realizadas con estos identificadores duplicados generan notificaciones de finalización. Se recomienda tener en cuenta detenidamente.
El identificador de puerto de finalización de E/S y todos los identificadores de archivos asociados a ese puerto de finalización de E/S específico se conocen como referencias al puerto de finalización de E/S. El puerto de finalización de E/S se libera cuando no hay más referencias a él. Por lo tanto, todos estos identificadores deben cerrarse correctamente para liberar el puerto de finalización de E/S y sus recursos del sistema asociados. Una vez que se cumplan estas condiciones, cierre el identificador de puerto de finalización de E/S mediante una llamada a la función CloseHandle.
En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.
| 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 |
Vea también
Funciones de administración de archivos
Funciones
Puertos de finalización de E/S
Temas de introducción