WSAAsyncGetServByName
WSAAsyncGetServByName 함수는 지정된 서비스 이름, 프로토콜과 부합하는 서비스 정보를 반환하는 함수 입니다.
HANDLE WSAAsyncGetServByName (
HWND hWnd,
unsigned int wMsg,
const char FAR * name,
const char FAR * proto,
char FAR *
buf,
int buflen
);
Parameters
hWnd
[입력] 비동기 작업이 완료 되었을
때 메시지를 수신받을 윈도우의 핸들
wMsg
[입력] 비동기 작업이 완료 되었을
때 수신받을 메세지
name
[입력] null
문자로 끝나는 서비스 이름 스트링
proto
[입력] 프로토콜
이름에 대한 포인터. 이 값은 WSAAsyncGetServByName
함수가 주어진 name과 일치하는 s_name이나 s_aliases에 대해서
첫 번째 서비스 엔트리만을 검색할 경우 NULL이 될 수 있습니다. 그렇지 않은 경우
즉, proto가 NULL이 아닌경우 WSAAsyncGetServByName
함수는 name 과 proto 양쪽 모두와 일치하는 서비스 정보를 반환하게
됩니다.
buf
[출력] SERVENT
데이터를 수신하기 위한 데이터 영역 포인터. 이 데이터영역은 SERVENT
구조체의 크기보다 더 커야 합니다. 왜냐믄, 이 데이터 영역을 윈도즈 소켓이 SERVENT
구조체와 SERVENT 구조체의 멤버를 참조하는 데이터 전부를 포함해야 하기 때문입니다.
구래서 보통 MAXGETHOSTSTRUCT 바이트 만큼의 버퍼를 주로 사용합니다.
buflen
[입력] buf 매개변수에 대한 데이터 영역의 크기
Remarks
WSAAsyncGetServByName 함수는 getservbyname 함수의 비동기 버전이라 할 수 있습니다. 즉, 지정된 서비스 이름과 부합하는 서비스 정보를 반환하는데 사용되는 함수입니다. 함수를 콜하게 되면, 바로 비동기 연산이 시작되게 되고 비동기 연산은 빽~ 으로 눈에 보이지 않게(?) 동작하게 됩니다. 이 비동기 연산에 대한 태스크 핸들이 본 함수의 리턴값으로 넘어오게 되는데 어플리케이션에서는 이 태스크 핸들을 사용 할 수 있습니다. 비동기 연산이 완료 되었을 때 그 결과는 함수의 호출지 제공되었던 buffer로 카피되고 어플리케이션 윈도우로 메시지가 보내지게 됩니다.
비동기 연산이 완료되었을 때, hWnd로 지정되었던 어플리케이션 윈도우는 wMsg로 지정되었던 메시지를 수신하게 됩니다. wParam 매개변수는 이전에 함수를 호출할 때 리턴되었던 핸들과 같은 비동기 태스크 핸들을 가지고 있습니다. lParam의 상위 16비트는 특정한 에러코드를 가지고 있는데, 이 에러코드는 WINSOCK(2).H에 정의된 특정한 에러코드가 될 수 있습니다. 만약 이 lParam의 상위 16비트인 에러코드가 0일 경우 비동기 연산은 성공했다고 볼 수 있습니다.
성공적인 수행 후에, 함수호출시 제공되었던 buffer는 SERVENT 구조체를 가지게 됩니다. 이 구조체의 멤버를 접근하려면, 먼저 buffer 어드레스를 SERVENT 구조체로 캐스팅하고, 멤버를 접근하면 됩니다.
만약 WSAENOBUFS 에러코드가 발생한 경우 함수의 호출시 넘겨주었던 buflen의 크기인 buffer가 모든 정보를 담기에 너무작은 경우입니다. 이런 경우 lParam의 하위 16비트는 모든 정보를 담기에 충분한 버퍼의 크기를 가르쳐 주게 되죠. 즉, lParam의 하위 16비트 크기만큼의 버퍼를 할당해야지만, 정상적인 정보를 얻어낼 수 있다는 의미입니다.
lParam에 포함되어 있는 에러코드와 버퍼의 길이는 WSAGETASYNCERROR 과 WSAGETASYNCBUFLEN 매크로를 이용해서 뽑아낼 수도 있습니다.
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
//에러코드 검색
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
//필요한 버퍼의 길이 검색
이러한 매크로를 이용하면, 코드의 이식성이 좋아진다고 합니다.
Return Values
리턴값은 비동기적인 연산이 성공했든 아니든간에 반환됩니다. 이 리턴값 그자체로는 연산이 정상적으로 수행되었는지 아닌지를 결정할 수는 없습니다.
만약 아무런 에러가 발생하지 않았다면, WSAAsyncGetProtoByNumber 함수는 0이 아닌 비동기 태스크 핸들을 반환 합니다(윈도즈 HTASK와 헷갈리지 마세요). 이 비동기 태스크 핸들은 두가지 용도로 사용될 수 있습니다. 첫 번째로 WSACancelAsyncRequest 함수에 사용해서 작업중이 연산을 중지 시킬 수 있고, 두 번째로 연산이 완료되었을 때 메시지를 받는 루틴에서 wParam과, 이 비동기 태스크 핸들을 비교해서 어떤 작업의 완료 메시지 인지를 비교해서 추출해 낼 수 도 있는거죠.
만약 비동기 연산이 초기화되고 시작되지 못했다면, 이 함수는 0값을 반환 하고, WSAGetLastError 함수를 이용해서 특정한 에러코드를 반환 할 수 있습니다.
Error Codes
아래의 에러코드는 어플리케이션 윈도우가 메시지를 받았을 때 얻어낼 수 있는 에러코드입니다. 다시말하면, 수신된 메시지중 lParam 매개변수를 WSAGETASYNCERROR 매크로를 사용해서 뽑아낼 수 있는 값입니다.
| 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 : 지원되지 않음
Header
:
Win16/32
: winsock.h
Win32-II
: winsock2.h
Import Library :
Win16 : winsock.lib
Win32
: wsock32.lib
Win32-II
: ws2_32.lib