Share via

WSAAsyncGetServByName 함수(winsock.h)

  • 아티클

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

구문

HANDLE WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

매개 변수

[in] hWnd

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

[in] wMsg

비동기 요청이 완료될 때 수신할 메시지입니다.

[in] name

null로 종료된 서비스 이름에 대한 포인터입니다.

[in] proto

프로토콜 이름에 대한 포인터입니다. NULL일 수 있습니다. 이 경우 WSAAsyncGetServByName은 s_name 또는 s_aliases 중 하나가 지정된 이름과 일치하는 첫 번째 서비스 항목을 검색합니다. 그렇지 않으면 WSAAsyncGetServByName 이 이름과proto를 모두 일치합니다.

[out] buf

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

[in] buflen

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

반환 값

반환 값은 비동기 작업이 성공적으로 시작되었는지 여부를 지정합니다. 이는 작업 자체의 성공 또는 실패를 의미하지는 않습니다.

오류가 발생하지 않으면 WSAAsyncGetServByName 은 요청에 대한 비동기 작업 핸들인 HANDLE 형식의 0이 아닌 값을 반환합니다(Windows HTASK와 혼동하지 않음). 이 값은 두 가지 방법으로 사용할 수 있습니다. WSACancelAsyncRequest를 사용하여 작업을 취소하거나 wParam 메시지 매개 변수를 검사하여 비동기 작업 및 완료 메시지를 일치시키는 데 사용할 수 있습니다.

비동기 작업을 시작할 수 없는 경우 WSAAsyncServByName 은 0 값을 반환하고 WSAGetLastError를 호출하여 특정 오류 번호를 검색할 수 있습니다.

애플리케이션 창에서 메시지를 받을 때 다음 오류 코드를 설정할 수 있습니다. 위에서 설명한 대로 WSAGETASYNCERROR 매크로를 사용하여 회신 메시지의 lParam에서 추출할 수 있습니다.

오류 코드 의미
WSAENETDOWN
 네트워크 하위 시스템이 실패했습니다.
WSAENOBUFS
 버퍼 공간이 부족합니다.
WSAEFAULT
 buf 매개 변수가 프로세스 주소 공간의 유효한 부분에 있지 않습니다.
WSAHOST_NOT_FOUND
 신뢰할 수 있는 응답 호스트를 찾을 수 없습니다.
WSATRY_AGAIN
 인증되지 않은 서비스를 찾을 수 없거나 서버 오류가 발생했습니다.
WSANO_RECOVERY
 복구할 수 없는 오류로, 서비스 데이터베이스에 액세스할 수 없습니다.
WSANO_DATA
 유효한 이름이며 요청된 형식의 데이터 레코드가 없습니다.
 

다음 오류는 함수 호출 시 발생할 수 있으며 비동기 작업을 시작할 수 없음을 나타냅니다.

오류 코드 의미
WSANOTINITIALISED 이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSAENETDOWN 네트워크 하위 시스템이 실패했습니다.
WSAEINPROGRESS 차단 Windows Sockets 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEWOULDBLOCK 현재는 Windows 소켓 구현 내의 리소스 또는 기타 제약 조건으로 인해 비동기 작업을 예약할 수 없습니다.

설명

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

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

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

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

이 함수에 지정된 버퍼는 Windows 소켓에서 동일한 서브트 구조의 멤버가 참조하는 데이터 영역의 내용과 함께 서브트 구조를 생성하는 데 사용됩니다. WSAENOBUFS 오류를 방지하려면 애플리케이션이 WINSock2.h에 정의된 대로 최소 MAXGETHOSTSTRUCT 바이트 버퍼를 제공해야 합니다.

오류 코드 및 버퍼 길이는 Winsock2.h에 다음과 같이 정의된 WSAGETASYNCERROR 및 WSAGETASYNCBUFLEN 매크로를 사용하여 lParam에서 추출해야 합니다.

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

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

요구 사항

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

추가 정보

WSACancelAsyncRequest

Winsock 함수

Winsock 참조

getservbyname