Función TransmitFile (mswsock.h)

Artículo
03/15/2023

La función TransmitFile transmite datos de archivo a través de un controlador de socket conectado. Esta función usa el administrador de caché del sistema operativo para recuperar los datos de archivo y proporciona transferencia de datos de archivos de alto rendimiento a través de sockets.

Nota Esta función es una extensión específica de Microsoft para la especificación de Windows Sockets.

Sintaxis

BOOL TransmitFile(
  SOCKET                  hSocket,
  HANDLE                  hFile,
  DWORD                   nNumberOfBytesToWrite,
  DWORD                   nNumberOfBytesPerSend,
  LPOVERLAPPED            lpOverlapped,
  LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
  DWORD                   dwReserved
);

Parámetros

hSocket

Identificador de un socket conectado. La función TransmitFile transmitirá los datos del archivo a través de este socket. El socket especificado por el parámetro hSocket debe ser un socket orientado a la conexión de tipo SOCK_STREAM, SOCK_SEQPACKET o SOCK_RDM.

hFile

Identificador del archivo abierto que transmite la función TransmitFile . Puesto que el sistema operativo lee los datos del archivo secuencialmente, puede mejorar el rendimiento del almacenamiento en caché abriendo el identificador con FILE_FLAG_SEQUENTIAL_SCAN.

El parámetro hFile es opcional. Si el parámetro hFile es NULL, solo se transmiten los datos del encabezado o del búfer de cola. Cualquier acción adicional, como la desconexión o reutilización del socket, se realiza según lo especificado por el parámetro dwFlags .

nNumberOfBytesToWrite

Número de bytes del archivo que se va a transmitir. La función TransmitFile se completa cuando se ha enviado el número especificado de bytes, o cuando se produce un error, lo que ocurra primero.

Establezca este parámetro en cero para transmitir todo el archivo.

nNumberOfBytesPerSend

Tamaño, en bytes, de cada bloque de datos enviados en cada operación de envío. El nivel de sockets de Windows usa este parámetro para determinar el tamaño del bloque para las operaciones de envío. Para seleccionar el tamaño de envío predeterminado, establezca este parámetro en cero.

El parámetro nNumberOfBytesPerSend es útil para los protocolos que tienen limitaciones en el tamaño de las solicitudes de envío individuales.

lpOverlapped

Puntero a una estructura OVERLAPPED. Si el identificador de socket se ha abierto como superpuesto, especifique este parámetro para lograr una operación de E/S superpuesta (asincrónica). De forma predeterminada, los identificadores de socket se abren como superpuestos.

Puede usar el parámetro lpOverlapped para especificar un desplazamiento de 64 bits dentro del archivo en el que iniciar la transferencia de datos de archivo estableciendo el miembro Offset y OffsetHigh de la estructura SUPERPUESTA . Si lpOverlapped es un puntero NULL , la transmisión de datos siempre comienza en el desplazamiento de bytes actual en el archivo.

Cuando lpOverlapped no es NULL, es posible que la E/S superpuesta no finalice antes de que TransmitFile devuelva. En ese caso, la función TransmitFile devuelve FALSE y WSAGetLastError devuelve ERROR_IO_PENDING o WSA_IO_PENDING. Esto permite al autor de la llamada continuar procesando mientras se completa la operación de transmisión de archivos. Windows establecerá el evento especificado por el miembro hEvent de la estructura SUPERPUESTA , o el socket especificado por hSocket, en el estado señalado tras la finalización de la solicitud de transmisión de datos.

lpTransmitBuffers

Puntero a una estructura de datos TRANSMIT_FILE_BUFFERS que contiene punteros a datos que se van a enviar antes y después de enviar los datos del archivo. Este parámetro debe establecerse en un puntero NULL si desea transmitir solo los datos del archivo.

dwReserved

Conjunto de marcas usadas para modificar el comportamiento de la llamada de función TransmitFile . El parámetro dwFlags puede contener una combinación de las siguientes opciones definidas en el archivo de encabezado Mswsock.h :

