WSAAsyncGetHostByName 함수(winsock2.h)

아티클
08/27/2023

WSAAsyncGetHostByName 함수는 호스트 이름에 해당하는 호스트 정보를 비동기적으로 검색합니다.

참고WSAAsyncGetHostByName 함수는 여러 이름의 병렬 확인을 제공하도록 설계되지 않았습니다. 따라서 여러 요청을 실행하는 애플리케이션은 동시에 실행될 것으로 예상해서는 안 됩니다. 또는 애플리케이션은 다른 스레드를 시작하고 getaddrinfo 함수를 사용하여 IP 버전에 구애받지 않은 방식으로 이름을 resolve 수 있습니다. Windows Sockets 2 애플리케이션을 만드는 개발자는 getaddrinfo 함수를 사용하여 IPv6 호환성으로 원활하게 전환할 것을 촉구합니다.

구문

HANDLE WSAAPI WSAAsyncGetHostByName(
  HWND       hWnd,
  u_int      wMsg,
  const char *name,
  char       *buf,
  int        buflen
);

매개 변수

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

반환 값

반환 값은 비동기 작업이 성공적으로 시작되었는지 여부를 지정합니다. 이는 작업 자체의 성공 또는 실패를 의미하지는 않습니다.

오류가 발생하지 않으면 WSAAsyncGetHostByName 은 요청에 대해 비동기 작업 핸들(Windows HTASK와 혼동하지 않음)인 HANDLE 형식의 0이 아닌 값을 반환합니다. 이 값은 두 가지 방법으로 사용할 수 있습니다. WSACancelAsyncRequest를 사용하여 작업을 취소하거나 wParam 메시지 매개 변수를 검사하여 비동기 작업 및 완료 메시지를 일치시키는 데 사용할 수 있습니다.

비동기 작업을 시작할 수 없는 경우 WSAAsyncGetHostByName 은 0 값을 반환하고 WSAGetLastError를 호출하여 특정 오류 번호를 검색할 수 있습니다.

애플리케이션 창에서 메시지를 받을 때 다음 오류 코드를 설정할 수 있습니다. 위에서 설명한 대로 WSAGETASYNCERROR 매크로를 사용하여 회신 메시지의 lParam 에서 추출할 수 있습니다.

오류 코드	의미
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAENOBUFS	버퍼 공간이 부족합니다.
WSAEFAULT	이름 또는 buf 매개 변수가 프로세스 주소 공간의 유효한 부분에 있지 않습니다.
WSAHOST_NOT_FOUND	신뢰할 수 있는 응답 호스트를 찾을 수 없습니다.
WSATRY_AGAIN	인증되지 않은 호스트를 찾을 수 없거나 SERVERFAIL입니다.
WSANO_RECOVERY	복구할 수 없는 오류: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	유효한 이름이며 요청된 형식의 데이터 레코드가 없습니다.

다음 오류는 함수 호출 시 발생할 수 있으며 비동기 작업을 시작할 수 없음을 나타냅니다.

오류 코드	의미
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAEINPROGRESS	차단 Windows Sockets 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEWOULDBLOCK	현재는 Windows 소켓 구현 내의 리소스 또는 기타 제약 조건으로 인해 비동기 작업을 예약할 수 없습니다.

설명

WSAAsyncGetHostByName 함수는 gethostbyname의 비동기 버전이며 호스트 이름에 해당하는 호스트 이름 및 주소 정보를 검색하는 데 사용됩니다. Windows 소켓은 작업을 시작하고 호출자에게 즉시 반환하여 애플리케이션이 작업을 식별하는 데 사용할 수 있는 불투명 비동기 작업 핸들을 다시 전달합니다. 작업이 완료되면 결과(있는 경우)가 호출자가 제공하는 버퍼에 복사되고 메시지가 애플리케이션의 창으로 전송됩니다.

비동기 작업이 완료되면 hWnd 매개 변수로 표시된 애플리케이션 창이 wMsg 매개 변수의 메시지를 받습니다. wParam 매개 변수는 원래 함수 호출에서 반환된 비동기 작업 핸들을 포함합니다. lParam의 상위 16비트에는 오류 코드가 포함되어 있습니다. 오류 코드는 Winsock2.h에 정의된 오류일 수 있습니다. 오류 코드가 0이면 비동기 작업이 성공적으로 완료되었음을 나타냅니다.

성공적으로 완료되면 원래 함수 호출에 지정된 버퍼에 호스트 구조가 포함됩니다. 이 구조체의 요소에 액세스하려면 원래 버퍼 주소를 호스트 구조 포인터로 캐스팅하고 적절하게 액세스해야 합니다.

오류 코드가 WSAENOBUFS인 경우 원래 호출에서 buflen 에 의해 지정된 버퍼의 크기가 너무 작아서 모든 결과 정보를 포함할 수 없습니다. 이 경우 lParam 의 하위 16비트에는 모든 필수 정보를 제공하는 데 필요한 버퍼 크기가 포함됩니다. 애플리케이션에서 부분 데이터가 부적절하다고 판단되면 원하는 모든 정보를 받을 수 있을 만큼 큰 버퍼를 사용하여 WSAAsyncGetHostByName 함수 호출을 다시 실행할 수 있습니다(즉, lParam의 낮은 16비트보다 작지 않음).

이 함수에 지정된 버퍼는 Windows 소켓에서 동일한 호스트 구조의 멤버가 참조하는 데이터 영역의 내용과 함께 호스트 구조를 생성하는 데 사용됩니다. WSAENOBUFS 오류를 방지하려면 애플리케이션이 WINSock2.h에 정의된 대로 최소 MAXGETHOSTSTRUCT 바이트 버퍼를 제공해야 합니다.

오류 코드 및 버퍼 길이는 Winsock2.h에 다음과 같이 정의된 WSAGETASYNCERROR 및 WSAGETASYNCBUFLEN 매크로를 사용하여 lParam에서 추출해야 합니다.

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

이러한 매크로를 사용하면 애플리케이션에 대한 소스 코드의 이식성을 최대화할 수 있습니다.

WSAAsyncGetHostByName은 gethostname을 성공적으로 호출하여 반환된 문자열을 resolve 보장됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	winsock2.h(Winsock2.h, Winsock.h 포함)
라이브러리	Ws2_32.lib
DLL	Ws2_32.dll