LPFN_TRANSMITPACKETS 콜백 함수(mswsock.h)

아티클
08/25/2023

TransmitPackets 함수는 연결된 소켓을 통해 메모리 내 데이터 또는 파일 데이터를 전송합니다. TransmissionPackets 함수는 운영 체제 캐시 관리자를 사용하여 파일 데이터를 검색하고 전송에 필요한 최소 시간 동안 메모리를 잠그고 효율적인 고성능 전송을 생성합니다.

참고 이 함수는 Windows 소켓 사양에 대한 Microsoft 관련 확장입니다.

구문

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

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

매개 변수

hSocket

전송에 사용할 연결된 소켓에 대한 핸들입니다. 소켓이 연결 지향 회로일 필요는 없지만 연결, WSAConnect, accept, WSAAccept, AcceptEx 또는 WSAJoinLeaf 함수를 사용하여 기본 대상/피어를 설정해야 합니다.

lpPacketArray

전송할 데이터를 설명하는 TRANSMIT_PACKETS_ELEMENT 형식의 배열입니다.

nElementCount

lpPacketArray의 요소 수입니다.

nSendSize

보내기 작업에 사용되는 데이터 블록의 크기(바이트)입니다. nSendSize를 0으로 설정하여 소켓 계층이 기본 송신 크기를 선택할 수 있도록 합니다.

nSendSize를 0xFFFFFFF 설정하면 호출자는 lpPacketArray 매개 변수에서 가리키는 TRANSMIT_PACKETS_ELEMENT 배열의 TP_ELEMENT_EOP 플래그를 사용하여 각 송신 요청의 크기와 콘텐츠를 제어할 수 있습니다. 이 기능은 개별 송신 요청의 크기에 제한을 두는 메시지 프로토콜에 유용합니다.

lpOverlapped

OVERLAPPED 구조에 대한 포인터입니다. hSocket 매개 변수에 지정된 소켓 핸들이 겹치는 것으로 열려 있는 경우 이 매개 변수를 사용하여 비동기(겹치는) I/O 작업을 수행합니다. 소켓 핸들은 기본적으로 겹치는 대로 열립니다.

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\매개 변수\전송작업자로 조정할 수 있습니다.
TF_USE_SYSTEM_THREAD	Winsock에 시스템 스레드를 사용하여 긴 TransmitPackets 요청을 처리하도록 지시합니다. 긴 TransmitPackets 요청은 파일 또는 캐시에서 하나 이상의 읽기가 필요한 요청으로 정의됩니다. 따라서 긴 요청 정의는 파일의 크기와 송신 패킷의 지정된 길이에 따라 달라집니다.
TF_USE_KERNEL_APC	Winsock이 작업자 스레드 대신 커널 APC(비동기 프로시저 호출 )를 사용하여 긴 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 플래그가 설정되지 않은 경우 이 오류가 반환됩니다. lpOverlapped에서 가리키는 OVERLAPPED 구조체에 지정된 오프셋이 파일 내에 없는 경우에도 이 오류가 반환됩니다. 전송할 총 바이트 수가 2,147,483,646보다 큰 값이고 32비트 정수에서 1을 뺀 값인 경우에도 이 오류가 반환됩니다.
WSAENETDOWN	소켓 작업에 데드 네트워크가 발생했습니다. 이 오류는 네트워크 하위 시스템이 실패한 경우 반환됩니다.
WSAENETRESET	해당 작업이 진행되는 동안 오류가 발생하여 연결이 끊겼습니다. 이 오류는 오류를 감지하는 유지 활동으로 인해 연결이 끊어진 스트림 소켓에 대해 반환됩니다.
WSAENOBUFS	시스템에 충분한 버퍼 공간이 부족하거나 큐가 가득 차서 소켓에서 작업을 수행할 수 없습니다. 이 오류는 Windows 소켓 공급자가 버퍼 교착 상태를 보고하는 경우에도 반환됩니다.
WSAENOTCONN	소켓이 연결되지 않았기 때문에 데이터를 보내거나 받는 요청이 허용되지 않았습니다. 이 오류는 스트림 소켓에 대해 반환됩니다.
WSAENOTSOCK	소켓이 아닌 항목에서 작업을 시도했습니다. hSocket 매개 변수가 소켓이 아닌 경우 이 오류가 반환됩니다.
WSAESHUTDOWN	이전의 종료 호출로 그 방향에서 이미 소켓이 종료되었기 때문에 데이터 보내기 또는 받기 요청이 허용되지 않습니다. 이 오류는 전송을 위해 스트림 소켓이 종료된 경우 반환됩니다. 매개 변수가 SD_SEND 또는 SD_BOTH 설정된 방법을 사용하여 소켓에서 종료 함수가 호출된 후에는 스트림 소켓에서 TransmitFile을 호출할 수 없습니다.
WSANOTINITIALISED	애플리케이션이 WSAStartup 함수를 호출하지 않았거나 WSAStartup 이 실패했습니다. TransmitFile 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSA_IO_PENDING	겹치는 I/O 작업이 진행 중입니다. 겹치는 I/O 작업이 성공적으로 시작되고 나중에 완료가 표시됨을 나타내는 경우 이 값이 반환됩니다.
WSA_OPERATION_ABORTED	스레드 종료 또는 애플리케이션 요청으로 인해 I/O 작업이 중단되었습니다. 이 오류는 소켓의 닫기, WSAIoctl의 "SIO_FLUSH" 명령 실행 또는 작업이 완료되기 전에 겹친 요청을 시작한 스레드로 인해 겹친 작업이 취소된 경우 반환됩니다. 참고 지정된 스레드에서 시작한 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 비동기 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread를 참조하세요.

