LPFN_TRANSMITPACKETS función de devolución de llamada (mswsock.h)

Artículo
03/15/2023

La función TransmitPackets transmite datos en memoria o datos de archivo a través de un socket conectado. La función TransmitPackets usa el administrador de caché del sistema operativo para recuperar datos de archivo, bloquear la memoria durante el tiempo mínimo necesario para transmitir y dar lugar a una transmisión eficaz y de alto rendimiento.

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

Sintaxis

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

Parámetros

hSocket

Identificador del socket conectado que se va a utilizar en la transmisión. Aunque el socket no necesita ser un circuito orientado a la conexión, se debe haber establecido el destino o el mismo nivel predeterminado mediante la función connect, WSAConnect, accept, WSAAccept, AcceptEx o WSAJoinLeaf .

lpPacketArray

Matriz de tipo TRANSMIT_PACKETS_ELEMENT, que describe los datos que se van a transmitir.

nElementCount

Número de elementos de lpPacketArray.

nSendSize

Tamaño, en bytes, del bloque de datos usado en la operación de envío . Establezca nSendSize en cero para permitir que la capa de sockets seleccione un tamaño de envío predeterminado.

Al establecer nSendSize en 0xFFFFFFF permite al autor de la llamada controlar el tamaño y el contenido de cada solicitud de envío , que se logra mediante el uso de la marca TP_ELEMENT_EOP en la matriz de TRANSMIT_PACKETS_ELEMENT a la que apunta el parámetro lpPacketArray . Esta funcionalidad es útil para los protocolos de mensajes que colocan limitaciones en el tamaño de las solicitudes de envío individuales.

lpOverlapped

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

dwFlags

Conjunto de marcas que se usan para personalizar el procesamiento de la función TransmitPackets . En la tabla siguiente se describe el uso del parámetro dwFlags .

Valor	Significado
TF_DISCONNECT	Inicia una desconexión de nivel de transporte después de que todos los datos del archivo se hayan puesto en cola para su transmisión. Solo se aplica a sockets orientados a la conexión. Si se especifica esta marca para los sockets que no admiten la semántica de desconexión (como los sockets de datagramas), se producirá un error.
TF_REUSE_SOCKET	Prepara el identificador de socket que se va a reutilizar. Cuando se completa la función TransmitPackets , el identificador de socket se puede pasar a la función AcceptEx . Válido solo cuando se especifica un socket orientado a la conexión y TF_DISCONNECT. Nota La transmisión de paquetes de nivel de socket está sujeta al comportamiento del transporte subyacente. Por ejemplo, un socket TCP puede estar sujeto al estado de TIME_WAIT TCP, lo que provoca que la llamada a TransmitPackets se retrase.
TF_USE_DEFAULT_WORKER	Dirige Winsock para usar el subproceso predeterminado del sistema para procesar solicitudes de TransmitPackets largas . Las solicitudes Long TransmitPackets se definen como solicitudes que requieren más de una sola lectura del archivo o una memoria caché; Por lo tanto, la definición de solicitud larga depende del tamaño del archivo y de la longitud especificada del paquete de envío. El subproceso predeterminado del sistema se puede ajustar mediante el siguiente parámetro del Registro como una REG_DWORD:HKEY_LOCAL_MACHINE\Parámetros\afd\ deservicios CurrentControlSet\\TransmitWorker
TF_USE_SYSTEM_THREAD	Dirige Winsock para usar subprocesos del sistema para procesar solicitudes de TransmitPackets largas . Las solicitudes Long TransmitPackets se definen como solicitudes que requieren más de una sola lectura del archivo o una memoria caché; Por lo tanto, la definición de solicitud larga depende del tamaño del archivo y de la longitud especificada del paquete de envío.
TF_USE_KERNEL_APC	Dirige Winsock para usar llamadas a procedimientos asincrónicos (APCs) de kernel en lugar de subprocesos de trabajo para procesar solicitudes de TransmitPackets largas. Las solicitudes Long TransmitPackets se definen como solicitudes que requieren más de una sola lectura del archivo o una memoria caché; Por lo tanto, la definición de solicitud larga depende del tamaño del archivo y de la longitud especificada del paquete de envío. Vea Comentarios para obtener más información.

Valor devuelto

Si la función TransmitPackets 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 lpPacketArray o el parámetro lpOverlapped no están totalmente contenidos 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 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 número total de bytes que se van a transmitir es 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. Este error se devuelve para un socket de flujo en el que se interrumpió la conexión debido a que la actividad keep-alive detecta un error.
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. Este error se devuelve para un socket de flujo.
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 se ha cerrado un socket de flujo para el envío. No es posible llamar a TransmitFile en un socket de secuencia 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 realizar 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 la operación superpuesta se ha cancelado 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 TransmitPackets está optimizada según el sistema operativo en el que se usa:

En las ediciones de Windows Server, la función TransmitPackets está optimizada para un alto rendimiento.
En las ediciones de cliente de Windows, la función TransmitPackets está optimizada para un uso mínimo de memoria y recursos.

El número máximo de bytes que se pueden transmitir mediante una sola llamada a la función TransmitPackets es 2.147.483.646, el valor máximo de un entero de 32 bits menos 1. Si una aplicación necesita transmitir datos de más de 2.147.483.646 bytes, se pueden usar varias llamadas a la función TransmitPackets con cada llamada que transfiera no más de 2.147.483.646 bytes.

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

Espere mejores resultados de rendimiento al usar la función TransmitPackets en Windows Server 2003.

Cuando lpOverlapped no es NULL, es posible que la E/S superpuesta no finalice antes de que se devuelva la función TransmitPackets . Cuando esto ocurre, la función TransmitPackets devuelve un error y una llamada a la función WSAGetLastError devuelve ERROR_IO_PENDING, lo que permite al autor de la llamada continuar procesando mientras se completa la transmisió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 está cerrado antes de que se completen las operaciones. Consulte ExitThread para obtener más información.

Cuando la función TransmitPackets devuelve TRUE o devuelve FALSE y WSAGetLastError devuelve ERROR_IO_PENDING, Windows establece el evento especificado por el miembro hEvent de la estructura SUPERPUESTA o el socket especificado por hSocket al estado señalado y, tras la finalización, entrega una notificación a cualquier puerto de finalización asociado al socket. Use GetOverlappedResult, WSAGetOverlappedResult o GetQueuedCompletionStatus para recuperar el estado final y el número de bytes transmitidos.

TransmitPackets y llamadas a procedimientos asincrónicos (APCs)

El uso de la marca TF_USE_KERNEL_APC puede ofrecer ventajas de rendimiento significativas. Si el subproceso que inicia la llamada a la función TransmitPackets se usa para cálculos pesados, es posible, aunque poco probable, que se podrían impedir que se inicien las API.

Nota Hay una diferencia entre las API de kernel y modo de usuario:

Las API de kernel se inician cuando un subproceso está en un estado de espera.
Las API en modo de usuario se inician cuando un subproceso está en un estado de espera alertable.

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.

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