WSAAsyncGetHostByName 매크로(wsipv6ok.h)

아티클
08/28/2023

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

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

구문

void WSAAsyncGetHostByName(
  [in]   a,
  [in]   b,
  [in]   c,
  [out]  d,
  [in]   e
);

매개 변수

[in] a

비동기 요청이 완료될 때 메시지를 받을 창의 핸들입니다.

[in] b

비동기 요청이 완료될 때 받을 메시지입니다.

[in] c

호스트의 null로 종료된 이름에 대한 포인터입니다.

[out] d

호스트 데이터를 받을 데이터 영역에 대한 포인터 입니다 . 지정된 데이터 영역은 호스트 구조체 및 호스트 구조의 멤버가 참조하는 모든 데이터를 포함하기 위해 Windows Sockets에서 사용되므로 데이터 영역은 호스트 구조의 크기보다 커야 합니다. MAXGETHOSTSTRUCT 바이트의 버퍼를 사용하는 것이 좋습니다.

[in] e

buf 매개 변수의 데이터 영역 크기(바이트)입니다.

반환 값

없음

설명

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

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

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

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

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

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

요구 사항

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