функция обратного вызова LPFN_TRANSMITPACKETS (mswsock.h)

Статья
02/29/2024

Функция TransmitPackets передает данные в памяти или файловые данные через подключенный сокет. Функция TransmitPackets использует диспетчер кэша операционной системы для получения файловых данных, блокируя память на минимальное время, необходимое для передачи, что приводит к эффективной и высокопроизводительной передаче данных.

Примечание Эта функция является расширением для спецификации сокетов Windows, относящаяся к корпорации Майкрософт.

Синтаксис

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

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

Параметры

hSocket

Дескриптор подключенного сокета, который будет использоваться в передаче. Хотя сокет не обязательно должен быть каналом, ориентированным на подключение, назначение или одноранговый узел по умолчанию должен быть установлен с помощью функции connect, WSAConnect, accept, WSAAccept, AcceptEx или WSAJoinLeaf .

lpPacketArray

Массив типа TRANSMIT_PACKETS_ELEMENT, описывающий передаваемые данные.

nElementCount

Количество элементов в lpPacketArray.

nSendSize

Размер (в байтах) блока данных, используемого в операции отправки . Задайте nSendSize равным нулю, чтобы слой сокетов выбирал размер отправки по умолчанию.

Если задать для nSendSize значение 0xFFFFFFF, вызывающий объект может управлять размером и содержимым каждого запроса на отправку с помощью флага TP_ELEMENT_EOP в массиве TRANSMIT_PACKETS_ELEMENT , указанном в параметре lpPacketArray . Эта возможность полезна для протоколов сообщений, которые накладывают ограничения на размер отдельных запросов на отправку .

lpOverlapped

Указатель на структуру OVERLAPPED . Если дескриптор сокета, указанный в параметре hSocket , был открыт как перекрываемый, используйте этот параметр для выполнения асинхронной (перекрывающейся) операции ввода-вывода. По умолчанию дескриптор сокета открываются как перекрывающиеся.

dwFlags

Набор флагов, используемых для настройки обработки функции TransmitPackets . В следующей таблице описано использование параметра dwFlags .

Значение	Значение
TF_DISCONNECT	Запускает отключение на уровне транспорта после того, как все данные файлов будут помещены в очередь для передачи. Применяется только к сокетам, ориентированным на подключение. Указание этого флага для сокетов, которые не поддерживают семантику отключения (например, сокеты датаграмм), приводит к ошибке.
TF_REUSE_SOCKET	Подготавливает дескриптор сокета для повторного использовать. После завершения функции TransmitPackets дескриптор сокета можно передать в функцию AcceptEx . Допустимо только при указании сокета, ориентированного на подключение, и TF_DISCONNECT. Примечание Передача пакетов на уровне сокета зависит от поведения базового транспорта. Например, сокет TCP может находиться в состоянии TCP TIME_WAIT, что приводит к задержке вызова TransmitPackets .
TF_USE_DEFAULT_WORKER	Предписывает Winsock использовать системный поток по умолчанию для обработки длинных запросов TransmitPackets . Длинные запросы TransmitPackets определяются как запросы, требующие более одного считывания из файла или кэша; Поэтому определение длинного запроса зависит от размера файла и указанной длины отправляемого пакета. Системный поток по умолчанию можно настроить с помощью следующего параметра реестра в качестве REG_DWORD:HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\Parameters\TransmitWorker
TF_USE_SYSTEM_THREAD	Предписывает Winsock использовать системные потоки для обработки длинных запросов TransmitPackets . Длинные запросы TransmitPackets определяются как запросы, требующие более одного считывания из файла или кэша; Поэтому определение длинного запроса зависит от размера файла и указанной длины отправляемого пакета.
TF_USE_KERNEL_APC	Предписывает Winsock использовать асинхронные вызовы процедур ядра вместо рабочих потоков для обработки длинных запросов TransmitPackets . Длинные запросы TransmitPackets определяются как запросы, требующие более одного считывания из файла или кэша; Поэтому определение длинного запроса зависит от размера файла и указанной длины отправляемого пакета. Дополнительные сведения см. в разделе "Примечания".

Возвращаемое значение

Если функция TransmitPackets завершается успешно, возвращается значение TRUE. В противном случае возвращается значение FALSE. Чтобы получить расширенные сведения об ошибке, вызовите WSAGetLastError. Код ошибки WSA_IO_PENDING или ERROR_IO_PENDING указывает, что перекрывающаяся операция успешно запущена и что завершение будет указано позже. Любой другой код ошибки указывает на то, что перекрывающаяся операция не была успешно инициирована и не будет никаких указаний завершения. В этом случае приложения должны обрабатывать ERROR_IO_PENDING или WSA_IO_PENDING.

