WNetGetUniversalNameA 함수(winnetwk.h)

아티클
11/20/2024

WNetGetUniversalName 함수는 네트워크 리소스에 대한 드라이브 기반 경로를 사용하고 보다 보편적인 형식의 이름을 포함하는 정보 구조를 반환합니다.

통사론

DWORD WNetGetUniversalNameA(
  [in]      LPCSTR  lpLocalPath,
  [in]      DWORD   dwInfoLevel,
  [out]     LPVOID  lpBuffer,
  [in, out] LPDWORD lpBufferSize
);

매개 변수

[in] lpLocalPath

네트워크 리소스의 드라이브 기반 경로인 null로 끝나는 상수 문자열에 대한 포인터입니다.

예를 들어 H 드라이브가 네트워크 드라이브 공유에 매핑되고 관심 있는 네트워크 리소스가 해당 공유의 디렉터리 \Win32\Examples에 Sample.doc 파일인 경우 드라이브 기반 경로는 H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

lpBuffer 매개 변수가 가리키는 버퍼에 함수가 저장하는 구조체의 형식입니다. 이 매개 변수는 Winnetwk.h 헤더 파일에 정의된 다음 값 중 하나일 수 있습니다.

값	의미
UNIVERSAL_NAME_INFO_LEVEL	함수는 버퍼에 UNIVERSAL_NAME_INFO 구조를 저장합니다.
REMOTE_NAME_INFO_LEVEL	함수는 버퍼에 REMOTE_NAME_INFO 구조를 저장합니다.

UNIVERSAL_NAME_INFO 구조체는 UNC(유니버설 명명 규칙) 이름 문자열을 가리킵니다.

REMOTE_NAME_INFO 구조체는 UNC 이름 문자열과 두 개의 추가 연결 정보 문자열을 가리킵니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

[out] lpBuffer

dwInfoLevel 매개 변수로 지정된 구조를 수신하는 버퍼에 대한 포인터입니다.

[in, out] lpBufferSize

lpBuffer 매개 변수가 가리키는 버퍼의 크기를 바이트 단위로 지정하는 변수에 대한 포인터입니다.

함수가 성공하면 lpBufferSize 가리키는 변수를 버퍼에 저장된 바이트 수로 설정합니다. 버퍼가 너무 작기 때문에 함수가 실패하면 이 위치는 필요한 버퍼 크기를 받고 함수는 ERROR_MORE_DATA 반환합니다.

반환 값

함수가 성공하면 반환 값이 NO_ERROR.

함수가 실패하면 반환 값은 다음 값 중 하나와 같이시스템 오류 코드입니다.

반환 코드	묘사
ERROR_BAD_DEVICE	lpLocalPath 매개 변수가 가리키는 문자열이 잘못되었습니다.
ERROR_CONNECTION_UNAVAIL	원격 디바이스에 대한 현재 연결은 없지만 기억된(영구) 연결이 있습니다.
ERROR_EXTENDED_ERROR	네트워크 관련 오류가 발생했습니다. WNetGetLastError 함수를 사용하여 오류에 대한 설명을 가져옵니다.
ERROR_MORE_DATA	lpBuffer 매개 변수가 가리키는 버퍼가 너무 작습니다. 이 함수는 lpBufferSize 매개 변수가 가리키는 변수를 필요한 버퍼 크기로 설정합니다. 후속 호출을 통해 더 많은 항목을 사용할 수 있습니다.
ERROR_NOT_SUPPORTED	dwInfoLevel 매개 변수는 UNIVERSAL_NAME_INFO_LEVEL 설정되지만 네트워크 공급자는 UNC 이름을 지원하지 않습니다. (이 함수를 지원하는 네트워크 공급자는 없습니다.)
ERROR_NO_NET_OR_BAD_PATH	네트워크 공급자 중 어느 것도 로컬 이름을 연결이 있는 것으로 인식하지 않습니다. 그러나 연결이 속할 수 있는 공급자는 네트워크를 하나 이상 사용할 수 없습니다.
ERROR_NO_NETWORK	네트워크를 사용할 수 없습니다.
ERROR_NOT_CONNECTED	lpLocalPath 매개 변수로 지정된 디바이스가 리디렉션되지 않습니다.

발언

로컬 드라이브 기반 경로의 범용 형식은 명확한 컴퓨터 독립적 방식으로 네트워크 리소스를 식별합니다. 그런 다음 다른 컴퓨터의 프로세스에 이름을 전달하여 해당 프로세스가 리소스에 액세스할 수 있도록 할 수 있습니다.

