GetAddressByNameA 함수(nspapi.h)

[GetAddressByName 은 Windows 소켓 2를 기준으로 더 이상 사용할 수 없습니다. 대신 프로토콜 독립적 이름 확인에 자세히 설명된 함수를 사용합니다.]

GetAddressByName 함수는 네임스페이스 또는 기본 네임스페이스 집합을 쿼리하여 지정된 네트워크 서비스에 대한 네트워크 주소 정보를 검색합니다. 이 프로세스를 서비스 이름 확인이라고 합니다. 네트워크 서비스는 함수를 사용하여 바인딩 함수와 함께 사용할 수 있는 로컬 주소 정보를 가져올 수도 있습니다.

구문

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

매개 변수

[in] dwNameSpace

운영 체제에서 네트워크 주소 정보를 쿼리해야 하는 네임스페이스 또는 기본 네임스페이스 집합입니다.

다음 상수 중 하나를 사용하여 네임스페이스를 지정합니다.

값	의미
NS_DEFAULT	기본 네임스페이스 집합입니다. 함수는 이 집합 내의 각 네임스페이스를 쿼리합니다. 기본 네임스페이스 집합에는 일반적으로 시스템에 설치된 모든 네임스페이스가 포함됩니다. 그러나 시스템 관리자는 집합에서 특정 네임스페이스를 제외할 수 있습니다. 대부분의 애플리케이션이 dwNameSpace에 사용해야 하는 값입니다.
NS_DNS	호스트 이름 확인을 위해 인터넷에서 사용되는 DNS(도메인 이름 시스템)입니다.
NS_NETBT	TCP/IP 계층을 통해 NetBIOS. 모든 운영 체제는 NetBIOS에 컴퓨터 이름을 등록합니다. 이 네임스페이스는 컴퓨터 이름을 이 등록을 사용하는 IP 주소로 변환하는 데 사용됩니다. NS_NETBT WINS 서버에 액세스하여 해결을 수행할 수 있습니다.
NS_SAP	NetWare Service Advertising Protocol입니다. 적절한 경우 NetWare 바인더리에 액세스할 수 있습니다. NS_SAP 서비스 등록을 허용하는 동적 네임스페이스입니다.
NS_TCPIP_HOSTS	systemroot>\system32\drivers\etc\hosts 파일의 조회 값<입니다.
NS_TCPIP_LOCAL	로컬 호스트 이름과의 비교를 포함하여 로컬 TCP/IP 이름 확인 메커니즘은 호스트와 IP 주소 매핑의 캐시에서 호스트 이름 및 IP 주소를 조회합니다.

 

GetAddressByName에 대한 대부분의 호출은 특수 값 NS_DEFAULT 사용해야 합니다. 이를 통해 클라이언트는 인터넷 작업에서 사용할 수 있는 네임스페이스를 전혀 알지 못했습니다. 시스템 관리자가 네임스페이스 액세스를 결정합니다. 네임스페이스는 클라이언트가 변경 내용을 인식하지 않고도 오고 갈 수 있습니다.

[in] lpServiceType

네트워크 서비스의 형식을 지정하는 GUID(Globally Unique Identifier)에 대한 포인터입니다. Svcguid.h 헤더 파일에는 여러 GUID 서비스 형식의 정의와 함께 작업하기 위한 매크로가 포함되어 있습니다.

Svcguid.h 헤더 파일은 Winsock2.h 헤더 파일에 자동으로 포함되지 않습니다.

[in, optional] lpServiceName

서비스 이름을 고유하게 나타내는 0으로 끝나는 문자열에 대한 포인터입니다. 예를 들어 "MY SNA SERVER"입니다.

lpServiceName을 NULL로 설정하는 것은 dwResolution을 RES_SERVICE 설정하는 것과 같습니다. 함수는 두 번째 모드에서 작동하여 지정된 형식의 서비스가 바인딩해야 하는 로컬 주소를 가져옵니다. 함수는 *lpCsaddrBuffer에 저장된 CSADDR_INFO 구조체의 LocalAddr 멤버 내에 로컬 주소를 저장합니다.

dwResolution이 RES_SERVICE 설정된 경우 함수는 lpServiceName 매개 변수를 무시합니다.

dwNameSpace가 NS_DNS 설정된 경우 *lpServiceName은 호스트의 이름입니다.

[in, optional] lpiProtocols

프로토콜 식별자의 0으로 끝나는 배열에 대한 포인터입니다. 함수는 이러한 프로토콜을 제공하는 네임스페이스 공급자로 이름 확인 시도를 제한합니다. 이렇게 하면 호출자가 검색의 scope 제한할 수 있습니다.

lpiProtocols가 NULL로 설정된 경우 함수는 사용 가능한 모든 프로토콜에 대한 정보를 검색합니다.

[in] dwResolution

서비스 이름 확인 프로세스의 측면을 지정하는 비트 플래그 집합입니다. 다음 비트 플래그가 정의됩니다.

값	의미
RES_SERVICE	설정된 경우 함수는 지정된 형식의 서비스가 바인딩해야 하는 주소를 검색합니다. lpServiceName 매개 변수를 NULL로 설정하는 것과 같습니다. 이 플래그가 명확하면 일반 이름 확인이 발생합니다.
RES_FIND_MULTIPLE	이 플래그가 설정되면 운영 체제는 서비스에 대한 모든 네임스페이스를 광범위하게 검색합니다. 모든 적절한 네임스페이스에 서비스 이름을 resolve 요청합니다. 이 플래그가 명확하면 운영 체제는 서비스 주소가 발견되는 즉시 검색을 중지합니다.
RES_SOFT_SEARCH	네임스페이스가 여러 수준의 검색을 지원하는 경우 이 플래그는 유효합니다. 이 플래그가 유효하고 설정된 경우 운영 체제는 네임스페이스를 간단하고 빠르게 검색합니다. 이는 애플리케이션이 서비스에 대해 찾기 쉬운 주소만 가져와야 하는 경우에 유용합니다. 이 플래그가 유효하고 명확한 경우 운영 체제는 네임스페이스를 보다 광범위하게 검색합니다.

