WNetAddConnection3A 함수(winnetwk.h)
WNetAddConnection3 함수는 네트워크 리소스에 연결합니다. 함수는 로컬 디바이스를 네트워크 리소스로 리디렉션할 수 있습니다.
WNetAddConnection3 함수는 WNetAddConnection2 함수와 비슷합니다. 기본 차이점은 WNetAddConnection3에는 네트워크 리소스 공급자가 대화 상자의 소유자 창으로 사용할 수 있는 창에 대한 핸들인 추가 매개 변수가 있다는 것입니다. WNetAddConnection2 함수와 WNetAddConnection3 함수는 WNetAddConnection 함수를 대체합니다.
구문
DWORD WNetAddConnection3A(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
매개 변수
[in] hwndOwner
네트워크 리소스 공급자가 대화 상자의 소유자 창으로 사용할 수 있는 창에 대한 핸들입니다. dwFlags 매개 변수에서 CONNECT_INTERACTIVE 값을 설정하는 경우 이 매개 변수를 사용합니다.
hwndOwner 매개 변수는 NULL일 수 있습니다. 이 경우 WNetAddConnection3에 대한 호출은 WNetAddConnection2 함수를 호출하는 것과 같습니다.
[in] lpNetResource
네트워크 리소스, 로컬 디바이스 및 네트워크 리소스 공급자에 대한 정보와 같이 제안된 연결의 세부 정보를 지정하는 NETRESOURCE 구조체에 대한 포인터입니다.
NETRESOURCE 구조체의 다음 멤버를 지정해야 합니다.
WNetAddConnection3 함수는 NETRESOURCE 구조체의 다른 멤버를 무시합니다.
[in] lpPassword
네트워크 연결을 만드는 데 사용할 암호를 지정하는 null로 끝나는 문자열에 대한 포인터입니다.
lpPassword가 NULL인 경우 함수는 lpUserName 매개 변수로 지정된 사용자와 연결된 현재 기본 암호를 사용합니다.
lpPassword가 빈 문자열을 가리키는 경우 함수는 암호를 사용하지 않습니다.
잘못된 암호로 인해 연결이 실패하고 dwFlags 매개 변수에 CONNECT_INTERACTIVE 값이 설정된 경우 함수는 사용자에게 암호를 입력하라는 대화 상자를 표시합니다.
Windows Me/98/95: 이 매개 변수는 NULL 또는 빈 문자열이어야 합니다.
[in] lpUserName
연결을 만들기 위한 사용자 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다.
lpUserName이 NULL인 경우 함수는 기본 사용자 이름을 사용합니다. (프로세스의 사용자 컨텍스트는 기본 사용자 이름을 제공합니다.)
lpUserName 매개 변수는 사용자가 기본 사용자 이름 또는 계정 이외의 사용자 이름 또는 계정이 할당된 네트워크 리소스에 연결하려는 경우에 지정됩니다.
사용자 이름 문자열은 보안 컨텍스트를 나타냅니다. 네트워크 공급자와 관련이 있을 수 있습니다.
Windows Me/98/95: 이 매개 변수는 NULL 또는 빈 문자열이어야 합니다.
[in] dwFlags
연결 옵션 집합입니다. 현재 다음 값이 정의되어 있습니다.
| 값 | 의미 |
|---|---|
|
이 플래그를 설정하면 운영 체제가 인증을 위해 사용자와 상호 작용할 수 있습니다. |
|
이 플래그는 사용자에게 대안을 제공할 기회를 제공하지 않고 사용자 이름 또는 암호에 대한 기본 설정을 사용하지 않도록 시스템에 지시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다. |
|
이 플래그는 연결을 만들 때 로컬 디바이스의 리디렉션을 강제로 수행합니다.
NETRESOURCE의 lpLocalName 멤버가 리디렉션할 로컬 디바이스를 지정하는 경우 운영 체제에서 지정된 디바이스를 리디렉션하려고 시도하므로 이 플래그는 적용되지 않습니다. 운영 체제에서 로컬 디바이스를 자동으로 선택하면 dwType 멤버가 RESOURCETYPE_ANY 동일하지 않아야 합니다. 이 플래그를 설정하지 않으면 네트워크에서 로컬 디바이스를 리디렉션해야 하는 경우에만 로컬 디바이스가 리디렉션을 위해 자동으로 선택됩니다. Windows Server 2003 및 Windows XP: 시스템에서 네트워크 드라이브 문자를 자동으로 할당하면 문자가 Z:로 시작하고 Y:로 시작하고 C:로 끝나는 문자가 할당됩니다. 이렇게 하면 로그온 드라이브당 문자(예: 네트워크 드라이브 문자)와 전역 드라이브 문자(예: 디스크 드라이브) 간의 충돌이 줄어듭니다. 이전 버전의 Windows 할당 드라이브 문자는 C: 로 시작하고 Z:로 끝납니다. |
|
네트워크 리소스 연결을 기억해야 합니다.
이 비트 플래그가 설정되면 운영 체제는 사용자가 로그온할 때 자동으로 연결을 복원하려고 시도합니다. 운영 체제는 로컬 디바이스를 리디렉션하는 성공적인 연결만 기억합니다. 실패한 연결이나 디바이스 없는 연결은 기억나지 않습니다. lpLocalName 멤버가 NULL이거나 빈 문자열을 가리키는 경우 디바이스 없는 연결이 발생합니다. 이 비트 플래그가 명확하면 운영 체제가 로그온 시 연결을 자동으로 복원하지 않습니다. |
|
이 플래그가 설정된 경우 운영 체제는 사용자에게 GUI(그래픽 사용자 인터페이스) 대신 명령줄을 사용하여 인증하라는 메시지를 표시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다.
Windows 2000/NT 및 Windows Me/98/95: 이 값은 지원되지 않습니다. |
|
이 플래그가 설정되고 운영 체제에서 자격 증명을 묻는 메시지가 표시되면 자격 증명 관리자가 자격 증명을 저장해야 합니다. 호출자의 로그온 세션에 대해 자격 증명 관리자를 사용하지 않도록 설정하거나 네트워크 공급자가 자격 증명 저장을 지원하지 않는 경우 이 플래그는 무시됩니다. CONNECT_COMMANDLINE 플래그를 설정하지 않으면 이 플래그도 무시됩니다.
Windows 2000/NT 및 Windows Me/98/95: 이 값은 지원되지 않습니다. |
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 값 중 하나와 같은 시스템 오류 코드입니다.
| 반환 코드 | 설명 |
|---|---|
|
호출자에게 네트워크 리소스에 대한 액세스 권한이 없습니다. |
|
lpLocalName 멤버로 지정된 로컬 디바이스가 이미 네트워크 리소스에 연결되어 있습니다. |
|
로컬 디바이스의 유형 및 네트워크 리소스 유형이 일치하지 않습니다. |
|
lpLocalName에 지정된 값이 잘못되었습니다. |
|
lpRemoteName 멤버로 지정된 값은 리소스 이름이 잘못되었거나 명명된 리소스를 배치할 수 없기 때문에 네트워크 리소스 공급자가 사용할 수 없습니다. |
|
사용자 프로필이 잘못된 형식입니다. |
|
lpProvider 멤버가 지정한 값이 공급자와 일치하지 않습니다. |
|
라우터 또는 공급자가 초기화 중일 수 있습니다. 호출자는 다시 시도해야 합니다. |
|
네트워크 리소스 공급자 중 하나 또는 호출된 리소스의 대화 상자를 통해 사용자가 연결을 취소했습니다. |
|
시스템에서 영구 연결을 처리하기 위해 사용자 프로필을 열 수 없습니다. |
|
lpLocalName 멤버가 지정한 디바이스에 대한 항목이 이미 사용자 프로필에 있습니다. |
|
네트워크 관련 오류가 발생했습니다. WNetGetLastError 함수를 호출하여 오류에 대한 설명을 가져옵니다. |
|
지정한 암호가 잘못되었으며 CONNECT_INTERACTIVE 플래그가 설정되지 않았습니다. |
|
네트워크 구성 요소가 시작되지 않았거나 지정된 이름을 사용할 수 없기 때문에 작업을 수행할 수 없습니다. |
|
네트워크를 사용할 수 없습니다. |
설명
WNetUseConnection 함수는 WNetAddConnection3 함수와 유사합니다. 기본 차이점은 WNetUseConnection이 사용하지 않는 로컬 디바이스를 자동으로 선택하여 네트워크 리소스로 리디렉션할 수 있다는 것입니다.
Windows Server 2003 및 Windows XP에서 WNet 함수는 MS-DOS 디바이스가 AuthenticationID(a)로 식별되기 때문에 로그온 세션과 연결된 MS-DOS 디바이스 네임스페이스에서 네트워크 드라이브 문자를 만들고 삭제합니다.
로그온 세션과 연결된 로컬 고유 식별자 또는 LUID입니다.) 이는 WNet 함수 중 하나를 호출하여 한 사용자 로그온에서 네트워크 드라이브 문자를 만들지만 다른 사용자 로그온에서 기존 네트워크 드라이브 문자를 쿼리하는 애플리케이션에 영향을 줄 수 있습니다. 이 상황의 예로, 예를 들어 CreateProcessAsUser 함수를 호출하여 사용자의 두 번째 로그온을 로그온 세션 내에 만들고 두 번째 로그온이 GetLogicalDrives 함수를 호출하는 애플리케이션을 실행하는 경우일 수 있습니다. GetLogicalDrives 함수에 대한 호출은 첫 번째 로그온에서 WNet 함수 호출에 의해 생성된 네트워크 드라이브 문자를 반환하지 않습니다. 앞의 예제에서는 첫 번째 로그온 세션이 여전히 존재하며 터미널 서비스 세션을 비롯한 모든 로그온 세션에 이 예제를 적용할 수 있습니다. 자세한 내용은 MS-DOS 디바이스 이름 정의를 참조하세요.
Windows Server 2003 및 Windows XP에서 LocalSystem으로 실행되는 서비스가 WNetAddConnection3 함수를 호출하는 경우 매핑된 드라이브가 모든 사용자 로그온 세션에 표시됩니다.
Microsoft 네트워크 공급자의 경우 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조체의 lpRemoteName 멤버는 점선 10진수 표기법의 IPv4 주소를 포함할 수 있습니다. 공유의 예는 다음과 같습니다.
\192.168.1.1\share
Windows Vista 이상의 Microsoft 네트워크 공급자의 경우 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpRemoteName 멤버에 IPv6 주소가 포함될 수 있습니다. 그러나 IPv6 주소가 올바르게 구문 분석되도록 IPv6 리터럴 형식을 사용해야 합니다. IPv6 리터럴 주소는 다음과 같은 형식입니다.
':' 문자가 있는 ipv6-address는 '-' 문자와 ".ipv6-literal.net" 문자열로 바뀝니다.
예를 들어 다음 IPv6 주소는 다음과 같습니다.
2001:4898:9:3:c069:aa97:fe76:2449
공유의 예는 다음과 같습니다.
\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share
다른 네트워크 공급자는 IPv4 또는 IPv6 주소를 포함하는 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpRemoteName 멤버를 지원할 수 있지만 이는 특정 네트워크 공급자에 달려 있습니다.
Windows 7 및 Windows Server 2008 R2: WNetAddConnection3 함수가 pUsername 및 lpPassword에 지정된 명시적 사용자 자격 증명으로 호출되어 특정 서버의 네트워크 리소스와의 연결을 설정한 다음 이러한 매개 변수 중 하나를 NULL로 사용하여 다시 호출(기본 사용자 이름 또는 기본 암호 사용)이 동일한 서버에 대해 호출되면 호출이 실패합니다. 반환된 오류는 ERROR_BAD_USERNAME 또는 ERROR_INVALID_PASSWORD.
참고
winnetwk.h 헤더는 WNetAddConnection3을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | winnetwk.h |
| 라이브러리 | Mpr.lib |
| DLL | Mpr.dll |