Marca	Significado
TF_DISCONNECT	Inicia una desconexión de nivel de transporte después de que todos los datos de archivos se han colocado en la cola para la transmisión.
TF_REUSE_SOCKET	Prepare el identificador de socket que se va a reutilizar. Esta marca solo es válida si también se especifica TF_DISCONNECT. Cuando se completa la solicitud TransmitFile , el identificador de socket se puede pasar a la llamada de función usada anteriormente para establecer la conexión, como AcceptEx o ConnectEx. Dicha reutilización es mutuamente excluyente; Por ejemplo, si se llamó a la función AcceptEx para el socket, la reutilización solo se permite para las llamadas posteriores a la función AcceptEx y no se permite para una llamada posterior a ConnectEx. Nota La transmisión del archivo de nivel de socket está sujeta al comportamiento del transporte subyacente. Por ejemplo, un socket TCP puede estar sujeto al estado tcp TIME_WAIT, lo que provoca que se retrase la llamada a TransmitFile .
TF_USE_DEFAULT_WORKER	Dirige al proveedor de servicios de Windows Sockets para que use el subproceso predeterminado del sistema para procesar solicitudes de TransmitFile largas. El subproceso predeterminado del sistema se puede ajustar mediante el siguiente parámetro del Registro como un REG_DWORD: HKEY_LOCAL_MACHINE\Currentcontrolset\Servicios\AFD\Parámetros\TransmitWorker
TF_USE_SYSTEM_THREAD	Dirige al proveedor de servicios Windows Sockets para que use subprocesos del sistema para procesar solicitudes de TransmitFile largas.
TF_USE_KERNEL_APC	Dirige al controlador para que use llamadas a procedimientos asincrónicos del kernel (APCs) en lugar de subprocesos de trabajo para procesar solicitudes de TransmitFile largas. Las solicitudes Long TransmitFile se definen como solicitudes que requieren más de una sola lectura del archivo o una memoria caché; Por lo tanto, la solicitud depende del tamaño del archivo y de la longitud especificada del paquete de envío. El uso de TF_USE_KERNEL_APC puede ofrecer importantes ventajas de rendimiento. Sin embargo, es posible (aunque improbable), que el subproceso en el que se inicia transmitFile de contexto se está usando para cálculos pesados; Esta situación puede impedir que se inicien las API. Tenga en cuenta que el controlador del modo kernel winsock usa LAS API de kernel normales, que se inician cada vez que un subproceso está en un estado de espera, que difiere de las API en modo de usuario, que se inician cada vez que un subproceso está en un estado de espera alertable iniciado en modo de usuario).
TF_WRITE_BEHIND	Complete la solicitud TransmitFile inmediatamente, sin estar pendiente. Si se especifica esta marca y TransmitFile se realiza correctamente, el sistema ha aceptado los datos, pero no necesariamente confirmados por el extremo remoto. No use esta configuración con las marcas TF_DISCONNECT y TF_REUSE_SOCKET. Nota Si el archivo que se envía no está en la memoria caché del sistema de archivos, los lápiz de solicitud.

Valor devuelto

Si la función TransmitFile se realiza correctamente, el valor devuelto es TRUE. De lo contrario, el valor devuelto es FALSE. Para obtener información de error extendida, llame a WSAGetLastError. Un código de error de WSA_IO_PENDING o ERROR_IO_PENDING indica que la operación superpuesta se ha iniciado correctamente y que la finalización se indicará más adelante. Cualquier otro código de error indica que la operación superpuesta no se inició correctamente y no se producirá ninguna indicación de finalización. Las aplicaciones deben controlar ERROR_IO_PENDING o WSA_IO_PENDING en este caso.

