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 デバイス名前空間でネットワーク ドライブ文字を作成および削除します。MS-DOS デバイスは AuthenticationID によって識別されるためです。 (AuthenticationID は、ログオン セッションに関連付けられている ローカル一意識別子 (LUID) です)。これは、WNet 関数のいずれかを呼び出して 1 人のユーザー ログオンでネットワーク ドライブ文字を作成するアプリケーションに影響を与える可能性がありますが、別のユーザー ログオンで既存のネットワーク ドライブ文字を照会します。 このような状況の例としては、たとえば CreateProcessAsUser 関数を呼び出してユーザーの 2 番目のログオンがログオン セッション内に作成され、2 番目のログオンで GetLogicalDrives 関数を呼び出すアプリケーションが実行される場合があります。 GetLogicalDrives は、最初の ログオン時に WNet 関数によって作成されたネットワーク ドライブ文字を返しません。 前の例では、最初のログオン セッションがまだ存在し、ターミナル サービス セッションを含む任意のログオン セッションに適用できることに注意してください。 詳細については、「 MS-DOS デバイス名の定義」を参照してください。
注意
winnetwk.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして WNetUseConnection を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winnetwk.h |
| Library | Mpr.lib |
| [DLL] | Mpr.dll |