WNetUseConnectionA 関数 (winnetwk.h)
WNetUseConnection 関数は、ネットワーク リソースに接続します。 関数は、ローカル デバイスをネットワーク リソースにリダイレクトできます。
WNetUseConnection 関数は、WNetAddConnection3 関数に似ています。 メイン違いは、WNetUseConnection で未使用のローカル デバイスを自動的に選択してネットワーク リソースにリダイレクトできることです。
構文
DWORD WNetUseConnectionA(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserId,
[in] DWORD dwFlags,
[out] LPSTR 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 メンバーによって指定された値が、どのプロバイダーにも一致しません。 |
|
接続の試行は、ネットワーク リソース プロバイダーの 1 つからのダイアログ ボックスまたは呼び出されたリソースによって、ユーザーによって取り消されました。 |
|
ネットワーク固有のエラーが発生しました。 エラーの説明を取得するには、 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 を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winnetwk.h |
| Library | Mpr.lib |
| [DLL] | Mpr.dll |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示