WNetAddConnection2A 함수(winnetwk.h)
WNetAddConnection2 함수는 네트워크 리소스에 연결하고 로컬 디바이스를 네트워크 리소스로 리디렉션할 수 있습니다.
WNetAddConnection2 함수는 WNetAddConnection 함수를 대체합니다. 네트워크 리소스 공급자가 대화 상자의 소유자 창으로 사용할 수 있는 창에 핸들을 전달할 수 있는 경우 대신 WNetAddConnection3 함수를 호출합니다.
구문
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
매개 변수
[in] lpNetResource
네트워크 리소스, 로컬 디바이스 및 네트워크 리소스 공급자에 대한 정보와 같이 제안된 연결의 세부 정보를 지정하는 NETRESOURCE 구조체에 대한 포인터입니다.
NETRESOURCE 구조체의 다음 멤버를 지정해야 합니다.
WNetAddConnection2 함수는 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
연결 옵션 집합입니다. 연결 옵션에 대한 가능한 값은 Winnetwk.h 헤더 파일에 정의되어 있습니다. 현재 사용할 수 있는 값은 다음과 입니다.
| 값 | 의미 |
|---|---|
|
네트워크 리소스 연결을 기억해야 합니다.
이 비트 플래그가 설정되면 운영 체제는 사용자가 로그온할 때 자동으로 연결을 복원하려고 시도합니다. 운영 체제는 로컬 디바이스를 리디렉션하는 성공적인 연결만 기억합니다. 실패한 연결이나 디바이스 없는 연결은 기억나지 않습니다. (lpLocalName 멤버가 NULL이거나 빈 문자열을 가리키는 경우 디바이스 없는 연결이 발생합니다.) 이 비트 플래그가 명확하면 사용자가 로그온할 때 운영 체제에서 연결을 복원하지 않습니다. |
|
네트워크 리소스 연결은 최근 연결 목록에 배치하면 안 됩니다.
이 플래그가 설정되고 연결이 성공적으로 추가된 경우 네트워크 리소스 연결은 연결된 리디렉션된 로컬 디바이스가 있는 경우에만 최근 연결 목록에 배치됩니다. |
|
네트워크 리소스 연결을 기억해서는 안 됩니다.
이 플래그가 설정되면 사용자가 다시 로그온할 때 운영 체제에서 연결을 복원하지 않습니다. |
|
이 플래그가 설정된 경우 운영 체제는 인증을 위해 사용자와 상호 작용할 수 있습니다. |
|
이 플래그는 사용자에게 대안을 제공할 기회를 제공하지 않고 사용자 이름 또는 암호에 대한 기본 설정을 사용하지 않도록 시스템에 지시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다. |
|
이 플래그는 연결을 만들 때 로컬 디바이스의 리디렉션을 강제로 수행합니다.
NETRESOURCE의 lpLocalName 멤버가 리디렉션할 로컬 디바이스를 지정하는 경우 운영 체제에서 지정된 디바이스를 리디렉션하려고 시도하므로 이 플래그는 적용되지 않습니다. 운영 체제에서 로컬 디바이스를 자동으로 선택하면 dwType 멤버가 RESOURCETYPE_ANY 같지 않아야 합니다. 이 플래그가 설정되지 않은 경우 네트워크에서 로컬 디바이스를 리디렉션해야 하는 경우에만 로컬 디바이스가 리디렉션되도록 자동으로 선택됩니다. Windows Server 2003 및 Windows XP: 시스템에서 네트워크 드라이브 문자를 자동으로 할당하면 문자가 Z:, Y:로 시작하고 C:로 끝나는 문자가 할당됩니다. 이렇게 하면 로그온 드라이브별 문자(예: 네트워크 드라이브 문자)와 전역 드라이브 문자(예: 디스크 드라이브) 간의 충돌이 줄어듭니다. 이전 버전의 Windows 할당 드라이브 문자는 C: 로 시작하고 Z:로 끝납니다. |
|
이 플래그가 설정된 경우 운영 체제는 새 미디어를 사용하여 연결을 설정하려고 시도하지 않습니다(예: 새 전화 접속 연결을 시작). |
|
이 플래그가 설정되면 운영 체제는 GUI(그래픽 사용자 인터페이스) 대신 명령줄을 사용하여 사용자에게 인증을 요청하는 메시지를 표시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다.
Windows XP: 이 값은 Windows XP 이상에서 지원됩니다. |
|
이 플래그가 설정되고 운영 체제에서 자격 증명을 묻는 메시지가 표시되면 자격 증명 관리자가 자격 증명을 저장해야 합니다. 호출자의 로그온 세션에 대해 자격 증명 관리자를 사용하지 않도록 설정하거나 네트워크 공급자가 자격 증명 저장을 지원하지 않는 경우 이 플래그는 무시됩니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다. CONNECT_COMMANDLINE 플래그를 설정하지 않으면 이 플래그도 무시됩니다.
Windows XP: 이 값은 Windows XP 이상에서 지원됩니다. |
|
이 플래그가 설정되고 운영 체제에서 자격 증명을 묻는 메시지가 표시되면 자격 증명 관리자가 자격 증명을 다시 설정합니다. 호출자의 로그온 세션에 대해 자격 증명 관리자를 사용하지 않도록 설정하거나 네트워크 공급자가 자격 증명 저장을 지원하지 않는 경우 이 플래그는 무시됩니다. CONNECT_COMMANDLINE 플래그를 설정하지 않으면 이 플래그도 무시됩니다.
Windows Vista: 이 값은 Windows Vista 이상에서 지원됩니다. |
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 오류 코드 또는 시스템 오류 코드 중 하나일 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
호출자는 네트워크 리소스에 액세스할 수 없습니다. |
|
lpLocalName 멤버로 지정된 로컬 디바이스가 이미 네트워크 리소스에 연결되어 있습니다. |
|
로컬 디바이스의 유형 및 네트워크 리소스 유형이 일치하지 않습니다. |
|
지정된 디바이스 이름이 잘못되었습니다. lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpLocalName 멤버가 리디렉션할 수 없는 디바이스를 지정하면 이 오류가 반환됩니다. |
|
네트워크 이름을 찾을 수 없습니다. 이 값은 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpRemoteName 멤버가 리소스 이름이 비어 있거나 유효하지 않거나 명명된 리소스를 배치할 수 없기 때문에 네트워크 리소스 공급자가 허용되지 않는 리소스를 지정하는 경우 반환됩니다. |
|
사용자 프로필이 잘못된 형식입니다. |
|
지정된 네트워크 공급자 이름이 잘못되었습니다. lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpProvider 멤버가 네트워크 공급자와 일치하지 않는 값을 지정하면 이 오류가 반환됩니다. |
|
지정된 사용자 이름이 잘못되었습니다. |
|
라우터 또는 공급자가 초기화 중일 수 있습니다. 호출자는 다시 시도해야 합니다. |
|
네트워크 리소스 공급자 중 하나 또는 호출된 리소스의 대화 상자를 통해 사용자가 연결을 취소했습니다. |
|
시스템에서 영구 연결을 처리하기 위해 사용자 프로필을 열 수 없습니다. |
|
로컬 디바이스 이름에 다른 네트워크 리소스에 대한 저장된 연결이 있습니다. 이 오류는 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpLocalName 멤버로 지정된 디바이스에 대한 항목이 lpNetResource 매개 변수에 지정된 것과 다른 연결에 대한 사용자 프로필에 이미 있는 값을 지정하는 경우 반환됩니다. |
|
네트워크 관련 오류가 발생했습니다. WNetGetLastError 함수를 호출하여 오류에 대한 설명을 가져옵니다. |
|
잘못된 주소에 액세스하려고 했습니다. dwFlags 매개 변수가 CONNECT_REDIRECT 값을 지정하지만 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpLocalName 멤버가 지정되지 않은 경우 이 오류가 반환됩니다. |
|
매개 변수가 잘못되었습니다. lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 dwType 멤버가 RESOURCETYPE_DISK, RESOURCETYPE_PRINT 또는 RESOURCETYPE_ANY 이외의 값을 지정하면 이 오류가 반환됩니다. dwFlags 매개 변수가 잘못되거나 알 수 없는 값을 지정하는 경우에도 이 오류가 반환됩니다. |
|
지정한 암호가 잘못되었으며 CONNECT_INTERACTIVE 플래그가 설정되지 않았습니다. |
|
알 수 없는 사용자 이름 또는 잘못된 암호로 인한 로그온 실패 |
|
지정된 네트워크 경로를 수락한 네트워크 공급자가 없습니다. 이 오류는 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpRemoteName 멤버를 인식한 네트워크 공급자가 없는 경우 반환됩니다. |
|
네트워크를 사용할 수 없습니다. |
|
FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다. |
설명
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으로 실행되는 서비스가 WNetAddConnection2 함수를 호출하는 경우 매핑된 드라이브가 모든 사용자 로그온 세션에 표시됩니다.
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: WNetAddConnection2 함수가 pUsername 및 lpPassword에 지정된 명시적 사용자 자격 증명으로 호출되어 특정 서버의 네트워크 리소스와의 연결을 설정한 다음, 이러한 매개 변수 중 하나를 NULL로 사용하여 다시 호출(기본 사용자 이름 또는 기본 암호 사용)를 동일한 서버에 호출하면 호출이 실패합니다. 반환된 오류는 ERROR_BAD_USERNAME 또는 ERROR_INVALID_PASSWORD.
예제
다음 코드 샘플에서는 WNetAddConnection2 함수를 사용하여 네트워크 리소스에 연결하는 방법을 보여 줍니다.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
// Need to link with Netapi32.lib and Mpr.lib
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
NETRESOURCE nr;
DWORD dwFlags;
if (argc != 5) {
wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
argv[0]);
wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",
argv[0]);
exit(1);
}
wprintf(L"Calling WNetAddConnection2 with\n");
wprintf(L" lpLocalName = %s\n", argv[1]);
wprintf(L" lpRemoteName = %s\n", argv[2]);
wprintf(L" lpUsername = %s\n", argv[3]);
wprintf(L" lpPassword = %s\n", argv[4]);
// Zero out the NETRESOURCE struct
memset(&nr, 0, sizeof (NETRESOURCE));
// Assign our values to the NETRESOURCE structure.
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];
nr.lpRemoteName = argv[2];
nr.lpProvider = NULL;
// Assign a value to the connection options
dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
// a drive letter to the share.
//
dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
// print the error.
//
if (dwRetVal == NO_ERROR)
wprintf(L"Connection added to %s\n", nr.lpRemoteName);
else
wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);
exit(1);
}
WNetAddConnection2 함수를 사용하여 네트워크 리소스에 연결하는 방법을 보여 주는 다른 코드 샘플은 네트워크 연결 추가 및 공유에 드라이브 할당을 참조하세요.
참고
winnetwk.h 헤더는 WNetAddConnection2를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | winnetwk.h |
| 라이브러리 | Mpr.lib |
| DLL | Mpr.dll |