Код возврата	Описание
WSAECONNABORTED	Установленное подключение прервано программой на вашем компьютере. Эта ошибка возвращается, если виртуальный канал был прерван из-за истечения времени ожидания или другого сбоя.
WSAECONNRESET	существующее соединение было принудительно завершено удаленным узлом. Эта ошибка возвращается для сокета потока, когда виртуальная цепь была сброшена удаленной стороной. Приложение должно закрыть сокет, поскольку он больше не может использоваться.
WSAEFAULT	Система обнаружила недопустимый адрес указателя при попытке использовать аргумент указателя в вызове. Эта ошибка возвращается, если параметр lpPacketArray или lpOverlapped не полностью содержится в допустимой части адресного пространства пользователя.
WSAEINVAL	Указан недопустимый аргумент. Эта ошибка возвращается, если параметру dwFlags задан флаг TF_REUSE_SOCKET , но флаг TF_DISCONNECT не задан. Эта ошибка также возвращается, если смещение, указанное в структуре OVERLAPPED , на которую указывает lpOverlapped , не находится в файле. Эта ошибка также возвращается, если общее число передаваемых байтов больше 2 147 483 646, максимальное значение для 32-разрядного целого числа минус 1.
WSAENETDOWN	Операция сокета обнаружила неработающих сетей. Эта ошибка возвращается, если произошел сбой сетевой подсистемы.
WSAENETRESET	Подключение было разорвано из-за действия поддержания активности, обнаруживающего сбой во время выполнения операции. Эта ошибка возвращается для сокета потока, в котором подключение было разорвано из-за действия keep-alive, обнаруживающего сбой.
WSAENOBUFS	Не удалось выполнить операцию с сокетом, так как в системе недостаточно места в буфере или из-за переполнения очереди. Эта ошибка также возвращается, если поставщик сокетов Windows сообщает о взаимоблокировке буфера.
WSAENOTCONN	Запрос на отправку или получение данных был запрещен, так как сокет не подключен. Эта ошибка возвращается для сокета потока.
WSAENOTSOCK	Предпринята попытка выполнения операции с тем, что не является сокетом. Эта ошибка возвращается, если параметр hSocket не является сокетом.
WSAESHUTDOWN	Запрос на отправку или получение данных запрещен, так как сокет уже завершил работу в этом направлении по предыдущему запросу на завершение работы. Эта ошибка возвращается, если сокет потока был завершен для отправки. Невозможно вызвать TransmitFile в сокете потока после вызова функции завершения работы в сокете с параметром howSD_SEND или SD_BOTH.
WSANOTINITIALISED	Либо приложение не вызывало функцию WSAStartup , либо произошел сбой WSAStartup . Перед использованием функции TransmitFile должен быть выполнен успешный вызов WSAStartup.
WSA_IO_PENDING	Выполняется перекрываемая операция ввода-вывода. Это значение возвращается, если была успешно инициирована перекрывающаяся операция ввода-вывода, и указывает, что завершение будет указано позже.
WSA_OPERATION_ABORTED	Операция ввода-вывода прекращена из-за выхода из потока или запроса приложения. Эта ошибка возвращается, если перекрывающаяся операция была отменена из-за закрытия сокета, выполнения команды "SIO_FLUSH" в WSAIoctl или потока, который инициировал перекрывающийся запрос, завершился до завершения операции. Примечание Все операции ввода-вывода, инициированные данным потоком, отменяются при выходе из этого потока. Для перекрывающихся сокетов ожидающие асинхронные операции могут завершиться ошибкой, если поток будет закрыт до завершения асинхронных операций. Дополнительные сведения см. в разделе ExitThread.

В выпусках Windows Server функция TransmitPackets оптимизирована для высокой производительности.
В клиентских выпусках Windows функция TransmitPackets оптимизирована для минимального использования памяти и ресурсов.

Максимальное число байтов, которое может быть передано с помощью одного вызова функции TransmitPackets , составляет 2 147 483 646, максимальное значение для 32-разрядного целого числа минус 1. Если приложению требуется передать данные размером более 2 147 483 646 байт, то при каждом вызове можно использовать несколько вызовов функции TransmitPackets с передачей не более 2 147 483 646 байт.

Примечание Указатель функции для функции TransmitPackets должен быть получен во время выполнения путем вызова функции WSAIoctl с указанным SIO_GET_EXTENSION_FUNCTION_POINTER кодом операции. Входной буфер, передаваемый в функцию WSAIoctl , должен содержать WSAID_TRANSMITPACKETS, глобальный уникальный идентификатор (GUID), значение которого определяет функцию расширения TransmitPackets . При успешном выполнении выходные данные, возвращаемые функцией WSAIoctl , содержат указатель на функцию TransmitPackets . Guid WSAID_TRANSMITPACKETS определяется в файле заголовка Mswsock.h .

Ожидается более высокая производительность при использовании функции TransmitPackets в Windows Server 2003.

Если значение lpOverlapped не равно NULL, перекрытие ввода-вывода может не завершиться до возврата функции TransmitPackets . В этом случае функция TransmitPackets возвращает ошибку, а вызов функции WSAGetLastError возвращает ERROR_IO_PENDING, что позволяет вызывающему объекту продолжать обработку во время завершения передачи.

Примечание Все операции ввода-вывода, инициированные данным потоком, отменяются при выходе из этого потока. Для перекрывающихся сокетов ожидающие асинхронные операции могут завершиться сбоем, если поток закрывается до завершения операций. Дополнительные сведения см. в разделе ExitThread .

Когда функция TransmitPackets возвращает TRUE или FALSE , а WSAGetLastError возвращает ERROR_IO_PENDING, Windows устанавливает событие, заданное элементом hEvent структуры OVERLAPPED или сокетом, заданным hSocket , в состояние сигнальной передачи, а по завершении доставляет уведомление на любой порт завершения, связанный с сокетом. Используйте GetOverlappedResult, WSAGetOverlappedResult или GetQueuedCompletionStatus , чтобы получить окончательное состояние и количество передаваемых байтов.

TransmitPackets и асинхронные вызовы процедур (APC)

Использование флага TF_USE_KERNEL_APC может значительно повысить производительность. Если поток, инициирующий вызов функции TransmitPackets , используется для интенсивных вычислений, то запуск APC может быть запрещен, хотя и маловероятным.

Примечание Существует разница между ядром и пользовательским режимом APC:

Ядро APC запускается, когда поток находится в состоянии ожидания.
PPC пользовательского режима запускаются, когда поток находится в состоянии ожидания с оповещением.

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	mswsock.h