WNetAddConnection2W 関数 (winnetwk.h)
WNetAddConnection2 関数は、ネットワーク リソースへの接続を確立し、ローカル デバイスをネットワーク リソースにリダイレクトできます。
WNetAddConnection2 関数は、WNetAddConnection 関数よりも優先されます。 ネットワーク リソースのプロバイダーがダイアログ ボックスの所有者ウィンドウとして使用できるウィンドウにハンドルを渡すことができる場合は、代わりに WNetAddConnection3 関数を呼び出します。
構文
DWORD WNetAddConnection2W(
[in] LPNETRESOURCEW lpNetResource,
[in] LPCWSTR lpPassword,
[in] LPCWSTR lpUserName,
[in] DWORD dwFlags
);
パラメーター
[in] lpNetResource
ネットワーク リソース、ローカル デバイス、ネットワーク リソース プロバイダーに関する情報など、提案された接続の詳細を指定する NETRESOURCE 構造体へのポインター。
NETRESOURCE 構造体の次のメンバーを指定する必要があります。
WNetAddConnection2 関数は、NETRESOURCE 構造体の他のメンバーを無視します。
[in] lpPassword
ネットワーク接続の作成に使用するパスワードを指定する 、null で終わる定数文字列へのポインター。
lpPassword が NULL の場合、この関数は lpUserName パラメーターで指定されたユーザーに関連付けられている現在の既定のパスワードを使用します。
lpPassword が空の文字列を指している場合、関数はパスワードを使用しません。
無効なパスワードが原因で接続に失敗し、 dwFlags パラメーターにCONNECT_INTERACTIVE値が設定されている場合、この関数はユーザーにパスワードの入力を求めるダイアログ ボックスを表示します。
Windows Me/98/95: このパラメーターは NULL または空の文字列である必要があります。
[in] lpUserName
接続を確立するためのユーザー名を指定する 、null で終わる定数文字列へのポインター。
lpUserName が NULL の場合、関数は既定のユーザー名を使用します。 (プロセスのユーザー コンテキストは、既定のユーザー名を提供します)。
lpUserName パラメーターは、ユーザーに既定のユーザー名またはアカウント以外のユーザー名またはアカウントが割り当てられているネットワーク リソースに接続する場合に指定します。
ユーザー名の文字列は 、セキュリティ コンテキストを表します。 ネットワーク プロバイダーに固有の場合があります。
Windows Me/98/95: このパラメーターは NULL または空の文字列である必要があります。
[in] dwFlags
接続オプションのセット。 接続オプションに使用できる値は、 Winnetwk.h ヘッダー ファイルで定義されています。 現在、次の値を使用できます。
| 値 | 意味 |
|---|---|
|
ネットワーク リソース接続を記憶する必要があります。
このビット フラグが設定されている場合、オペレーティング システムは、ユーザーがログオンしたときに接続の復元を自動的に試行します。 オペレーティング システムでは、ローカル デバイスをリダイレクトする正常な接続のみが記憶されます。 失敗した接続やデバイスレス接続は記憶されません。 ( lpLocalName メンバーが NULL であるか、空の文字列を指している場合、デバイスレス接続が発生します)。 このビット フラグがクリアされている場合、ユーザーがログオンしたときに、オペレーティング システムは接続の復元を試みません。 |
|
ネットワーク リソース接続は、最近の接続の一覧に配置しないでください。
このフラグが設定され、接続が正常に追加された場合、ネットワーク リソース接続は、リダイレクトされたローカル デバイスが関連付けられている場合にのみ、最近の接続リストに配置されます。 |
|
ネットワーク リソース接続は記憶しないでください。
このフラグが設定されている場合、ユーザーが再度ログオンしても、オペレーティング システムは接続の復元を試みません。 |
|
このフラグが設定されている場合、オペレーティング システムは認証のためにユーザーと対話する可能性があります。 |
|
このフラグは、ユーザーに代替手段を提供することなく、ユーザー名またはパスワードに既定の設定を使用しないようにシステムに指示します。 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 デバイス名前空間でネットワーク ドライブ文字を作成および削除します。MS-DOS デバイスは AuthenticationID (a
ログオン セッションに関連付けられているローカル一意識別子 (LUID)。 これは、WNet 関数のいずれかを呼び出して 1 人のユーザー ログオンでネットワーク ドライブ文字を作成するアプリケーションに影響を与える可能性がありますが、別のユーザー ログオンで既存のネットワーク ドライブ文字を照会します。 このような状況の例としては、たとえば CreateProcessAsUser 関数を呼び出してユーザーの 2 番目のログオンがログオン セッション内に作成され、2 番目のログオンで GetLogicalDrives 関数を呼び出すアプリケーションが実行される場合があります。 GetLogicalDrives 関数の呼び出しでは、最初のログオン時に WNet 関数呼び出しによって作成されたネットワーク ドライブ文字は返されません。 前の例では、最初のログオン セッションがまだ存在し、ターミナル サービス セッションを含む任意のログオン セッションに適用できることに注意してください。 詳細については、「 MS-DOS デバイス名の定義」を参照してください。
Windows Server 2003 および Windows XP では、LocalSystem として実行されるサービスが WNetAddConnection2 関数を呼び出すと、マップされたドライブはすべてのユーザー ログオン セッションに表示されます。
Microsoft ネットワーク プロバイダーの場合、lpNetResource パラメーターによって指される NETRESOURCE 構造体の lpRemoteName メンバーには、ドット 10 進表記で 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: PUsername と lpPassword で指定された明示的なユーザー資格情報を使用して WNetAddConnection2 関数を呼び出して、特定のサーバー上のネットワーク リソースとの接続を確立した後、これらのパラメーターのいずれかを 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);
}
WNetAddConnection2 関数を使用してネットワーク リソースに接続する方法を示すその他のコード サンプルについては、「ネットワーク接続の追加」および「共有へのドライブの割り当て」を参照してください。
注意
winnetwk.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして WNetAddConnection2 を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winnetwk.h |
| Library | Mpr.lib |
| [DLL] | Mpr.dll |