Código devuelto	Descripción
WSAECONNABORTED	El software del equipo host anuló una conexión establecida. Este error se devuelve si el circuito virtual finalizó debido a un tiempo de espera u otro error.
WSAECONNRESET	El host remoto forzó el cierre de la conexión existente. Este error se devuelve para un socket de flujo cuando el lado remoto restablece el circuito virtual. La aplicación debería cerrar el socket porque ya no se puede usar.
WSAEFAULT	El sistema ha detectado una dirección de puntero no válida al intentar usar un argumento de puntero en una llamada. Este error se devuelve si el parámetro lpTransmitBuffers o lpOverlapped no está totalmente incluido en una parte válida del espacio de direcciones del usuario.
WSAEINVAL	Se ha proporcionado un argumento no válido. Este error se devuelve si el parámetro hSocket especificó un socket de tipo SOCK_DGRAM o SOCK_RAW. Este error se devuelve si el parámetro dwFlags tiene establecida la marca TF_REUSE_SOCKET , pero no se estableció la marca TF_DISCONNECT . Este error también se devuelve si el desplazamiento especificado en la estructura SUPERPUESTA a la que apunta el lpOverlapped no está dentro del archivo. Este error también se devuelve si el parámetro nNumberOfBytesToWrite se establece en un valor mayor que 2.147.483.646, el valor máximo de un entero de 32 bits menos 1.
WSAENETDOWN	Una operación de socket encontró una red inactiva. Este error se devuelve si se ha producido un error en el subsistema de red.
WSAENETRESET	Se ha interrumpido la conexión debido a que la actividad para mantener activa la conexión detectó un error durante la operación.
WSAENOBUFS	No se ha podido realizar una operación en un socket porque el sistema no tenía suficiente espacio en búfer o porque una cola estaba llena. Este error también se devuelve si el proveedor de Windows Sockets notifica un interbloqueo de búfer.
WSAENOTCONN	No se permitió una solicitud para enviar o recibir datos porque el socket no está conectado.
WSAENOTSOCK	Se ha intentado realizar una operación en algo que no es un socket. Este error se devuelve si el parámetro hSocket no es un socket.
WSAESHUTDOWN	No se ha permitido la solicitud para enviar o recibir datos porque el socket ya se había apagado en esa dirección con una llamada de apagado previa. Este error se devuelve si el socket se ha apagado para el envío. No es posible llamar a TransmitFile en un socket después de llamar a la función de apagado en el socket con el parámetro how establecido en SD_SEND o SD_BOTH.
WSANOTINITIALISED	La aplicación no ha llamado a la función WSAStartup o WSAStartup no se pudo realizar. Se debe producir una llamada WSAStartup correcta antes de usar la función TransmitFile .
WSA_IO_PENDING	Hay una operación de E/S superpuesta en curso. Este valor se devuelve si se inició correctamente una operación de E/S superpuesta e indica que la finalización se indicará más adelante.
WSA_OPERATION_ABORTED	Se ha anulado la operación de E/S debido a una solicitud de la aplicación o una salida del subproceso. Este error se devuelve si se ha cancelado la operación superpuesta debido al cierre del socket, la ejecución del comando "SIO_FLUSH" en WSAIoctl o el subproceso que inició la solicitud superpuesta se cerró antes de que se complete la operación. Nota Todas las E/S iniciadas por un subproceso determinado se cancelan cuando se cierra ese subproceso. En el caso de los sockets superpuestos, las operaciones asincrónicas pendientes pueden producir un error si el subproceso se cierra antes de que se completen las operaciones asincrónicas. Para obtener más información, vea ExitThread.

Comentarios

La función TransmitFile usa el administrador de caché del sistema operativo para recuperar los datos de archivo y proporcionar transferencia de datos de archivos de alto rendimiento a través de sockets.

La función TransmitFile solo admite sockets orientados a la conexión de tipo SOCK_STREAM, SOCK_SEQPACKET y SOCK_RDM. No se admiten sockets de tipo SOCK_DGRAM y SOCK_RAW . La función TransmitPackets se puede usar con sockets de tipo SOCK_DGRAM.

El número máximo de bytes que se pueden transmitir mediante una sola llamada a la función TransmitFile es 2.147.483.646, el valor máximo de un entero de 32 bits menos 1. El número máximo de bytes que se van a enviar en una sola llamada incluye los datos enviados antes o después de los datos del archivo a los que apunta el parámetro lpTransmitBuffers más el valor especificado en el parámetro nNumberOfBytesToWrite para la longitud de los datos de archivo que se van a enviar. Si una aplicación necesita transmitir un archivo mayor que 2.147.483.646 bytes, se pueden usar varias llamadas a la función TransmitFile con cada llamada que transfiera no más de 2.147.483.646 bytes. Si se establece el parámetro nNumberOfBytesToWrite en cero para un archivo mayor que 2.147.483.646 bytes, también se producirá un error, ya que en este caso, la función TransmitFile usará el tamaño del archivo como valor para el número de bytes que se van a transmitir.

