WSAAsyncGetServByPort

WSAAsyncGetServByPort 함수는 지정된 포트와 프로토콜과 부합하는 서비스 정보를 얻어내는 함수입니다.

HANDLE WSAAsyncGetServByPort (
            HWND   hWnd,
            unsigned int   wMsg,
            int   port,
            const char FAR *   proto,
            char FAR *   buf,
            int   buflen
);

 

Parameters

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

wMsg
[입력] 비동기 작업이 완료 되었을 때 수신받을 메시지

port
[입력] 서비스 포트번호, 네트웍 바이트 오더로 넘겨 줍니다.

proto
[입력] 프로토콜 이름에 대한 포인터를 넘겨줍니다. 이값은 port 매개변수 하나로만, 서비스 정보를 얻고자 할 때, NULL이 될 수 있습니다. 만약 proto 매개변수를 NULL이 아닌 값으로 넘겨주에 되면, WSAAsyncGetServByPort 함수는 port와 proto 양쪽다 일치하는 서비스 정보를 반환 하게 됩니다.

buf
[출력] SERVENT 데이터를 수신받을 데이터 영역에 대한 포인터. 이 데이터 영역은 SERVENT 구조체의 크기보다 더 커야 합니다. 왜냐믄, 넘겨준 데이터 영역은 SERVENT구조체와 그외 모든 데이터를 가지도록 윈도즈 소켓이 사용하기 때문입니다. 일반적으로 MAXGETHOSTSTRUCT 바이트 크기의 버퍼를 사용합니다.

buflen
[입력] buf 매개변수에 대한 데이터 영역의 크기

 

Remarks

WSAAsyncGetServByPort 함수는 getservbyport 함수의 비동기 버전입니다. 이 함수는 port 번호와 부합하는 서비스 정보를 얻어냅니다. 함수를 호출하게 되면, 윈도즈 소켓은 연산을 시작하게되고, 즉각 함수는 반환됩니다. 즉, 블록킹되지 않는다는 의미죠. 비동기 연산은 빽~ 으로 보이지 않게 수행됩니다. 이렇게 바로 함수가 반환 할 때 주는 리턴값은 비동기 태스크 핸들입니다. 어플리케이션에서는 이값을 다른 작업을 하는데 사용 할 수 있습니다. 비동기 연산이 끝나게 되면, 함수를 호출할 때 넘겨주었던 버퍼에 서비스 정보가 카피되게 됩니다. 그리고, 지정된 어플리케이션 윈도우로 메시지가 보내지게 됩니다.

비동기 작업이 완료 되었을 때, hWnd로 지정되었던 어플리케이션 윈도우는 wMsg 로 지정되었던 메시지를 수신받게 됩니다. wParam 매개변수는 비동기 태스크 핸들을 가지게 됩니다. 이 태스크 핸들은 함수를 호출했을 때 리턴받은 핸들과 같은 핸들입니다. lParam의 상위 16비트는 WINSOCK(2).H에 정의되어 있는 특정한 에러코드가 될 수 있습니다. 만약 에러코드가 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

리턴값은 비동기적인 연산이 성공했든 아니든간에 반환됩니다. 이 리턴값 그자체로는 연산이 정상적으로 수행되었는지 아닌지를 결정할 수는 없습니다.

만약 아무런 에러가 발생하지 않았다면, WSAAsyncGetProtoByPort 함수는 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

See Also

overview, getservbyport, WSACancelAsyncRequest