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 빈 문자열을 가리키는 경우 함수는 암호를 사용하지 않습니다.
잘못된 암호로 인해 연결이 실패하고 CONNECT_INTERACTIVE 값이 dwFlags 매개 변수에 설정된 경우 함수는 사용자에게 암호를 입력하도록 요청하는 대화 상자를 표시합니다.
[in] lpUserName
연결을 만들기 위한 사용자 이름을 지정하는 상수 null종결 문자열에 대한 포인터입니다.
lpUserName 매개 변수는 사용자가 기본 사용자 이름 또는 계정 이외의 사용자 이름 또는 계정이 할당된 네트워크 리소스에 연결하려는 경우에 지정됩니다.
사용자 이름 문자열은 보안 컨텍스트나타냅니다. 네트워크 공급자에 한정될 수 있습니다.
[in] dwFlags
연결 옵션 집합입니다. 연결 옵션의 가능한 값은 Winnetwk.h 헤더 파일에 정의됩니다. 현재 다음 값을 사용할 수 있습니다.
| 값 | 의미 |
|---|---|
|
네트워크 리소스 연결을 기억해야 합니다.
이 비트 플래그를 설정하면 사용자가 로그온할 때 운영 체제가 자동으로 연결을 복원하려고 시도합니다. 운영 체제는 로컬 디바이스를 리디렉션하는 성공적인 연결만 기억합니다. 실패한 연결이나 디바이스 없는 연결은 기억나지 않습니다. (디바이스 없는 연결은 이 비트 플래그가 명확하면 사용자가 로그온할 때 운영 체제에서 연결을 복원하지 않습니다. |
|
네트워크 리소스 연결은 최근 연결 목록에 배치하면 안 됩니다.
이 플래그가 설정되고 연결이 성공적으로 추가되면 네트워크 리소스 연결은 연결된 리디렉션된 로컬 디바이스가 있는 경우에만 최근 연결 목록에 배치됩니다. |
|
네트워크 리소스 연결을 기억해서는 안 됩니다.
이 플래그가 설정되면 사용자가 다시 로그온할 때 운영 체제에서 연결을 복원하려고 시도하지 않습니다. |
|
이 플래그를 설정하면 운영 체제가 인증을 위해 사용자와 상호 작용할 수 있습니다. |
|
이 플래그는 사용자에게 대안을 제공할 기회를 제공하지 않고 사용자 이름 또는 암호에 대한 기본 설정을 사용하지 않도록 시스템에 지시합니다. 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를
Windows Server 2003 및 Windows XP에서 LocalSystem으로 실행되는 서비스가 WNetAddConnection2 함수를 호출하는 경우 매핑된 드라이브가 모든 사용자 로그온 세션에 표시됩니다.
Microsoft 네트워크 공급자의 경우 lpNetResource 매개 변수가 가리키는 NETRESOURCE 구조의 lpRemoteName 멤버는 점선 소수점 표기법으로 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);
}
메모
winnetwk.h 헤더는 WNetAddConnection2를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winnetwk.h |
| 라이브러리 | Mpr.lib |
| DLL | Mpr.dll |
참고 항목
WNetGetConnection
windows 네트워킹 함수