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 構造体を格納します。 |
|
関数は、バッファーに REMOTE_NAME_INFO 構造体を格納します。 |
UNIVERSAL_NAME_INFO構造体は、汎用名前付け規則 (UNC) の名前文字列を指します。
REMOTE_NAME_INFO構造体は、UNC 名文字列と 2 つの追加の接続文字列を指します。 詳細については、「解説」を参照してください。
[out] lpBuffer
dwInfoLevel パラメーターで指定された構造体を受け取るバッファーへのポインター。
[in, out] lpBufferSize
lpBuffer パラメーターによって指されるバッファーのサイズをバイト単位で指定する変数へのポインター。
関数が成功すると、 lpBufferSize によって指される変数がバッファーに格納されているバイト数に設定されます。 バッファーが小さすぎるために関数が失敗した場合、この場所は必要なバッファー サイズを受け取り、関数はERROR_MORE_DATAを返します。
戻り値
関数が成功した場合、戻り値はNO_ERROR。
関数が失敗した場合、戻り値は システム エラー コード (次のいずれかの値など) です。
| リターン コード | 説明 |
|---|---|
|
lpLocalPath パラメーターが指す文字列が無効です。 |
|
リモート デバイスへの現在の接続はありませんが、それには記憶された (永続的な) 接続があります。 |
|
ネットワーク固有のエラーが発生しました。 WNetGetLastError 関数を使用して、エラーの説明を取得します。 |
|
lpBuffer パラメーターが指すバッファーが小さすぎます。 この関数は、 lpBufferSize パラメーターが指す変数を必要なバッファー サイズに設定します。 後続の呼び出しでは、さらに多くのエントリを使用できます。 |
|
dwInfoLevel パラメーターは UNIVERSAL_NAME_INFO_LEVEL に設定されていますが、ネットワーク プロバイダーは UNC 名をサポートしていません。 (どのネットワーク プロバイダーもこの関数をサポートしません。 |
|
どのネットワーク プロバイダーも、ローカル名に接続があることを認識しません。 ただし、接続が属している可能性のあるプロバイダーが少なくとも 1 つのプロバイダーでネットワークを使用することはできません。 |
|
ネットワークが利用できません。 |
|
lpLocalPath パラメーターで指定されたデバイスはリダイレクトされません。 |
解説
ローカル ドライブベースのパスの汎用形式は、明確でコンピューターに依存しない方法でネットワーク リソースを識別します。 その後、その名前を他のコンピューター上のプロセスに渡して、それらのプロセスがリソースへのアクセスを取得できるようにします。
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);
}
}
注意
winnetwk.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして WNetGetUniversalName を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winnetwk.h |
| Library | Mpr.lib |
| [DLL] | Mpr.dll |