설명

TransmitPackets 함수는 사용되는 운영 체제에 따라 최적화됩니다.

Windows 서버 버전에서 TransmitPackets 함수는 고성능에 최적화되어 있습니다.
Windows 클라이언트 버전에서 TransmitPackets 함수는 최소 메모리 및 리소스 사용률에 최적화되어 있습니다.

TransmitPackets 함수에 대한 단일 호출을 사용하여 전송할 수 있는 최대 바이트 수는 2,147,483,646이며, 32비트 정수의 최대값은 1을 뺀 값입니다. 애플리케이션이 2,147,483,646바이트보다 큰 데이터를 전송해야 하는 경우 2,147,483,646바이트 이하를 전송하는 각 호출과 함께 TransmitPackets 함수에 대한 여러 호출을 사용할 수 있습니다.

참고 SIO_GET_EXTENSION_FUNCTION_POINTER opcode가 지정된 WSAIoctl 함수를 호출하여 런타임에 TransmitPackets 함수에 대한 함수 포인터를 가져와야 합니다. WSAIoctl 함수에 전달된 입력 버퍼에는 값이 TransmitPackets 확장 함수를 식별하는 GUID(Globally Unique Identifier)인 WSAID_TRANSMITPACKETS 포함되어야 합니다. 성공하면 WSAIoctl 함수에서 반환된 출력에 TransmitPackets 함수에 대한 포인터가 포함됩니다. WSAID_TRANSMITPACKETS GUID는 Mswsock.h 헤더 파일에 정의되어 있습니다.

Windows Server 2003에서 TransmitPackets 함수를 사용할 때 더 나은 성능 결과를 기대합니다.

lpOverlapped가 NULL이 아닌 경우 겹치는 I/O는 TransmitPackets 함수가 반환되기 전에 완료되지 않을 수 있습니다. 이 경우 TransmitPackets 함수가 반환되지 않고 WSAGetLastError 함수를 호출하면 ERROR_IO_PENDING 반환되므로 전송이 완료되는 동안 호출자가 처리를 계속할 수 있습니다.

참고 지정된 스레드에서 시작된 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread 를 참조하세요.

TransmitPackets 함수가 TRUE를 반환하거나 FALSE를 반환하고 WSAGetLastError가 ERROR_IO_PENDING 반환하면 Windows는 OVERLAPPED 구조체의 hEvent 멤버 또는 hSocket에 의해 지정된 소켓에 지정된 이벤트를 신호 상태로 설정하고 완료 시 소켓과 연결된 모든 완료 포트에 알림을 전달합니다. GetOverlappedResult 또는 WSAGetOverlappedResult 또는 GetQueuedCompletionStatus를 사용하여 전송된 최종 상태 및 바이트 수를 검색합니다.

TransmitPackets 및 APC(비동기 프로시저 호출)

TF_USE_KERNEL_APC 플래그를 사용하면 상당한 성능 이점을 제공할 수 있습니다. TransmitPackets 함수 호출을 시작하는 스레드가 무거운 계산에 사용되는 경우 해당 APC가 시작되지 않도록 방지할 수 있습니다.

참고 커널과 사용자 모드 APC 간에는 차이가 있습니다.

스레드가 대기 상태일 때 커널 APC가 시작됩니다.
스레드가 경고 대기 상태일 때 사용자 모드 APC가 시작됩니다.

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8.1, Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	mswsock.h