WSAAsyncGetHostByAddr

WSAAsyncGetHostByAddr

WSAAsyncGetHostByAddr 함수는 지정된 주소에 일치하는 호스트 정보를 비동기적으로 얻어내는 함수입니다.

HANDLE WSAAsyncGetHostByAddr (
        HWND   hWnd,
        unsigned int   wMsg,
        const char FAR *   addr,
        int   len,
        int   type,
        char FAR * buf,
        int   buflen
);

Parameters

hWnd
[입력] 비동기 작업 요청이 완료 되었을 때 메시지를 받을 윈도우의 핸들

wMsg
[입력] 비동기 작업 요청이 완료 되었을 때 수신하기위한 메시지

addr
[입력] 얻고자 하는 호스트에 대한 네트웍 어드레스에 대한 포인터입니다. 호스트 어드레스는 네트웍 바이트 오더(빅-인디언) 으로 저장됩니다.

len
[입력] 어드레스의 길이

type
[입력] 어드레스의 형태

buf
[출력] HOSTENT 데이터를 받기위한 데이터 영역의 포인터입니다. 이 데이터 영역은 HOSTENT 구조체보다 더 커야 합니다. 왜냐하면, 제공되는 데이터 영역은 HOSTENT 구조체와 HOSTENT 구조체의 모든 멤버 데이터 참조를 포함하기 위해 윈도우즈 소켓 시스템에서 사용되기 때문입니다. 즉, 제공된 버퍼가 데이터 베이스 룩업의 결과로서 만들어진 모든 데이터를 수신하기에 너무 짧을 경우 에러가 반환될 것입니다. 에러를 방지 하기 위해서 어플리케이션은 최소한 MAXGETHOSTSTRUCT 바이트 길이의 버퍼를 제공해야 합니다.

buflen
[입력] buf 매개변수의 크기를 나타냅니다.

Remarks

WSAAsyncGetHostByAddr 함수는 gethostbyaddr 함수의 비동기 버전이라고 생각하시면 됩니다. 이 함수는 지정되 네트웍 어드레스와 일치하는 어드레스 정보와 호스트네임을 얻고자 하는데 사용됩니다. 윈도우즈 소켓은 연산을 시작하고, 즉각 함수를 반환 하고, 어플리케이션은 비동기 작업(task) 식별자를 사용할 수 있습니다. 연산(operation)이 완료 되었을 때, 작업의 결과가 함수 호출시 지정했던 버퍼로 복사되고, 메시지가 어플리케이션 윈도우로 보내어 집니다.

비동기 연산이 완료 되었을 때, hWnd 매개변수로 지정된 어플리케이션 윈도우는 wMsg 매개변수로 지정된 메시지를 받습니다. wParam 매개변수는 원래 함수호출에 의해 반환된 비동기 작업(task) 핸들을 포함하고 있습니다. lParam 의 상위 16비트는 에러코드를 가지고 있습니다. 에러코드는 WINSOCK(2).H 헤더파일에 정의된 에러코드가 될 수 있습니다. 에러코드가 0 이면, 비동기 연산(operation)이 성공적으로 완료되었음을 가리킵니다.

성공적인 함수의 완료시, 함수 호출시 지정된 버퍼에는 HOSTENT 구조체를 가지고 있습니다. 이 구조체의 멤버에 접근하기 위해서는 원래 버퍼 메모리 주소를 HOSTENT 구조체의 포인터로 캐스팅 하고 적절히 접근 하면 됩니다.

만약 에러코드가 WSAENOBUFS 라면, buflen으로 지정된 버퍼의 크기가 모든 얻어낸 정보를 담기에 너무 작은 경우입니다. 이런 경우 lParam의 하위 16비트는 모든 정보를 수용할 수 있는 버퍼의 크기가 얼마인지 알려주게 됩니다. 만약 어플리케이션이 "이까짖 일부분 데이터는 필요없어!" 라고 판단한다면, 모든 정보를 받기에 충분한 크기로 버퍼를 셋팅하여 WSAAsyncGetHostByAddr 함수를 다시 호출 할 수 있습니다.

