WSAAsyncGetHostByName
WSAAsyncGetHostByName 함수는 지정된 호스트 이름과 일치하는 호스트 정보를 비동기적으로 얻어내는 함수 입니다.
HANDLE WSAAsyncGetHostByName (
HWND hWnd,
unsigned int wMsg,
const char FAR * name,
char FAR * buf,
int buflen
);
Parameters
hWnd
[입력]
비동기적인 요청이 완료되었을 때 메시지를 수신할 윈도우의 핸들
wMsg
[입력]
비동기적인 요청작업이 완료되었을 때 수신될 메시지
name
[입력]
널 문자로 끝나는 호스트 이름
buf
[출력]
HOSTENT
데이터를 수신하기 위한 데이터 영역의 포인터입니다. 이 데이터 영역은 HOSTENT
구조체의 크기보다 더 커야 합니다. 왜냐하면, 얻어지는 데이터 영역은 HOSTENT
구조체와 HOSTENT
구조체의 모든 멤버를 포함하기위하여 윈도우즈 소켓 시스템이 사용하기 때문입니다.
일반적으로 버퍼의 크기로 MAXGETHOSTSTRUCT를 사용합니다.
buflen
[입력]
buf
매개변수를 위한 데이터 영역의 크기를 명시 합니다.
Remarks
WSAAsyncGetHostByName 함수는 gethostbyname 함수의 비동기 버전입니다. 이 함수는 지정된 호스트 이름과 일치하는 어드레스 정보를 얻어내기 위해서 사용됩니다. 윈도우즈 소켓 시스템은 연산을 시작하고, 함수는 바로 반환되고, 보이지 않게 백으로 연산을 수행합니다. "비동기 작업 핸들(asynchronous task handle)" 은 어플리케이션에서 연사의 식별자로 사용 할 수 있습니다. 연산(operation)이 완료 되었을 때 그 결과는 함수의 매개변수로 지정한 버퍼에 카피되고, 메시지는 어플리케이션 윈도우로 전달 됩니다.
비동기적인 연산이 완료 되었을 때 hWnd 매개변수로 지정된 어플리케이션 윈도우는 wMsg 매개변수인 메시지를 받게 됩니다. wParam 매개변수는 비동기 작업(task) 핸들을 가지는 매개변수입니다. lParam의 상위 16비트는 에러코드를 가지고 있습니다. 에러코드는 WINSOCK(2).H 헤더 파일에 정의된 에러코드가 될 수 있습니다. 에러코드가 0 일 경우 비동기 연산(operation)의 성공적인 완료를 의미합니다.
성공적인 완료시에 함수호출시에 지정한 버퍼는 HOSTENT 구조체를 가집니다. 이 구조체의 멤버를 접근하기위해서는 원래 버퍼 메모리 주소를 HOSTENT 구조체의 포인터로 캐스팅 하고나서 접근 할 수 있습니다.
만약 에러코드가 WSAENOBUFS 일 경우 buflen 매개변수에 의해서 지정된 버퍼의 크기가 결과로 얻은 정보를 담기에 너무 작다는 것을 의미합니다. 이런 경우 lParam 의 하위 16비트는 정보를 담기위해 필요한 버퍼의 크기를 나타내게 됩니다. 만약 어플리케이션이 이렇게 얻은 일부분 데이터가 필요없는 데이터라면, 원하는 정보를 담기위해서 충분한 버퍼의 크기를 설정하고 WSAAsyncGetHostByName 함수를 다시 호출 할 수 있습니다.
이 함수를 위하여 지정된 버퍼는 HOSTENT 구조체의 멤버에 의해서 참조되는 데이터 영역과 함께 HOSTENT 구조체를 구성하기위해 윈도우즈 소켓 시스템에서 사용됩니다. WSAENOBUFS 에러를 피하기 위해서는 어플리케이션에서 버퍼의 크기를 적어도 MAXGETHOSTSTRUCT(WINSOCK(2).H 헤더파일에 정의됨) 바이트의 크기만큼을 지정해야 합니다.
에러코드 그리고 버퍼의 길이는 lParam 으로부터 뽑아내야 합니다. 이 데이터를 뽑아내는데는 WINSOCK(2).H 헤더파일에 정의된 WSAGETASYNCERROR 매크로와 WSAGETASYNCBUFLEN 매크로가 사용됩니다. 아래에 이들 매크로를 간단히 나열 해 보았습니다. 프로그램시 이들 매크로를 사용함으로써 윈도우즈 소켓 코드의 이식성(portability)을 향상 시킬 수 있다고 하네요.
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
//에러코드 검색
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
//필요한 버퍼의 길이 검색
Return Values
반환값은 단지 비동기 연산이 성공적으로 시작하느냐 그렇지 않느냐를 나타냅니다. 이러한 비동기 연산의 경우 반환값으로 연산 자체의 성공이냐 실패냐를 결정할 순 없습니다.
에러가 발생하지 않은 경우, WSAAsyncGetHostByName 함수는 비동기 작업(task) 핸들(윈도우즈의 HTASK 과 헷갈리지 마세요)인 HANDLE 타입을 반환 합니다. 이 핸들값은 두가지 방법으로 사용될 수 있습니다. 첫 번째는 WSACancelAsyncRequest 함수를 호출하여 연산을 취소 시키는데 사용할 수 있고, 비동기 연산과 wParam 메시지 매개변수인 완료 메시지와 맞추어 보는데 사용될 수 있습니다.
만약 비동기 연산이 시작될 수 없었다면, WSAAsyncGetHostByName 함수는 0을 리턴하고, WSAGetLastError 함수를 이용하여 특정한 에러코드를 얻어낼 수 있습니다.
Error Codes
아래의 에러코드는 어플리케이션 윈도우가 메시지를 받았을 때 설정될 수 있습니다. 앞서 설명 했듯이, WSAGETASYNCERROR 매크로를 이용해서 응답 메시지인 lParam으로부터 에러코드를 뽑아낼 수 있다는거져.
| WSAENETDOWN | 네트웍 서브 시스템에서 에러가 발생
했습니다. |
| WSAENOBUFS | 사용가능한 버퍼 공간이 부족합니다. |
| WSAEFAULT | name
또는 buf
매개변수가 처리를 하기에 올바를 형태가 아닙니다. |
| WSAHOST_NOT_FOUND | 정당한(Authoritative) 호스트를 찾아낼 수 없습니다. |
| WSATRY_AGAIN | 정당하지 않은(Non-Authoritative)를 찾을 수 없습니다. 또는 서버실패 입니다. |
| WSANO_RECOVERY | 회복할 수 없는 에러발생 |
| WSANO_DATA | 잘못된 이름(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