SetAddrInfoExA 함수(ws2tcpip.h)

아티클
08/28/2023

SetAddrInfoEx 함수는 이름, 서비스 이름 및 연결된 주소를 특정 네임스페이스 공급자에 등록하거나 등록 취소합니다.

구문

INT WSAAPI SetAddrInfoExA(
  [in]            PCSTR                              pName,
  [in]            PCSTR                              pServiceName,
  [in, out]       SOCKET_ADDRESS                     *pAddresses,
  [in]            DWORD                              dwAddressCount,
  [in, optional]  LPBLOB                             lpBlob,
  [in]            DWORD                              dwFlags,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

매개 변수

[in] pName

주소를 등록하거나 등록 취소할 이름을 포함하는 NULL로 끝나는 문자열에 대한 포인터입니다. 네임스페이스 공급자와 관련된 이 매개 변수의 해석입니다.

[in] pServiceName

등록되는 이름과 연결된 서비스 이름을 포함하는 선택적 NULL로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수의 해석은 네임스페이스 공급자와 관련이 있습니다.

[in, out] pAddresses

네임스페이스 공급자에 등록할 주소의 선택적 목록에 대한 포인터입니다.

[in] dwAddressCount

pAddresses 매개 변수에 전달된 주소 수입니다. 이 매개 변수가 0이면 pName 매개 변수가 네임스페이스 공급자에서 등록 취소됩니다.

[in, optional] lpBlob

주소 목록을 넘어 pName 매개 변수와 연결된 공급자별 네임스페이스 정보를 설정하는 데 사용되는 데이터에 대한 선택적 포인터입니다. pAddresses 매개 변수에 전달할 수 없는 모든 정보는 lpBlob 매개 변수에 전달될 수 있습니다. 이 정보의 형식은 네임스페이스 공급자에 따라 다릅니다.

[in] dwFlags

pName 및 pServiceName 매개 변수를 네임스페이스 공급자에 등록하는 방법을 제어하는 플래그 집합입니다. 이 정보의 해석은 네임스페이스 공급자에 따라 다릅니다.

[in] dwNameSpace

이 정보를 등록할 네임스페이스 공급자를 결정하는 네임스페이스 식별자입니다. 특정 네임스페이스 식별자를 전달하면 지정된 네임스페이스를 지원하는 네임스페이스 공급자에만 이 정보가 등록됩니다. NS_ALL 지정하면 모든 설치된 및 활성 네임스페이스 공급자에 정보가 등록됩니다.

dwNameSpace 매개 변수에 대한 옵션은 Winsock2.h 포함 파일에 나열됩니다. 여러 네임스페이스 공급자가 Windows Vista 이상에 포함되어 있습니다. 다른 네임스페이스 공급자를 설치할 수 있으므로 다음과 같은 가능한 값은 일반적으로 사용할 수 있는 값입니다. 다른 많은 사람들이 가능합니다.

값	의미
NS_ALL	설치된 모든 네임스페이스와 활성 네임스페이스.
NS_BTH	Bluetooth 네임스페이스입니다. 이 네임스페이스 식별자는 Windows Vista 이상에서 지원됩니다.
NS_DNS	DNS(도메인 이름 시스템) 네임스페이스입니다.
NS_EMAIL	전자 메일 네임스페이스입니다. 이 네임스페이스 식별자는 Windows Vista 이상에서 지원됩니다.
NS_NLA	NLA(네트워크 위치 인식) 네임스페이스입니다. 이 네임스페이스 식별자는 Windows XP 이상에서 지원됩니다.
NS_PNRPNAME	특정 피어 이름에 대한 피어 투 피어 네임스페이스입니다. 이 네임스페이스 식별자는 Windows Vista 이상에서 지원됩니다.
NS_PNRPCLOUD	피어 이름 컬렉션의 피어 투 피어 네임스페이스입니다. 이 네임스페이스 식별자는 Windows Vista 이상에서 지원됩니다.

[in, optional] lpNspId

여러 네임스페이스 공급자가 NS_DNS 같은 단일 네임스페이스 아래에 등록된 경우 이 정보를 등록할 특정 네임스페이스 공급자의 선택적 GUID에 대한 포인터입니다. 특정 네임스페이스 공급자에 대한 GUID를 전달하면 지정된 네임스페이스 공급자에만 정보가 등록됩니다. WSAEnumNameSpaceProviders 함수를 호출하여 네임스페이스 공급자에 대한 GUID를 검색할 수 있습니다.

[in, optional] timeout

호출을 중단하기 전에 네임스페이스 공급자의 응답을 기다리는 시간을 밀리초 단위로 나타내는 선택적 매개 변수입니다. 이 매개 변수는 현재 예약되어 있으며 시간 제한 옵션이 지원되지 않으므로 NULL로 설정해야 합니다.

[in, optional] lpOverlapped

비동기 작업에 사용되는 겹치는 구조체에 대한 선택적 포인터입니다. 이 매개 변수는 현재 예약되어 있으며 비동기 작업이 지원되지 않으므로 NULL 로 설정해야 합니다.

[in, optional] lpCompletionRoutine

비동기 작업을 성공적으로 완료할 때 호출할 함수에 대한 선택적 포인터입니다. 이 매개 변수는 현재 예약되어 있으며 비동기 작업이 지원되지 않으므로 NULL 로 설정해야 합니다.

[out, optional] lpNameHandle

비동기 작업에만 사용되는 선택적 포인터입니다. 이 매개 변수는 현재 예약되어 있으며 비동기 작업이 지원되지 않으므로 NULL 로 설정해야 합니다.

반환 값

성공하면 SetAddrInfoEx 는 NO_ERROR(0)를 반환합니다. 실패는 Windows 소켓 오류 코드에 있는 것처럼 0이 아닌 Windows 소켓 오류 코드를 반환합니다.

오류 코드	의미
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSATRY_AGAIN	이름 확인에 일시적인 오류가 발생했습니다.
WSAEINVAL	잘못된 매개 변수가 제공되었습니다. 예약된 매개 변수가 NULL이 아닌 경우 이 오류가 반환됩니다.
WSAENOBUFS	버퍼 공간이 부족합니다.
WSANO_RECOVERY	이름 확인에서 복구할 수 없는 오류가 발생했습니다.
WSA_NOT_ENOUGH_MEMORY	메모리 할당 오류가 발생했습니다.

설명

SetAddrInfoEx 함수는 네임스페이스 공급자를 사용하여 이름 및 하나 이상의 주소를 등록하거나 등록 취소하는 프로토콜 독립적 메서드를 제공합니다. Windows Vista 이상에서 NS_EMAIL 네임스페이스 공급자는 주소 등록 및 등록 취소를 지원합니다. 기본 NS_DNS, NS_PNRPNAME 및 NS_PNRPNAME 네임스페이스 공급자는 현재 이름 등록을 지원하지 않습니다.

setAddrInfoEx 함수가 dwNameSpace 매개 변수로 설정된 NS_ALL 및 lpNspId 매개 변수가 지정되지 않은 경우 SetAddrInfoEx는 모든 설치된 및 활성 네임스페이스에 이름과 연결된 주소를 등록하거나 등록 취소하려고 시도합니다. SetAddrInfoEx 함수는 네임스페이스 공급자가 이름을 성공적으로 등록하거나 등록 취소한 경우 성공을 반환하지만, 성공한 네임스페이스 공급자 또는 요청에 실패한 네임스페이스 공급자에 대한 표시는 없습니다.

UNICODE 또는 _UNICODE 정의되면 SetAddrInfoEx는 이 함수의 유니코드 버전인 SetAddrInfoExW로 정의됩니다. 문자열 매개 변수는 PWSTR 데이터 형식에 정의됩니다.

UNICODE 또는 _UNICODE 정의되지 않은 경우 SetAddrInfoEx는 이 함수의 ANSI 버전인 SetAddrInfoExA에 정의됩니다. 문자열 매개 변수는 PCSTR 데이터 형식입니다.

네임스페이스 공급자에 등록된 정보는 GetAddrInfoEx, getaddrinfo 또는 GetAddrInfoW 함수를 호출하여 반환할 수 있습니다. GetAddrInfoEx 함수는 getaddrinfo 및 GetAddrInfoW 함수의 향상된 버전입니다.

Windows Vista 이상에서는 서비스에서 SetAddrInfoEx 가 호출되는 경우 작업이 서비스를 호출하는 사용자 프로세스의 결과인 경우 서비스는 사용자를 가장해야 합니다. 이는 보안 및 라우팅 구획을 제대로 적용할 수 있도록 하기 위한 것입니다.

Windows 8.1 및 Windows Server 2012 R2: SetAddrInfoExW 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에 대해 지원됩니다.

참고

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8.1, Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	ws2tcpip.h
라이브러리	Ws2_32.lib
DLL	Ws2_32.dll