WNetGetUniversalName 함수는 현재 다음과 같은 하나의 범용 이름 형식인 UNC(범용 명명 규칙) 이름을 지원합니다.

\\servername\sharename\path\file

공유 네트워크 드라이브가 COOLSERVER라는 서버에 있고 공유 이름이 HOTSHARE인 경우 lpLocalPath 매개 변수에 대한 이전 설명의 예제를 사용하면 드라이브 기반 이름이 H:\Win32\Examples\Sample.doc 네트워크 리소스의 UNC 이름은 다음과 같습니다.

\\coolserver\hotshare\win32\examples\sample.doc

UNIVERSAL_NAME_INFO 구조체에는 UNC 이름 문자열에 대한 포인터가 포함됩니다. REMOTE_NAME_INFO 구조에는 UNC 이름 문자열에 대한 포인터와 다른 두 가지 유용한 문자열에 대한 포인터도 포함됩니다. 예를 들어 프로세스는 REMOTE_NAME_INFO 구조체의 lpszConnectionInfo 멤버를 WNetAddConnection2 함수에 전달하여 로컬 디바이스를 네트워크 리소스에 연결할 수 있습니다. 그런 다음 이 프로세스는 lpszRemainingPath 멤버가 가리키는 문자열을 로컬 디바이스 문자열에 추가할 수 있습니다. 결과 문자열은 드라이브 기반 경로가 필요한 함수에 전달될 수 있습니다.

lpLocalPath 매개 변수는 원격 리소스에 이미 있는 경로 또는 리소스를 지정할 필요가 없습니다. 예를 들어 lpLocalPath 매개 변수는 폴더, 폴더 계층 구조 또는 현재 존재하지 않는 파일을 지정하고 지정할 수 있습니다. WNetGetUniversalName 함수는 이러한 경우 보다 범용적인 형식의 이름을 반환합니다.

lpBuffer 매개 변수가 가리키고 lpBufferSize 매개 변수에 지정된 버퍼의 크기는 REMOTE_NAME_INFO 또는 UNIVERSAL_NAME_INFO 구조체의 크기보다 훨씬 커야 합니다. lpBuffer 매개 변수가 가리키는 버퍼는 멤버가 가리키는 UNC 문자열을 REMOTE_NAME_INFO 또는 UNIVERSAL_NAME_INFO 구조체에 저장할 수 있을 만큼 커야 합니다. 버퍼 크기가 너무 작으면 ERROR_MORE_DATA 함수가 실패하고 lpBufferSize 매개 변수가 가리키는 변수는 필요한 버퍼 크기를 나타냅니다.

Windows Server 2003 및 Windows XP: 이 함수는 MS-DOS 디바이스가 AuthenticationID로 식별되기 때문에 로그온 세션과 연결된 MS-DOS 디바이스 네임스페이스를 쿼리합니다. (AuthenticationID는 로그온 세션과 연결된 로컬 고유 식별자또는 LUID입니다.) 이는 WNet 함수 중 하나를 호출하여 한 사용자 로그온 아래에 네트워크 드라이브 문자를 만드는 애플리케이션에 영향을 줄 수 있지만 다른 사용자 로그온에서 기존 네트워크 드라이브 문자를 쿼리합니다. 예를 들어 CreateProcessAsUser 함수를 호출하여 사용자의 두 번째 로그온이 로그온 세션 내에 만들어지고 두 번째 로그온이 GetLogicalDrives 함수를 호출하는 애플리케이션을 실행하는 경우를 예로 들어 보겠습니다. GetLogicalDrives 첫 번째 로그온에서 WNet 함수에서 만든 네트워크 드라이브 문자를 반환하지 않습니다. 앞의 예제에서는 첫 번째 로그온 세션이 여전히 존재하며 이 예제는 터미널 서비스 세션을 비롯한 모든 로그온 세션에 적용할 수 있습니다. 자세한 내용은 MS-DOS 디바이스 이름정의를 참조하세요.

예제

다음 코드 샘플에서는 WNetGetUniversalName 함수를 사용하여 네트워크 리소스의 드라이브 기반 경로와 연결된 범용 UNC 이름 문자열을 검색하는 방법을 보여 줍니다.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])
{
    DWORD dwRetVal;

    WCHAR Buffer[1024];
    DWORD dwBufferLength = 1024;
       
    UNIVERSAL_NAME_INFO * unameinfo;
    REMOTE_NAME_INFO *remotenameinfo;
    
    wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);

    unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }


    remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL, 
        (LPVOID) remotenameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
        wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
        wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }
}

메모

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

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱만 해당]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winnetwk.h
라이브러리	Mpr.lib
DLL	Mpr.dll