[in, optional] lpServiceAsyncInfo

나중에 사용하도록 예약됨; 은 NULL로 설정해야 합니다.

[out] lpCsaddrBuffer

하나 이상의 CSADDR_INFO 데이터 구조를 수신하는 버퍼에 대한 포인터입니다. 버퍼에 기록된 구조체의 수는 해결 시도에서 찾은 정보의 양에 따라 달라집니다. 대부분의 경우 하나만 있지만 여러 구조체가 작성된다고 가정해야 합니다.

[in, out] lpdwBufferLength

입력 시 lpCsaddrBuffer가 가리키는 버퍼의 크기를 바이트 단위로 지정하는 변수에 대한 포인터입니다.

출력 시 이 변수에는 CSADDR_INFO 구조체의 배열을 저장하는 데 필요한 총 바이트 수가 포함됩니다. 이 값이 *lpdwBufferLength의 입력 값보다 작거나 같고 함수가 성공하면 버퍼에 실제로 저장된 바이트 수입니다. 이 값이 *lpdwBufferLength의 입력 값보다 크면 버퍼가 너무 작고 *lpdwBufferLength 의 출력 값이 필요한 최소 버퍼 크기입니다.

[in, out] lpAliasBuffer

네트워크 서비스에 대한 별칭 정보를 수신하는 버퍼에 대한 포인터입니다.

네임스페이스가 별칭을 지원하는 경우 함수는 lpAliasBuffer가 가리키는 버퍼에 0으로 끝나는 이름 문자열 배열을 저장합니다. 목록 끝에 이중 제로 종결자가 있습니다. 배열의 이름은 서비스의 기본 이름입니다. 다음에 나타나는 이름은 별칭입니다. 별칭을 지원하는 네임스페이스의 예는 DNS입니다.

네임스페이스가 별칭을 지원하지 않는 경우 이중 0 종결자를 버퍼에 저장합니다.

이 매개 변수는 선택 사항이며 NULL로 설정할 수 있습니다.

[in, out] lpdwAliasBufferLength

입력 시 lpAliasBuffer가 가리키는 버퍼의 크기(문자)를 지정하는 변수에 대한 포인터입니다.

출력 시 이 변수에는 이름 문자열 배열을 저장하는 데 필요한 총 요소 수(문자)가 포함됩니다. 이 값이 *lpdwAliasBufferLength의 입력 값보다 작거나 같고 함수가 성공하면 버퍼에 실제로 저장된 요소 수입니다. 이 값이 *lpdwAliasBufferLength의 입력 값보다 크면 버퍼가 너무 작고 출력 값 *lpdwAliasBufferLength 가 필요한 최소 버퍼 크기입니다.

lpAliasBuffer가 NULL인 경우 lpdwAliasBufferLength는 의미가 없으며 NULL일 수도 있습니다.

반환 값

함수가 성공하면 반환 값은 lpCsaddrBuffer가 가리키는 버퍼에 기록된 CSADDR_INFO 데이터 구조의 수입니다.

함수가 실패하면 반환 값은 SOCKET_ERROR( -1)입니다. 확장 오류 정보를 얻으려면 다음 확장 오류 값을 반환하는 GetLastError를 호출합니다.

오류 코드	의미
ERROR_INSUFFICIENT_BUFFER	lpCsaddrBuffer가 가리키는 버퍼가 너무 작아 관련 CSADDR_INFO 구조를 모두 받을 수 없습니다. *lpdwBufferLength에서 반환된 값만큼 버퍼를 사용하여 함수를 호출합니다.

설명

이 함수는 gethostbyname 함수의 더 강력한 버전입니다. GetAddressByName 함수는 여러 이름 서비스에서 작동합니다.

참고gethostbyname 함수는 getaddrinfo 함수를 도입하여 더 이상 사용되지 않습니다. Windows Sockets 2 애플리케이션을 만드는 개발자는 gethostbyname 대신 getaddrinfo 함수를 사용해야 합니다.

 

GetAddressByName 함수를 사용하면 클라이언트가 네트워크 서비스에 대한 Windows 소켓 주소를 가져올 수 있습니다. 클라이언트는 해당 서비스 유형 및 서비스 이름으로 관심 있는 서비스를 지정합니다.

대부분의 이름 서비스는 서비스 이름을 확인할 때 이름 서비스 공급자가 고려하는 기본 접두사 또는 접미사를 지원합니다. 예를 들어 DNS 네임스페이스에서 도메인 이름이 "nt.microsoft.com"이고 "ftp millikan"이 입력으로 제공되는 경우 DNS 소프트웨어는 "millikan"을 resolve 못하지만 "millikan.nt.microsoft.com"을 성공적으로 확인합니다.

GetAddressByName 함수는 특정 네임스페이스 내에서 또는 기본 네임스페이스 집합 내에서 두 가지 방법으로 서비스 주소를 검색할 수 있습니다. 관리자는 기본 네임스페이스를 사용하여 이름으로 지정된 경우에만 특정 네임스페이스가 서비스 주소를 검색할 수 있도록 지정할 수 있습니다. 관리자 또는 네임스페이스 - 설치 프로그램은 네임스페이스 검색 순서를 제어할 수도 있습니다.

참고

nspapi.h 헤더는 GETAddressByName을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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

추가 정보

CSADDR_INFO

Winsock 함수

Winsock 참조

getaddrinfo

gethostbyname