TransmitFile 함수(winsock.h)
TransmitFile 함수는 연결된 소켓 핸들을 통해 파일 데이터를 전송합니다. 이 함수는 운영 체제의 캐시 관리자를 사용하여 파일 데이터를 검색하고 소켓을 통해 고성능 파일 데이터 전송을 제공합니다.
구문
BOOL TransmitFile(
SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwReserved
);
매개 변수
hSocket
연결된 소켓에 대한 핸들입니다. TransmitFile 함수는 이 소켓을 통해 파일 데이터를 전송합니다. hSocket 매개 변수로 지정된 소켓은 SOCK_STREAM,SOCK_SEQPACKET또는 SOCK_RDM 형식의 연결 지향 소켓이어야 합니다.
hFile
TransmitFile 함수가 전송하는 열린 파일에 대한 핸들입니다. 운영 체제는 파일 데이터를 순차적으로 읽기 때문에 FILE_FLAG_SEQUENTIAL_SCAN 핸들을 열어 캐싱 성능을 향상시킬 수 있습니다.
hFile 매개 변수는 선택 사항입니다. hFile 매개 변수가 NULL이면 헤더 및/또는 테일 버퍼의 데이터만 전송됩니다. 소켓 연결 끊기 또는 다시 사용과 같은 추가 작업은 dwFlags 매개 변수에 지정된 대로 수행됩니다.
nNumberOfBytesToWrite
전송할 파일의 바이트 수입니다. TransmitFile 함수는 지정된 바이트 수를 보냈거나 오류가 발생할 때(어느 것이든 먼저 발생하는 경우) 완료됩니다.
전체 파일을 전송하려면 이 매개 변수를 0으로 설정합니다.
nNumberOfBytesPerSend
각 송신 작업에서 전송되는 각 데이터 블록의 크기(바이트)입니다. 이 매개 변수는 Windows 소켓 계층에서 송신 작업의 블록 크기를 결정하는 데 사용됩니다. 기본 보내기 크기를 선택하려면 이 매개 변수를 0으로 설정합니다.
nNumberOfBytesPerSend 매개 변수는 개별 송신 요청의 크기에 제한이 있는 프로토콜에 유용합니다.
lpOverlapped
OVERLAPPED 구조에 대한 포인터입니다. 소켓 핸들이 겹치는 것으로 열린 경우 겹치는(비동기) I/O 작업을 수행하려면 이 매개 변수를 지정합니다. 기본적으로 소켓 핸들은 겹치는 대로 열립니다.
lpOverlapped 매개 변수를 사용하여 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 설정하여 파일 데이터 전송을 시작할 파일 내에서 64비트 오프셋을 지정할 수 있습니다. lpOverlapped가 NULL 포인터인 경우 데이터 전송은 항상 파일의 현재 바이트 오프셋에서 시작됩니다.
lpOverlapped가 NULL이 아닌 경우 겹치는 I/O는 TransmitFile이 반환되기 전에 완료되지 않을 수 있습니다. 이 경우 TransmitFile 함수는 FALSE를 반환하고 WSAGetLastError 는 ERROR_IO_PENDING 또는 WSA_IO_PENDING 반환합니다. 이렇게 하면 파일 전송 작업이 완료되는 동안 호출자가 처리를 계속할 수 있습니다. Windows는 데이터 전송 요청이 완료될 때 OVERLAPPED 구조체의 hEvent 멤버 또는 hSocket에서 지정한 소켓에 지정된 이벤트를 신호 상태로 설정합니다.
lpTransmitBuffers
파일 데이터가 전송되기 전과 후에 보낼 데이터에 대한 포인터를 포함하는 TRANSMIT_FILE_BUFFERS 데이터 구조에 대한 포인터입니다. 파일 데이터만 전송하려면 이 매개 변수를 NULL 포인터로 설정해야 합니다.
dwReserved
TransmitFile 함수 호출의 동작을 수정하는 데 사용되는 플래그 집합입니다. dwFlags 매개 변수는 Mswsock.h 헤더 파일에 정의된 다음 옵션의 조합을 포함할 수 있습니다.
| 플래그 | 의미 |
|---|---|
|
전송을 위해 모든 파일 데이터를 큐에 대기시킨 후 전송 수준에서 연결 끊기를 시작합니다. |
|
재사용할 소켓 핸들을 준비합니다. 이 플래그는 TF_DISCONNECT 지정한 경우에만 유효합니다.
TransmitFile 요청이 완료되면 소켓 핸들을 이전에 AcceptEx 또는 ConnectEx와 같은 연결을 설정하는 데 사용된 함수 호출에 전달할 수 있습니다. 이러한 재사용은 상호 배타적입니다. 예를 들어 AcceptEx 함수가 소켓에 대해 호출된 경우 AcceptEx 함수에 대한 후속 호출에만 재사용이 허용되며 ConnectEx에 대한 후속 호출에는 허용되지 않습니다.
참고 소켓 수준 파일 전송에는 기본 전송의 동작이 적용됩니다. 예를 들어 TCP 소켓에는 TCP TIME_WAIT 상태가 적용되어 TransmitFile 호출이 지연될 수 있습니다.
|
|
Windows Sockets 서비스 공급자가 시스템의 기본 스레드를 사용하여 긴 TransmitFile 요청을 처리하도록 지시합니다. 시스템 기본 스레드는 다음 레지스트리 매개 변수를 REG_DWORD 사용하여 조정할 수 있습니다. Hkey_local_machine\CurrentControlSet\서비스\Afd\매개 변수\TransmitWorker |
|
Windows Sockets 서비스 공급자가 시스템 스레드를 사용하여 긴 TransmitFile 요청을 처리하도록 지시합니다. |
|
드라이버가 작업자 스레드 대신 APC(커널 비동기 프로시저 호출)를 사용하여 긴 TransmitFile 요청을 처리하도록 지시합니다. Long TransmitFile 요청은 파일 또는 캐시에서 단일 읽기가 필요한 요청으로 정의됩니다. 따라서 요청은 파일의 크기와 송신 패킷의 지정된 길이에 따라 달라집니다.
TF_USE_KERNEL_APC 사용하면 상당한 성능 이점을 제공할 수 있습니다. 그러나 컨텍스트 TransmitFile 이 시작되는 스레드가 많은 계산에 사용될 수 있습니다. 이 경우 APC가 시작되지 않을 수 있습니다. Winsock 커널 모드 드라이버는 스레드가 대기 상태에 있을 때마다 시작되는 일반 커널 APC를 사용합니다. 이는 스레드가 사용자 모드에서 시작된 경고 대기 상태에 있을 때마다 시작되는 사용자 모드 APC와 다릅니다.) |
|
보류되지 않고 즉시 TransmitFile 요청을 완료합니다. 이 플래그가 지정되고 TransmitFile 이 성공하면 시스템에서 데이터를 수락했지만 원격 엔드에서 반드시 승인하지는 않습니다. 이 설정은 TF_DISCONNECT 및 TF_REUSE_SOCKET 플래그와 함께 사용하지 마세요.
참고 전송되는 파일이 파일 시스템 캐시에 없으면 요청이 보류됩니다.
|
반환 값
TransmitFile 함수가 성공하면 반환 값은 TRUE입니다. 그렇지 않으면 반환 값이 FALSE입니다. 확장 오류 정보를 얻으려면 WSAGetLastError를 호출합니다. WSA_IO_PENDING 또는 ERROR_IO_PENDING 오류 코드는 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됨을 나타냅니다. 다른 오류 코드는 겹치는 작업이 성공적으로 시작되지 않았으며 완료 표시가 발생하지 않음을 나타냅니다. 이 경우 애플리케이션은 ERROR_IO_PENDING 또는 WSA_IO_PENDING 처리해야 합니다.
| 반환 코드 | 설명 |
|---|---|
| 호스트 컴퓨터의 소프트웨어에 의해 설정된 연결이 중단되었습니다. 이 오류는 시간 제한 또는 기타 오류로 인해 가상 회로가 종료된 경우 반환됩니다. | |
| 현재 연결은 원격 호스트에 의해 강제로 끊겼습니다. 이 오류는 원격 쪽에서 가상 회로를 다시 설정할 때 스트림 소켓에 대해 반환됩니다. 더 이상 소켓을 사용할 수 없으므로 응용 프로그램이 소켓을 닫아야 합니다. | |
| 시스템이 호출에서 포인터 인수를 사용하려는 시도에서 잘못된 포인터 주소를 발견했습니다. lpTransmitBuffers 또는 lpOverlapped 매개 변수가 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않은 경우 이 오류가 반환됩니다. | |
| 잘못된 인수가 지정되었습니다. hSocket 매개 변수가 SOCK_DGRAM 또는 SOCK_RAW 형식의 소켓을 지정한 경우 이 오류가 반환됩니다. dwFlags 매개 변수에 TF_REUSE_SOCKET 플래그가 설정되어 있지만 TF_DISCONNECT 플래그가 설정되지 않은 경우 이 오류가 반환됩니다. lpOverlapped에서 가리키는 OVERLAPPED 구조체에 지정된 오프셋이 파일 내에 없는 경우에도 이 오류가 반환됩니다. nNumberOfBytesToWrite 매개 변수가 32비트 정수에서 1을 뺀 값인 2,147,483,646보다 큰 값으로 설정된 경우에도 이 오류가 반환됩니다. | |
| 소켓 작업에 데드 네트워크가 발생했습니다. 이 오류는 네트워크 하위 시스템이 실패한 경우 반환됩니다. | |
| 해당 작업이 진행되는 동안 오류가 발생하여 연결이 끊겼습니다. | |
| 시스템에 충분한 버퍼 공간이 부족하거나 큐가 가득 차서 소켓에서 작업을 수행할 수 없습니다. 이 오류는 Windows 소켓 공급자가 버퍼 교착 상태를 보고하는 경우에도 반환됩니다. | |
| 소켓이 연결되지 않았기 때문에 데이터를 보내거나 받는 요청이 허용되지 않았습니다. | |
| 소켓이 아닌 항목에서 작업을 시도했습니다. hSocket 매개 변수가 소켓이 아닌 경우 이 오류가 반환됩니다. | |
| 이전의 종료 호출로 그 방향에서 이미 소켓이 종료되었기 때문에 데이터 보내기 또는 받기 요청이 허용되지 않습니다. 이 오류는 소켓이 보내기 위해 종료된 경우 반환됩니다. 매개 변수가 SD_SEND또는 SD_BOTH 설정된 방법을 사용하여 소켓에서 종료 함수가 호출된 후에는 소켓에서 TransmitFile을 호출할 수 없습니다. | |
| 애플리케이션이 WSAStartup 함수를 호출하지 않았거나 WSAStartup 이 실패했습니다. TransmitFile 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다. | |
| 겹치는 I/O 작업이 진행 중입니다. 겹치는 I/O 작업이 성공적으로 시작되고 나중에 완료가 표시됨을 나타내는 경우 이 값이 반환됩니다. | |
|
스레드 종료 또는 애플리케이션 요청으로 인해 I/O 작업이 중단되었습니다. 이 오류는 소켓의 닫기, WSAIoctl의 "SIO_FLUSH" 명령 실행 또는 작업이 완료되기 전에 겹친 요청을 시작한 스레드로 인해 겹친 작업이 취소된 경우 반환됩니다.
참고 지정된 스레드에서 시작한 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 비동기 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread를 참조하세요.
|
설명
TransferFile 함수는 운영 체제의 캐시 관리자를 사용하여 파일 데이터를 검색하고 소켓을 통해 고성능 파일 데이터 전송을 제공합니다.
TransmitFile 함수는 SOCK_STREAM,SOCK_SEQPACKET및 SOCK_RDM 형식의 연결 지향 소켓만 지원합니다. SOCK_DGRAM 및 SOCK_RAW 유형의 소켓은 지원되지 않습니다. TransmitPackets 함수는 SOCK_DGRAM 형식의 소켓과 함께 사용할 수 있습니다.
TransmitFile 함수에 대한 단일 호출을 사용하여 전송할 수 있는 최대 바이트 수는 2,147,483,646이며, 32비트 정수의 최대값은 1을 뺀 값입니다. 단일 호출에서 보낼 최대 바이트 수에는 lpTransmitBuffers 매개 변수가 가리키는 파일 데이터 전후에 전송된 모든 데이터와 보낼 파일 데이터의 길이에 대해 nNumberOfBytesToWrite 매개 변수에 지정된 값이 포함됩니다. 애플리케이션이 2,147,483,646바이트보다 큰 파일을 전송해야 하는 경우 2,147,483,646바이트 이하를 전송하는 각 호출과 함께 TransmitFile 함수에 대한 여러 호출을 사용할 수 있습니다. 2,147,483,646바이트보다 큰 파일에 대해 nNumberOfBytesToWrite 매개 변수를 0으로 설정하면 이 경우 TransmitFile 함수는 파일 크기를 전송할 바이트 수의 값으로 사용하기 때문에 실패합니다.
워크스테이션 및 클라이언트 버전의 Windows는 시스템에서 허용되는 동시 TransmissionFile 작업의 수를 최대 2개로 제한하여 최소 메모리 및 리소스 사용률을 위해 TransmissionFile 함수를 최적화합니다. Windows Vista, Windows XP, Windows 2000 Professional 및 Windows NT Workstation 3.51 이상에서는 두 개의 미해결 TransmitFile 요청만 동시에 처리됩니다. 세 번째 요청은 이전 요청 중 하나가 완료될 때까지 기다립니다.
서버 버전의 Windows는 고성능을 위해 TransmissionFile 함수를 최적화합니다. 서버 버전에서는 시스템에서 허용되는 동시 전송 파일 작업 수에 대한 기본 제한이 없습니다. 서버 버전의 Windows에서 TransmitFile 을 사용할 때 더 나은 성능 결과를 기대합니다. Windows 서버 버전에서는 레지스트리 항목을 만들고 다음 REG_DWORD 값을 설정하여 동시 전송 파일 작업의 최대 수에 대한 제한을 설정할 수 있습니다.
Hkey_local_machine\CurrentControlSet\서비스\Afd\매개 변수\MaxActiveTransmitFileCount
TF_DISCONNECT 플래그와 TF_REUSE_SOCKET 플래그가 모두 지정된 TCP 소켓(IPPROTO_TCP 프로토콜)을 사용하여 TransmissionFile 함수를 호출하는 경우 다음 두 조건이 충족될 때까지 호출이 완료되지 않습니다.
- TCP 소켓에서 원격 쪽에서 보낸 보류 중인 모든 수신 데이터(원격 쪽에서 FIN 이전에 수신됨)가 읽혀졌습니다.
- 원격 쪽에서 연결을 닫습니다(정상 TCP 연결 닫기 완료).
lpOverlapped 매개 변수를 NULL로 설정하여 TransmitFile 함수를 호출하면 작업이 동기 I/O로 실행됩니다. 파일이 전송될 때까지 함수가 완료되지 않습니다.
Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.
Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.
QoS에 대한 참고 사항
TransmitFile 함수를 사용하면 파일이 전송된 후 소켓을 "연결이 끊어지거나 재사용 가능한" 상태로 반환하는 두 플래그(TF_DISCONNECT 또는 TF_REUSE_SOCKET)를 설정할 수 있습니다. 서비스 공급자가 파일 전송이 완료되기 전에 소켓과 연결된 서비스 품질을 즉시 삭제할 수 있으므로 서비스 품질이 요청된 소켓에서 이러한 플래그를 사용하면 안 됩니다. QoS 지원 소켓의 가장 좋은 방법은 이러한 플래그에 의존하지 않고 파일 전송이 완료되면 closesocket 함수를 호출하는 것입니다.요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8.1, Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | winsock.h(Mswsock.h 포함) |
| 라이브러리 | Mswsock.lib |
| DLL | Mswsock.dll |