WNetUseConnectionW 함수(winnetwk.h)
WNetUseConnection 함수는 네트워크 리소스에 연결합니다. 함수는 로컬 디바이스를 네트워크 리소스로 리디렉션할 수 있습니다.
WNetUseConnection 함수는 WNetAddConnection3 함수와 유사합니다. 기본 차이점은 WNetUseConnection이 사용하지 않는 로컬 디바이스를 자동으로 선택하여 네트워크 리소스로 리디렉션할 수 있다는 것입니다.
구문
DWORD WNetUseConnectionW(
[in] HWND hwndOwner,
[in] LPNETRESOURCEW lpNetResource,
[in] LPCWSTR lpPassword,
[in] LPCWSTR lpUserId,
[in] DWORD dwFlags,
[out] LPWSTR lpAccessName,
[in, out] LPDWORD lpBufferSize,
[out] LPDWORD lpResult
);
매개 변수
[in] hwndOwner
네트워크 리소스 공급자가 대화 상자의 소유자 창으로 사용할 수 있는 창에 대한 핸들입니다. dwFlags 매개 변수에서 CONNECT_INTERACTIVE 값을 설정하는 경우 이 매개 변수를 사용합니다.
[in] lpNetResource
제안된 연결의 세부 정보를 지정하는 NETRESOURCE 구조체에 대한 포인터입니다. 구조에는 네트워크 리소스, 로컬 디바이스 및 네트워크 리소스 공급자에 대한 정보가 포함됩니다.
NETRESOURCE 구조체의 다음 멤버를 지정해야 합니다.
WNetUseConnection 함수는 NETRESOURCE 구조체의 다른 멤버를 무시합니다. 자세한 내용은 dwFlags 매개 변수에 대한 다음 설명을 참조하세요.
[in] lpPassword
네트워크 연결을 만드는 데 사용할 암호를 지정하는 null로 끝나는 상수 문자열에 대한 포인터입니다.
lpPassword가 NULL인 경우 함수는 lpUserID로 지정된 사용자와 연결된 현재 기본 암호를 사용합니다.
lpPassword가 빈 문자열을 가리키는 경우 함수는 암호를 사용하지 않습니다.
잘못된 암호로 인해 연결이 실패하고 dwFlags 매개 변수에 CONNECT_INTERACTIVE 값이 설정된 경우 함수는 사용자에게 암호를 입력하라는 대화 상자를 표시합니다.
[in] lpUserId
연결을 만들기 위한 사용자 이름을 지정하는 null로 끝나는 상수 문자열에 대한 포인터입니다.
lpUserID가 NULL인 경우 함수는 기본 사용자 이름을 사용합니다. (프로세스의 사용자 컨텍스트는 기본 사용자 이름을 제공합니다.)
lpUserID 매개 변수는 사용자가 기본 사용자 이름 또는 계정이 아닌 사용자 이름 또는 계정이 할당된 네트워크 리소스에 연결하려는 경우에 지정됩니다.
사용자 이름 문자열은 보안 컨텍스트를 나타냅니다. 네트워크 공급자와 관련이 있을 수 있습니다.
[in] dwFlags
연결을 설명하는 비트 플래그 집합입니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
이 플래그를 설정하면 운영 체제가 인증을 위해 사용자와 상호 작용할 수 있습니다. |
|
이 플래그는 사용자에게 대안을 제공할 기회를 제공하지 않고 사용자 이름 또는 암호에 대한 기본 설정을 사용하지 않도록 시스템에 지시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다. |
|
이 플래그는 연결을 만들 때 로컬 디바이스의 리디렉션을 강제로 수행합니다.
NETRESOURCE의 lpLocalName 멤버가 리디렉션할 로컬 디바이스를 지정하는 경우 운영 체제에서 지정된 디바이스를 리디렉션하려고 시도하므로 이 플래그는 적용되지 않습니다. 운영 체제에서 로컬 디바이스를 자동으로 선택하면 dwType 멤버가 RESOURCETYPE_ANY 동일하지 않아야 합니다. 이 플래그를 설정하지 않으면 네트워크에서 로컬 디바이스를 리디렉션해야 하는 경우에만 로컬 디바이스가 리디렉션을 위해 자동으로 선택됩니다. Windows XP: 시스템에서 네트워크 드라이브 문자를 자동으로 할당하면 문자가 Z:로 시작하고 Y:로 시작하고 C:로 끝나는 문자가 할당됩니다. 이렇게 하면 로그온 드라이브당 문자(예: 네트워크 드라이브 문자)와 전역 드라이브 문자(예: 디스크 드라이브) 간의 충돌이 줄어듭니다. 이전 릴리스에는 C: 로 시작하고 Z:로 끝나는 드라이브 문자가 할당되었습니다. |
|
이 플래그는 운영 체제에 네트워크 리소스 연결을 저장하도록 지시합니다.
이 비트 플래그가 설정되면 운영 체제는 사용자가 로그온할 때 자동으로 연결을 복원하려고 시도합니다. 시스템은 로컬 디바이스를 리디렉션하는 성공적인 연결만 기억합니다. 실패한 연결이나 디바이스 없는 연결은 기억나지 않습니다. ( lpLocalName 이 NULL 이거나 빈 문자열을 가리키는 경우 디바이스 없는 연결이 발생합니다.) 이 비트 플래그가 명확하면 운영 체제가 로그온 시 연결을 자동으로 복원하지 않습니다. |
|
이 플래그가 설정된 경우 운영 체제는 사용자에게 GUI(그래픽 사용자 인터페이스) 대신 명령줄을 사용하여 인증하라는 메시지를 표시합니다. CONNECT_INTERACTIVE 설정되지 않으면 이 플래그는 무시됩니다.
Windows 2000/NT 및 Windows Me/98/95: 이 값은 지원되지 않습니다. |
|
이 플래그가 설정되고 운영 체제에서 자격 증명을 묻는 메시지가 표시되면 자격 증명 관리자가 자격 증명을 저장해야 합니다. 호출자의 로그온 세션에 대해 자격 증명 관리자를 사용하지 않도록 설정하거나 네트워크 공급자가 자격 증명 저장을 지원하지 않는 경우 이 플래그는 무시됩니다. CONNECT_COMMANDLINE 플래그를 설정하지 않으면 이 플래그도 무시됩니다.
Windows 2000/NT 및 Windows Me/98/95: 이 값은 지원되지 않습니다. |
[out] lpAccessName
연결에서 시스템 요청을 수신하는 버퍼에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.
이 매개 변수를 지정하고 NETRESOURCE 구조의 lpLocalName 멤버가 로컬 디바이스를 지정하는 경우 이 버퍼는 로컬 디바이스 이름을 받습니다. lpLocalName이 디바이스를 지정하지 않고 네트워크에 로컬 디바이스 리디렉션이 필요하거나 CONNECT_REDIRECT 값이 설정된 경우 이 버퍼는 리디렉션된 로컬 디바이스의 이름을 받습니다.
그렇지 않으면 버퍼에 복사된 이름은 원격 리소스의 이름입니다. 지정된 경우 이 버퍼는 lpRemoteName 멤버가 가리키는 문자열만큼 커야 합니다.
[in, out] lpBufferSize
lpAccessName 버퍼의 크기를 문자 단위로 지정하는 변수에 대한 포인터입니다. 버퍼가 충분히 크지 않아 호출이 실패하면 함수는 이 위치에서 필요한 버퍼 크기를 반환합니다. 자세한 내용은 반환 값 섹션에서 lpAccessName 매개 변수 및 ERROR_MORE_DATA 오류 코드에 대한 설명을 참조하세요.
[out] lpResult
연결에 대한 추가 정보를 수신하는 변수에 대한 포인터입니다. 이 매개 변수는 다음 값일 수 있습니다.
| 값 | 의미 |
|---|---|
|
이 플래그가 설정된 경우 로컬 디바이스 리디렉션을 사용하여 연결이 수행되었습니다. lpAccessName 매개 변수가 버퍼를 가리키는 경우 로컬 디바이스 이름이 버퍼에 복사됩니다. |
반환 값
함수가 성공하면 반환 값이 NO_ERROR.
함수가 실패하면 반환 값은 다음 값 중 하나와 같은 시스템 오류 코드입니다.
| 반환 코드 | 설명 |
|---|---|
|
호출자에게 네트워크 리소스에 대한 액세스 권한이 없습니다. |
|
lpLocalName 멤버로 지정된 로컬 디바이스가 이미 네트워크 리소스에 연결되어 있습니다. |
|
lpLocalName에 지정된 값이 잘못되었습니다. |
|
lpRemoteName 멤버가 지정한 값은 리소스 이름이 잘못되었거나 명명된 리소스를 배치할 수 없기 때문에 네트워크 리소스 공급자가 사용할 수 없습니다. |
|
lpProvider 멤버가 지정한 값이 공급자와 일치하지 않습니다. |
|
네트워크 리소스 공급자 중 하나 또는 호출된 리소스의 대화 상자를 통해 사용자가 연결을 시도하지 못했습니다. |
|
네트워크 관련 오류가 발생했습니다. 오류에 대한 설명을 가져오려면 WNetGetLastError 함수를 호출합니다. |
|
호출자가 액세스할 수 없는 버퍼에 대한 포인터를 전달했습니다. |
|
이 오류는 다음 조건 중 하나의 결과입니다.
|
|
지정한 암호가 잘못되었으며 CONNECT_INTERACTIVE 플래그가 설정되지 않았습니다. |
|
lpAccessName 버퍼가 너무 작습니다.
로컬 디바이스가 리디렉션되는 경우 버퍼는 로컬 디바이스 이름을 포함할 수 있을 만큼 커야 합니다. 그렇지 않으면 버퍼가 lpRemoteName으로 가리키는 문자열 또는 lpRemoteName에서 별칭을 가리키는 연결 가능한 리소스의 이름을 포함할 만큼 커야 합니다. 이 오류가 반환되면 연결이 수행되지 않습니다. |
|
모든 유효한 로컬 디바이스가 사용 중이므로 운영 체제에서 로컬 리디렉션을 자동으로 선택할 수 없습니다. |
|
네트워크 구성 요소가 시작되지 않았거나 지정된 리소스 이름이 인식되지 않아 작업을 완료할 수 없습니다. |
|
네트워크를 사용할 수 없습니다. |
설명
Windows Server 2003 및 Windows XP: WNet 함수는 MS-DOS 디바이스가 AuthenticationID로 식별되므로 로그온 세션과 연결된 MS-DOS 디바이스 네임스페이스에서 네트워크 드라이브 문자를 만들고 삭제합니다. AuthenticationID는 로그온 세션과 연결된 로컬 고유 식별자 또는 LUID입니다. 이는 WNet 함수 중 하나를 호출하여 한 사용자 로그온에서 네트워크 드라이브 문자를 만들지만 다른 사용자 로그온에서 기존 네트워크 드라이브 문자를 쿼리하는 애플리케이션에 영향을 줄 수 있습니다. 예를 들어 CreateProcessAsUser 함수를 호출하여 사용자의 두 번째 로그온이 로그온 세션 내에 만들어지고 두 번째 로그온이 GetLogicalDrives 함수를 호출하는 애플리케이션을 실행하는 경우를 예로 들어 보겠습니다. GetLogicalDrives 는 첫 번째 로그온에서 WNet 함수에서 만든 네트워크 드라이브 문자를 반환하지 않습니다. 앞의 예제에서는 첫 번째 로그온 세션이 여전히 존재하며 터미널 서비스 세션을 비롯한 모든 로그온 세션에 이 예제를 적용할 수 있습니다. 자세한 내용은 MS-DOS 디바이스 이름 정의를 참조하세요.
참고
winnetwk.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 WNetUseConnection을 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | winnetwk.h |
| 라이브러리 | Mpr.lib |
| DLL | Mpr.dll |