WSAAsyncGetServByPort 함수(winsock2.h)
WSAAsyncGetServByPort 함수는 포트 및 프로토콜에 해당하는 서비스 정보를 비동기적으로 검색합니다.
구문
HANDLE WSAAPI WSAAsyncGetServByPort(
[in] HWND hWnd,
[in] u_int wMsg,
[in] int port,
[in] const char *proto,
[out] char *buf,
[in] int buflen
);
매개 변수
[in] hWnd
비동기 요청이 완료될 때 메시지를 받아야 하는 창의 핸들입니다.
[in] wMsg
비동기 요청이 완료될 때 받을 메시지입니다.
[in] port
서비스 포트(네트워크 바이트 순서)입니다.
[in] proto
프로토콜 이름에 대한 포인터입니다. NULL일 수 있습니다. 이 경우 WSAAsyncGetServByPort는 지정된 포트와 일치하는 s_port 첫 번째 서비스 항목을 검색합니다. 그렇지 않으면 WSAAsyncGetServByPort 가 포트 와 proto를 모두 일치합니다.
[out] buf
서비스 데이터를 수신할 데이터 영역에 대한 포인터 입니다 . 데이터 영역은 서브트 구조체와 서브트 구조체의 멤버가 참조하는 모든 데이터를 포함하기 위해 Windows Sockets에서 사용 되므로 서비스 구조체의 크기보다 커야 합니다. MAXGETHOSTSTRUCT 바이트의 버퍼를 사용하는 것이 좋습니다.
[in] buflen
buf 매개 변수의 데이터 영역 크기(바이트)입니다.
반환 값
반환 값은 비동기 작업이 성공적으로 시작되었는지 여부를 지정합니다. 이는 작업 자체의 성공 또는 실패를 의미하지는 않습니다.
오류가 발생하지 않으면 WSAAsyncGetServByPort 는 요청에 대한 비동기 작업 핸들인 HANDLE 형식의 0이 아닌 값을 반환합니다(Windows HTASK와 혼동하지 않음). 이 값은 두 가지 방법으로 사용할 수 있습니다. WSACancelAsyncRequest를 사용하여 작업을 취소하거나 wParam 메시지 매개 변수를 검사하여 비동기 작업 및 완료 메시지를 일치시키는 데 사용할 수 있습니다.
비동기 작업을 시작할 수 없는 경우 WSAAsyncGetServByPort 는 0 값을 반환하고 WSAGetLastError를 호출하여 특정 오류 번호를 검색할 수 있습니다.
애플리케이션 창에서 메시지를 받을 때 다음 오류 코드를 설정할 수 있습니다. 위에서 설명한 대로 WSAGETASYNCERROR 매크로를 사용하여 회신 메시지의 lParam에서 추출할 수 있습니다.
| 오류 코드 | 의미 |
|---|---|
| 네트워크 하위 시스템이 실패했습니다. | |
| 버퍼 공간이 부족합니다. | |
| proto 또는 buf 매개 변수가 프로세스 주소 공간의 유효한 부분에 있지 않습니다. | |
| 신뢰할 수 있는 응답 포트를 찾을 수 없습니다. | |
| 인증되지 않은 포트를 찾을 수 없거나 서버 오류가 발생했습니다. | |
| 복구할 수 없는 오류, 서비스 데이터베이스에 액세스할 수 없습니다. | |
| 유효한 이름이며 요청된 형식의 데이터 레코드가 없습니다. |
다음 오류는 함수 호출 시 발생할 수 있으며 비동기 작업을 시작할 수 없음을 나타냅니다.
| 오류 코드 | 의미 |
|---|---|
| WSANOTINITIALISED | 이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다. |
| WSAENETDOWN | 네트워크 하위 시스템이 실패했습니다. |
| WSAEINPROGRESS | 차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다. |
| WSAEWOULDBLOCK | 현재는 Windows 소켓 구현 내의 리소스 또는 기타 제약 조건으로 인해 비동기 작업을 예약할 수 없습니다. |
설명
WSAAsyncGetServByPort 함수는 getservbyport의 비동기 버전이며 포트 번호에 해당하는 서비스 정보를 검색하는 데 사용됩니다. Windows 소켓은 작업을 시작하고 호출자에게 즉시 반환하여 애플리케이션이 작업을 식별하는 데 사용할 수 있는 불투명하고 비동기적인 작업 핸들을 다시 전달합니다. 작업이 완료되면 결과(있는 경우)가 호출자가 제공하는 버퍼에 복사되고 메시지가 애플리케이션의 창으로 전송됩니다.
비동기 작업이 완료되면 hWnd 매개 변수로 표시된 애플리케이션 창이 wMsg 매개 변수의 메시지를 받습니다. wParam 매개 변수에는 원래 함수 호출에서 반환된 비동기 작업 핸들이 포함됩니다. lParam의 상위 16비트에는 오류 코드가 포함되어 있습니다. 오류 코드는 Winsock2.h에 정의된 오류일 수 있습니다. 오류 코드가 0이면 비동기 작업이 성공적으로 완료되었음을 나타냅니다.
성공적으로 완료되면 원래 함수 호출에 지정된 버퍼에 servent 구조가 포함됩니다. 이 구조체의 멤버에 액세스하려면 원래 버퍼 주소를 서브트 구조 포인터로 캐스팅하고 적절하게 액세스해야 합니다.
오류 코드가 WSAENOBUFS인 경우 원래 호출에서 buflen 에 의해 지정된 버퍼의 크기가 너무 작아서 모든 결과 정보를 포함할 수 없습니다. 이 경우 lParam 의 하위 16비트에는 모든 필수 정보를 제공하는 데 필요한 버퍼 크기가 포함됩니다. 애플리케이션에서 부분 데이터가 적합하지 않다고 판단하는 경우 원하는 모든 정보를 받을 수 있을 만큼 큰 버퍼를 사용하여 WSAAsyncGetServByPort 함수 호출을 다시 실행할 수 있습니다(즉, lParam의 낮은 16비트보다 작지 않음).
이 함수에 지정된 버퍼는 Windows Sockets에서 동일한 서브트 구조의 멤버가 참조하는 데이터 영역의 내용과 함께 서브트 구조를 생성하는 데 사용됩니다. WSAENOBUFS 오류를 방지하려면 애플리케이션에서 최소 MAXGETHOSTSTRUCT 바이트(Winsock2.h에 정의된 대로)의 버퍼를 제공해야 합니다.
오류 코드 및 버퍼 길이는 Winsock2.h에 다음과 같이 정의된 WSAGETASYNCERROR 및 WSAGETASYNCBUFLEN 매크로를 사용하여 lParam에서 추출되어야 합니다.
#include <windows.h>
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
이러한 매크로를 사용하면 애플리케이션에 대한 소스 코드의 이식성을 최대화할 수 있습니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | winsock2.h(Winsock2.h 포함) |
| 라이브러리 | Ws2_32.lib |
| DLL | Ws2_32.dll |