WNetGetUniversalNameA 関数 (winnetwk.h)

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構造体は、汎用名前付け規則 (UNC) の名前文字列を指します。

REMOTE_NAME_INFO構造体は、UNC 名文字列と 2 つの追加の接続文字列を指します。 詳細については、「解説」を参照してください。

[out] lpBuffer

dwInfoLevel パラメーターで指定された構造体を受け取るバッファーへのポインター。

[in, out] lpBufferSize

lpBuffer パラメーターによって指されるバッファーのサイズをバイト単位で指定する変数へのポインター。

関数が成功すると、 lpBufferSize によって指される変数がバッファーに格納されているバイト数に設定されます。 バッファーが小さすぎるために関数が失敗した場合、この場所は必要なバッファー サイズを受け取り、関数はERROR_MORE_DATAを返します。

戻り値

関数が成功した場合、戻り値はNO_ERROR。

関数が失敗した場合、戻り値は システム エラー コード (次のいずれかの値など) です。

解説

ローカル ドライブベースのパスの汎用形式は、明確でコンピューターに依存しない方法でネットワーク リソースを識別します。 その後、その名前を他のコンピューター上のプロセスに渡して、それらのプロセスがリソースへのアクセスを取得できるようにします。

WNetGetUniversalName 関数は現在、汎用名前付け規則 (UNC) 名の 1 つをサポートしています。これは次のようになります。

\\servername\sharename\path\file 

lpLocalPath パラメーターの前述の説明の例を使用すると、共有ネットワーク ドライブが COOLSERVER という名前のサーバー上にあり、共有名が HOTSHARE の場合、ドライブベースの名前が H:\Win32\Examples\Sample.doc ネットワーク リソースの UNC 名は次のようになります。

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

UNIVERSAL_NAME_INFO構造体には、UNC 名文字列へのポインターが含まれています。 REMOTE_NAME_INFO構造体には、UNC 名文字列へのポインターと、他の 2 つの便利な文字列へのポインターも含まれています。 たとえば、プロセスは 、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 関数のいずれかを呼び出して 1 人のユーザー ログオンでネットワーク ドライブ文字を作成するアプリケーションに影響を与える可能性がありますが、別のユーザー ログオンで既存のネットワーク ドライブ文字を照会します。 このような状況の例としては、たとえば CreateProcessAsUser 関数を呼び出してユーザーの 2 番目のログオンがログオン セッション内に作成され、2 番目のログオンで 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);
    }
}

要件

関連項目

共有の場所の決定

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Windows ネットワーク (WNet) の概要

Windows ネットワーク関数