LPWSPSENDTO 콜백 함수(ws2spi.h)
LPWSPSendTo 함수는 겹치는 I/O를 사용하여 특정 대상으로 데이터를 보냅니다.
구문
LPWSPSENDTO Lpwspsendto;
int Lpwspsendto(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] const sockaddr *lpTo,
[in] int iTolen,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
매개 변수
[in] s
소켓을 식별하는 설명자입니다.
[in] lpBuffers
WSABUF 구조체 배열에 대한 포인터입니다. 각 WSABUF 구조체에는 버퍼에 대한 포인터와 버퍼의 길이(바이트)가 포함됩니다. Winsock 애플리케이션의 경우 LPWSPSendTo 함수가 호출되면 시스템에서 이러한 버퍼를 소유하고 애플리케이션이 액세스하지 못할 수 있습니다. 각 WSABUF 구조에서 참조되는 데이터 버퍼는 시스템에서 소유하며 애플리케이션이 호출 수명 동안 액세스하지 못할 수 있습니다.
[in] dwBufferCount
lpBuffers 배열의 WSABUF 구조체 수입니다.
[out] lpNumberOfBytesSent
이 호출에서 보낸 바이트 수에 대한 포인터입니다.
[in] dwFlags
호출이 이루어지는 방식을 지정하는 플래그 집합입니다.
[in] lpTo
sockaddr 구조체의 대상 소켓 주소에 대한 선택적 포인터입니다.
[in] iTolen
lpTo 매개 변수가 가리키는 주소의 크기(바이트)입니다.
[in] lpOverlapped
WSAOverlapped 구조체에 대한 포인터입니다(오버랩되지 않은 소켓의 경우 무시됨).
[in] lpCompletionRoutine
형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
송신 작업이 완료되었을 때 호출되는 완료 루틴에 대한 포인터입니다(오버랩되지 않은 소켓의 경우 무시됨).
[in] lpThreadId
WPUQueueApc에 대한 후속 호출에서 공급자가 사용할 WSATHREADID 구조체에 대한 포인터입니다. 공급자는 WPUQueueApc 함수가 반환될 때까지 참조된 WSATHREADID 구조체(동일한 포인터가 아님)를 저장해야 합니다.
[out] lpErrno
오류 코드에 대한 포인터입니다.
반환 값
오류가 발생하지 않고 수신 작업이 즉시 완료되면 LPWSPSendTo 는 0을 반환합니다. 이 경우 완료 루틴(지정된 경우)이 이미 큐에 대기 중입니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 lpErrno에서 특정 오류 코드를 사용할 수 있습니다. WSA_IO_PENDING 오류 코드는 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됨을 나타냅니다. 다른 오류 코드는 겹치는 작업이 시작되지 않았으며 완료 표시가 발생하지 않음을 나타냅니다.
| 오류 코드 | 의미 |
|---|---|
| 네트워크 하위 시스템이 실패했습니다. | |
| 요청된 주소는 브로드캐스트 주소이지만 적절한 플래그가 설정되지 않았습니다. | |
| (차단) 호출이 LPWSPCancelBlockingCall을 통해 취소되었습니다. | |
| Windows 소켓 호출 차단이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다. | |
| lpBuffers 또는 lpTo 매개 변수는 사용자 주소 공간의 일부가 아니거나 lpTo 매개 변수가 너무 작습니다. | |
| 해당 작업이 진행되는 동안 오류가 발생하여 연결이 끊겼습니다. | |
| Windows 소켓 공급자는 버퍼 교착 상태를 보고합니다. | |
| 소켓이 연결되지 않았습니다(연결 지향 소켓만 해당). | |
| 설명자가 소켓이 아닙니다. | |
| MSG_OOB 지정되었지만 소켓은 SOCK_STREAM 형식과 같은 스트림 스타일이 아니거나, OOB 데이터가 이 소켓과 연결된 통신 도메인에서 지원되지 않거나, MSG_PARTIAL 지원되지 않거나, 소켓이 단방향이며 수신 작업만 지원합니다. | |
| 소켓이 종료되었습니다. LPWSPShutdown이 SD_SEND 또는 SD_BOTH 로 설정된 방법을 사용하여 호출된 후에는 소켓에서 LPWSPSendTo를 사용할 수 없습니다. | |
| Windows NT: 겹친 소켓: 미해결 겹친 I/O 요청이 너무 많습니다. 오버랩되지 않은 소켓: 소켓이 차단 해제로 표시되고 보내기 작업을 즉시 완료할 수 없습니다. | |
| 소켓은 메시지 지향적이며 메시지는 기본 전송에서 지원하는 최대값보다 큽습니다. | |
| 소켓이 LPWSPBind에 바인딩되지 않았거나 겹치는 플래그를 사용하여 소켓이 만들어지지 않았습니다. | |
| 시간 제한 또는 기타 오류로 인해 가상 회로가 종료되었습니다. | |
| 원격 쪽에서 가상 회로를 다시 설정했습니다. | |
| 원격 주소가 유효한 주소가 아닙니다(예: ADDR_ANY). | |
| 지정된 패밀리의 주소는 이 소켓에서 사용할 수 없습니다. | |
| 대상 주소가 필요합니다. | |
| 현재 이 호스트에서 네트워크에 연결할 수 없습니다. | |
| 소켓의 닫기 또는 LPWSPIoctl에서 SIO_FLUSH 명령 실행으로 인해 겹치는 작업이 취소되었습니다. |
설명
LPWSPSendTo 함수는 일반적으로 로 지정된 연결 없는 소켓에서 하나 이상의 버퍼 에 포함된 데이터그램을 lpTo 매개 변수로 식별된 특정 피어 소켓으로 보내는 데 사용됩니다. 연결 없는 소켓이 이전에 LPWSPConnect 함수를 사용하여 특정 주소에 연결되었더라도 lpTo는 해당 특정 데이터그램의 대상 주소만 재정의합니다. 연결 지향 소켓에서 lpTo 및 iToLen 매개 변수는 무시됩니다. 이 경우 LPWSPSendTo 함수는 LPWSPSend와 동일합니다.
겹치는 소켓(플래그 WSA_FLAG_OVERLAPPED LPWSPSocket 을 사용하여 생성됨)의 경우 lpOverlapped 및 lpCompletionRoutine 이 모두 NULL 이 아니면 겹치는 I/O를 사용하여 발생합니다. 이 경우 소켓은 오버랩되지 않은 소켓으로 처리됩니다. 제공된 버퍼가 전송에서 사용된 경우 완료 표시(완료 루틴 호출 또는 이벤트 개체 설정)가 발생합니다. 작업이 즉시 완료되지 않으면 완료 루틴 또는 LPWSPGetOverlappedResult를 통해 최종 완료 상태 검색됩니다.
오버랩되지 않은 소켓의 경우 lpOverlapped, lpCompletionRoutine 및 lpThreadId 매개 변수는 무시되고 LPWSPSendTo 는 일반 동기 의미 체계를 채택합니다. 데이터는 제공된 버퍼에서 전송의 버퍼로 복사됩니다. 소켓이 차단되지 않고 스트림 지향적이며 전송 버퍼에 충분한 공간이 없는 경우 LPWSPSendTo 는 Windows 소켓 SPI 클라이언트 버퍼의 일부만 사용된 상태로 반환됩니다. 동일한 버퍼 상황과 차단 소켓을 감안할 때 LPWSPSendTo 는 모든 Windows 소켓 SPI 클라이언트의 버퍼 콘텐츠를 사용할 때까지 차단됩니다.
lpBuffers 매개 변수가 가리키는 WSABUF 구조체의 배열은 일시적입니다. 이 작업이 겹치는 방식으로 완료되면 이 호출에서 반환하기 전에 이러한 WSABUF 구조를 캡처하는 것은 서비스 공급자의 책임입니다. 이를 통해 애플리케이션은 스택 기반 WSABUF 배열을 빌드할 수 있습니다.
메시지 지향 소켓의 경우 소켓 옵션 SO_MAX_MSG_SIZE 값을 가져와 얻을 수 있는 기본 전송의 최대 메시지 크기를 초과하지 않도록 주의해야 합니다. 데이터가 기본 프로토콜을 통해 원자성으로 전달하기에 너무 긴 경우 WSAEMSGSIZE 오류가 반환되고 데이터가 전송되지 않습니다.
LPWSPSendTo가 성공적으로 완료되었다고 해서 데이터가 성공적으로 전달되었음을 의미하지는 않습니다.
iFlags 매개 변수를 사용하여 연결된 소켓에 대해 지정된 옵션을 벗어나 함수 호출의 동작에 영향을 줄 수 있습니다. 즉, 이 함수의 의미 체계는 소켓 옵션 및 dwFlags 매개 변수에 의해 결정됩니다. 후자는 다음 값과 함께 비트 OR 연산자를 사용하여 생성됩니다.
| 값 | 의미 |
|---|---|
| MSG_DONTROUTE | 데이터가 라우팅의 대상이 되어서는 안 되도록 지정합니다. Windows 소켓 서비스 공급자는 이 플래그를 무시하도록 선택할 수 있습니다. |
| MSG_OOB | OOB 데이터(SOCK_STREAM 같은 스트림 스타일 소켓만 해당)를 보냅니다. |
| MSG_PARTIAL | lpBuffers에 부분 메시지만 포함되도록 지정합니다. 오류 코드 WSAEOPNOTSUPP 는 부분 메시지 전송을 지원하지 않는 전송에 의해 반환됩니다. |
겹치는 작업이 즉시 완료되면 LPWSPSendTo 는 0 값을 반환하고 lpNumberOfBytesSent 매개 변수는 전송된 바이트 수로 업데이트됩니다. 겹치는 작업이 성공적으로 시작되고 나중에 완료될 경우 LPWSPSendTo 는 SOCKET_ERROR 반환하고 오류 코드 WSA_IO_PENDING 나타냅니다. 이 경우 lpNumberOfBytesSent 는 업데이트되지 않습니다. 겹치는 작업이 완료되면 전송되는 데이터의 양은 완료 루틴의 cbTransferred 매개 변수(지정된 경우)를 통해 또는 LPWSPGetOverlappedResult의 lpcbTransfer 매개 변수를 통해 표시됩니다.
공급자는 이전 LPWSPRecv, LPWSPRecvFrom, LPWSPSend 또는 LPWSPSendTo 함수의 완료 루틴 내에서 이 함수를 호출하도록 허용해야 합니다. 그러나 지정된 소켓의 경우 I/O 완료 루틴을 중첩할 수 없습니다. 이렇게 하면 시간이 중요한 데이터 전송이 선점 컨텍스트 내에서 완전히 발생할 수 있습니다.
lpOverlapped 매개 변수는 겹치는 작업 기간 동안 유효해야 합니다. 여러 I/O 작업이 동시에 미해결 상태이면 각각 겹치는 별도의 구조를 참조해야 합니다. WSAOverlapped 구조체는 자체 참조 페이지에 정의되어 있습니다.
lpCompletionRoutine 매개 변수가 null이면 서비스 공급자는 유효한 이벤트 개체 핸들이 포함된 경우 겹치는 작업이 완료될 때 lpOverlapped의 hEvent 멤버에 신호를 보냅니다. Windows 소켓 SPI 클라이언트는 LPWSPGetOverlappedResult 를 사용하여 이벤트 개체를 기다리거나 폴링할 수 있습니다.
lpCompletionRoutine이 null이 아닌 경우 hEvent 멤버는 무시되며 Windows Sockets SPI 클라이언트에서 컨텍스트 정보를 완료 루틴에 전달하는 데 사용할 수 있습니다. null이 아닌 lpCompletionRoutine을 전달하고 나중에 동일한 겹치는 I/O 요청에 대해 WSAGetOverlappedResult를 호출하는 클라이언트는 WSAGetOverlappedResult 호출에 대한 fWait 매개 변수를 TRUE로 설정할 수 없습니다. 이 경우 hEvent 멤버의 사용은 정의되지 않으며 hEvent 멤버를 기다리려고 하면 예측할 수 없는 결과가 생성됩니다.
겹치는 작업이 완료될 때 지정된 클라이언트 호출-완료 루틴을 정렬하는 것은 서비스 공급자의 책임입니다. 겹치는 작업을 시작한 동일한 스레드의 컨텍스트에서 완료 루틴을 실행해야 하므로 서비스 공급자에서 직접 호출할 수 없습니다. 이 Ws2_32.dll 완료 루틴을 쉽게 호출할 수 있도록 APC(비동기 프로시저 호출) 메커니즘을 제공합니다.
서비스 공급자는 WPUQueueApc를 호출하여 함수가 적절한 스레드에서 실행되도록 정렬합니다. 이 함수는 겹치는 작업을 시작하는 데 사용된 스레드 및 프로세스와 다른 컨텍스트라도 모든 프로세스 및 스레드 컨텍스트에서 호출할 수 있습니다.
WPUQueueApc 함수는 WSATHREADID 구조체에 대한 포인터(lpThreadId 입력 매개 변수를 통해 공급자에게 제공됨), 호출할 APC 함수에 대한 포인터 및 이후에 APC 함수에 전달되는 컨텍스트 값을 입력 매개 변수로 사용합니다. 단일 컨텍스트 값만 사용할 수 있으므로 APC 함수 자체는 클라이언트가 지정한 완료 루틴이 될 수 없습니다. 대신 서비스 공급자는 제공된 컨텍스트 값을 사용하여 겹치는 작업에 필요한 결과 정보에 액세스한 다음 지정된 클라이언트 완료 루틴을 호출하는 자체 APC 함수에 대한 포인터를 제공해야 합니다.
클라이언트에서 제공하는 완료 루틴의 프로토타입은 다음과 같습니다.
void CALLBACK
CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine은 클라이언트에서 제공하는 함수 이름의 자리 표시자입니다. dwError는 lpOverlapped에 표시된 대로 겹치는 작업에 대한 완료 상태 지정합니다. cbTransferred는 전송된 바이트 수를 지정합니다. 현재 정의된 플래그 값이 없으며 dwFlags 값은 0입니다. 이 함수는 값을 반환하지 않습니다.
겹치는 작업이 완료된 순서와 동일한 순서로 반드시 호출되는 것은 아니지만 완료 루틴을 순서대로 호출할 수 있습니다. 그러나 서비스 공급자는 게시된 버퍼가 제공된 것과 동일한 순서로 전송되도록 클라이언트에 보장합니다.
참고
지정된 스레드에서 시작된 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread 를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 머리글 | ws2spi.h |