ホーム › NetworkManagement.WNet › PF_NPAddConnection3

PF_NPAddConnection3

コールバック

シグネチャ

DWORD PF_NPAddConnection3(
    HWND hwndOwner,
    NETRESOURCEW* lpNetResource,
    LPWSTR lpPassword,
    LPWSTR lpUserName,
    DWORD dwFlags
);

パラメーター

フィールド

型

説明

hwndOwner

HWND

メッセージやダイアログボックスを所有するウィンドウのハンドルです。このハンドルは dwFlags に CONNECT_INTERACTIVE が設定されている場合にのみ有効であり、認証に必要なダイアログボックスの表示にのみ使用してください。

lpNetResource

NETRESOURCEW*

接続先のネットワークリソースを指定する NETRESOURCE 構造体へのポインターです。接続を行う際は、次のフィールドを設定する必要があります。それ以外のフィールドは無視されます。

値	意味
lpRemoteName	接続先のネットワークリソースを指定します。
lpLocalName	リダイレクトするローカルデバイスの名前("F:" や "LPT1" など)を指定します。この名前は大文字と小文字が区別されず、空の文字列または NULL ポインターでもかまいません。文字列が空または NULL の場合、関数はリダイレクトを行わずにネットワークリソースへ接続します。
dwType	接続先のリソースの種類を指定します。RESOURCETYPE_DISK、RESOURCETYPE_PRINT、RESOURCETYPE_ANY のいずれかを指定できます。呼び出し側が種類を問わない場合や種類が不明な場合は RESOURCETYPE_ANY を使用します。

lpPassword

LPWSTR

接続時に使用するパスワードへのポインターです。通常は lpUserName に対応付けられたパスワードを指定します。NULL を渡すと、既定のパスワードが使用されます。空の文字列はパスワードがないことを示します。パスワードの使用が終わったら、SecureZeroMemory 関数を呼び出してメモリから消去してください。パスワードの保護について詳しくは、Handling Passwords を参照してください。

lpUserName

LPWSTR

接続に使用するユーザー名へのポインターです。NULL の場合は、既定のユーザー名(現在ログオンしているユーザーの名前)が使用されます。これは、リソースへ接続したいが、そのリソースに対して別のユーザー名やアカウントが割り当てられている場合に使用します。

dwFlags

DWORD

次の値の任意の組み合わせです。プロバイダーは、dwFlags に設定されている可能性のあるその他のビットを無視してください。

値	意味
CONNECT_TEMPORARY	接続は参照(ブラウズ)目的で確立されており、おそらくすぐに解放されます。
CONNECT_INTERACTIVE	認証のためにユーザーとの対話が発生する場合があります。
CONNECT_PROMPT	ユーザーに別の値を指定する機会を与えずに、ユーザー名やパスワードの既定値を使用しないでください。このフラグは、CONNECT_INTERACTIVE も設定されている場合にのみ有効です。
CONNECT_DEFERRED	ネットワーク接続を確立するためのリモートネットワーク操作は行わず、代わりに接続を「切断された状態」で復元します。実際の接続は、いずれかのプロセスがその接続を使用しようとしたときにのみ試みます。このビットが設定されている場合、呼び出し側は lpLocalName を指定する必要があります。この機能は、ログオン時のネットワーク接続の復元を高速化するために使用されます。これをサポートするプロバイダーは、NPGetCaps で WNNC_CON_DEFERRED ビットを返す必要があります。

公式ドキュメント

NPAddConnection3 関数は、ローカルデバイスをネットワークリソースに接続します。この関数は NPAddConnection と同じ処理を行いますが、さらに、結果として表示されるダイアログボックスを所有するウィンドウのハンドルと、接続の確立方法を指定できます。

戻り値

関数が成功した場合は WN_SUCCESS を返します。それ以外の場合はエラーコードを返します。エラーコードには次のいずれかが含まれることがあります。

戻り値	説明
WN_BAD_NETNAME	lpNetResource に渡された構造体の lpRemoteName メンバーの値が、このプロバイダーでは有効ではありません。
WN_BAD_LOCALNAME	lpNetResource に渡された構造体の lpLocalName メンバーの値が有効ではありません。
WN_BAD_PASSWORD	指定されたパスワードが有効ではありません。
WN_ALREADY_CONNECTED	lpNetResource に渡された構造体の lpLocalName メンバーで指定されたデバイスは、既に接続されています。
WN_ACCESS_DENIED	接続を確立する権限がありません。
WN_NO_NETWORK	ネットワークが存在しません。
WN_CANCEL	接続の試行が、プロバイダーが表示したダイアログボックスでユーザーによって取り消されました。

解説(Remarks)

指定された資格情報が不十分なためにプロバイダーがパスワードダイアログボックスを表示し、かつ CONNECT_INTERACTIVE フラグが設定されている場合、プロバイダーはアクセス拒否を示すエラーコード(ERROR_LOGON_FAILURE、WN_BAD_PASSWORD、WN_ACCESS_DENIED のいずれか)を返さないことがあります。推奨される動作は、ユーザーが有効な資格情報を入力するか「キャンセル」ボタンを押すまで、プロバイダーが有効な資格情報の入力を求め続けることです。 WNetConnectionDialog 関数または WNetConnectionDialog1 関数で要求された接続を行うために NPAddConnection3 が呼び出され、アクセス拒否のコードが返された場合は、 WNetConnectionDialog 関数または WNetConnectionDialog1 関数自体がパスワードダイアログボックスを表示します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)