Nota El puntero de función para la función TransmitFile debe obtenerse en tiempo de ejecución realizando una llamada a la función WSAIoctl con el código de operación SIO_GET_EXTENSION_FUNCTION_POINTER especificado. El búfer de entrada pasado a la función WSAIoctl debe contener WSAID_TRANSMITFILE, un identificador único global (GUID) cuyo valor identifica la función de extensión TransmitFile . Si se ejecuta correctamente, la salida devuela por la función WSAIoctl contiene un puntero a la función TransmitFile . El GUID de WSAID_TRANSMITFILE se define en el archivo de encabezado Mswsock.h .

NotaTransmitFile no es funcional en los transportes que realizan su propio almacenamiento en búfer. Los transportes con la marca TDI_SERVICE_INTERNAL_BUFFERING establecida, como ADSP, realizan su propio almacenamiento en búfer. Dado que TransmitFile logra sus ganancias de rendimiento mediante el envío de datos directamente desde la memoria caché de archivos. Los transportes que se quedan sin espacio en búfer en una conexión determinada no se controlan mediante TransmitFile y, como resultado de quedarse sin espacio de búfer en la conexión, TransmitFile devuelve STATUS_DEVICE_NOT_READY.

La función TransmitFile se agregó principalmente a Winsock para su uso por parte de aplicaciones de servidor de alto rendimiento (servidores web y ftp, por ejemplo).

Las versiones de estación de trabajo y cliente de Windows optimizan la función TransmitFile para un uso mínimo de memoria y recursos limitando el número de operaciones de TransmitFile simultáneas permitidas en el sistema a un máximo de dos. En Windows Vista, Windows XP, Windows 2000 Professional y Windows NT Workstation 3.51 y versiones posteriores, solo se controlan simultáneamente dos solicitudes de TransmitFile pendientes; la tercera solicitud esperará hasta que se complete una de las solicitudes anteriores.

Las versiones de servidor de Windows optimizan la función TransmitFile para un alto rendimiento. En las versiones del servidor, no hay límites predeterminados colocados en el número de operaciones de TransmitFile simultáneas permitidas en el sistema. Espere mejores resultados de rendimiento al usar TransmitFile en versiones de servidor de Windows. En las versiones de servidor de Windows, es posible establecer un límite en el número máximo de operaciones de TransmitFile simultáneas creando una entrada del Registro y estableciendo un valor para el siguiente REG_DWORD:

HKEY_LOCAL_MACHINE\Currentcontrolset\Servicios\AFD\Parámetros\MaxActiveTransmitFileCount

Si se llama a la función TransmitFile con socket TCP (protocolo de IPPROTO_TCP) con las marcas TF_DISCONNECT y TF_REUSE_SOCKET especificadas, la llamada no se completará hasta que se cumplan las dos condiciones siguientes.

Todos los datos de recepción pendientes enviados por el lado remoto (recibidos antes de un FIN desde el lado remoto) en el socket TCP se han leído.
El lado remoto ha cerrado la conexión (completó el cierre de conexión TCP con gracia).

Si se llama a la función TransmitFile con el parámetro lpOverlapped establecido en NULL, la operación se ejecuta como E/S sincrónica. La función no se completará hasta que se haya enviado el archivo.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Notas de QoS

La función TransmitFile permite establecer dos marcas, TF_DISCONNECT o TF_REUSE_SOCKET, que devuelven el socket a un estado "desconectado y reutilizable" después de que se haya transmitido el archivo. Estas marcas no deben utilizarse en un socket en el que se haya solicitado la calidad del servicio, ya que el proveedor de servicios puede eliminar inmediatamente cualquier calidad de servicio asociada al socket antes de que se haya completado la transferencia de archivos. El mejor enfoque para un socket habilitado para QoS es simplemente llamar a la función closesocket cuando se haya completado la transferencia de archivos, en lugar de confiar en estas marcas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	mswsock.h (incluya Mswsock.h)
Library	Mswsock.lib
Archivo DLL	Mswsock.dll