WSAENOBUFS 에러를 피하기 위해서 어플리케이션은 적어도 MAXGETHOSTSTRUCT 바이트(WINSOCK(2).H 에 정의되어 있음) 의 버퍼를 제공해야 합니다.

에러코드와 버퍼 길이는 WINSOCK2.H 파일에 정의된 WSAGETASYNCERROR 와 WSAGETASYNCBUFLEN 매크로를 사용해서 lParam 으로부터 뽑아낼 수 있습니다. 아래에 이 매크로에 대해서 간단히 나열해 보았습니다. 참고 하세요. 프로그램시 이들 매크로를 사용함으로써 윈도우즈 소켓 코드의 이식성(portability)을 향상 시킬 수 있다고 하네요.

#define WSAGETASYNCERROR(lParam) HIWORD(lParam) //에러코드 검색
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam) //필요한 버퍼의 길이 검색

Return Values

반환값은 단지 비동기 연산이 성공적으로 시작하느냐 그렇지 않느냐를 나타냅니다. 이러한 비동기 연산의 경우 반환값으로 연산 자체의 성공이냐 실패냐를 결정할 순 없습니다.

에러가 발생하지 않은 경우, WSAAsyncGetHostByAddr 함수는 비동기 작업(task) 핸들(윈도우즈의 HTASK 과 헷갈리지 마세요)인 HANDLE 타입을 반환 합니다. 이 핸들값은 두가지 방법으로 사용될 수 있습니다. 첫 번째는 WSACancelAsyncRequest 함수를 호출하여 연산을 취소 시키는데 사용할 수 있고, 비동기 연산과 wParam 메시지 매개변수인 완료 메시지와 맞추어 보는데 사용될 수 있습니다.

만약 비동기 연산이 시작될 수 없었다면, WSAAsyncGetHostByAddr 함수는 0을 리턴하고, WSAGetLastError 함수를 이용하여 특정한 에러코드를 얻어낼 수 있습니다.

Error Codes

아래의 에러코드는 어플리케이션 윈도우가 메시지를 받았을 때 설정될 수 있습니다. 앞서 설명 했듯이, WSAGETASYNCERROR 매크로를 이용해서 응답 메시지인 lParam으로부터 에러코드를 뽑아낼 수 있습니다.

WSAENETDOWN	네트웍 서브 시스템에서 에러가 발생 했습니다.
WSAENOBUFS	사용가능한 버퍼 공간이 부족합니다.
WSAEFAULT	addr 또는 buf 매개변수가 처리를 하기에 올바를 형태가 아닙니다.
WSAHOST_NOT_FOUND	정당한(Authoritative) 호스트를 찾아낼 수 없습니다.
WSATRY_AGAIN	정당하지 않은(Non-Authoritative)를 찾을 수 없습니다. 또는 서버실패 입니다.
WSANO_RECOVERY	회복할 수 없는 에러발생
WSANO_DATA	요청된 type(어드레스의 형태)를 찾을 수 없거나 잘못된 이름(name)입니다.

아래의 에러코드는 본 함수를 호출 했을 때 발생될 수 있는 에러코드입니다. 그리고, 이러한 에러코드가 검출 되었을 때 비동기 연산은 시작 될 수 없다는 것을 의미합니다.

WSANOTINITIALISED	이 함수를 사용하기 이전에 WSAStartup 함수를 성공적으로 호출해야 합니다.
WSAENETDOWN	네트웍 서브 시스템에서 에러가 났습니다.
WSAEINPROGRESS	블럭킹 윈속 v1.1이 진행상태에 있거나, 서비스 프로바이더가 아직 콜백함수를 진행하고 있습니다.
WSAEWOULDBLOCK	비동기 연산이 리소스나 다른 반대적인 요소들 때문에 진행될 수 없습니다.

QuickInfo

Windows NT : 사용가능
Windows : 사용가능
Windows CE : 버젼 1.0 그리고 그이후의 버젼에서 사용가능
Header :
          Win16/32 : winsock.h
          Win32-II : winsock2.h
Import Library :
         Win16 : winsock.lib
          Win32 : wsock32.lib
          Win32-II : ws2_32.lib

See Also