API 関数解説

WNetUseConnection

Declare Function Api_WNetUseConnection& Lib "mpr" Alias "WNetUseConnectionA" (ByVal hwndOwner&, ByRef lpNetResource As NETRESOURCE, ByVal lpUserID$, ByVal lpPassword$, ByVal dwFlags&, ByVal lpAccessName$, ByRef lpBufferSize&, ByRef lpResult&)

Declare Function WNetUseConnection Lib "mpr" Alias "WNetUseConnectionA" (ByVal hwndOwner As Long, ByRef lpNetResource As NETRESOURCE, ByVal lpUserID As String, ByVal lpPassword As String, ByVal dwFlags As Long, ByVal lpAccessName As String, ByRef lpBufferSize As Long, ByRef lpResult As Long) As Long

ネットワーク資源に接続する。ローカルデバイスをネットワーク資源へリダイレクトできる。
WNetUseConnection 関数は、WNetAddConnection3 関数に似ている。WNetAddConnection3 関数との大きな違いは、ネットワーク資源へリダイレクトされる未使用のローカルデバイスを自動的に選択できる点である。

パラメータ
hwndOwner
［入力］ネットワーク資源のプロバイダがダイアログボックスのオーナーウィンドウとして利用できるウィンドウのハンドルを指定する。このパラメ

ータは、dwFlags パラメータで CONNECT_INTERACTIVE をセットする場合に、この hwndOwner パラメータを使う。
lpNetResource
［入力］希望の接続の詳細(ネットワーク資源、ローカルデバイス、ネットワーク資源のプロバイダの情報)を指定する構造体へのポインタを

指定する。
NETRESOURCE 構造体の次のメンバを指定しなければならない。

メンバ	説明
dwType	接続先の資源の種類を指定する。 ESOURCETYPE_DISK や RESOURCETYPE_PRINT など、資源の種類を指定すると最も効率が良くなる。逆に、lpLocalName メンバが NULL の場合や、このメンバが空の文字列を指し、CONNECT_REDIRECT をセットしない場合は、dwType に RESOURCETYPE_ANY を指定できる。この方法は、ネットワーク資源へリダイレクトされるデバイスを自動的に選択する場合は使えない。
lpLocalName	"F:"、"LPT1" など、リダイレクトされるローカルデバイスの名前を表す、NULL で終わる文字列へのポインタである。この文字列の大文字と小文字を区別しない。この文字列が空の場合や、lpLocalName が NULL の場合、ローカルデバイスのリダイレクトなしでネットワーク資源への接続を行う。 dwFlags パラメータで CONNECT_REDIRECT をセットした場合や、ネットワークが、リダイレクトされたローカルデバイスを必要とする場合、リダイレクトされるデバイスを自動的に選択し、そのデバイスの名前が lpAccessName に格納される
lpRemoteName	接続先ネットワーク資源の名前を表す、NULL で終わる文字列へのポインタである。指定する文字列の長さは最大 MAX_PATH 文字で、ネットワークプロバイダの名前付け規則に従う必要がある。
lpProvider	接続先ネットワークプロバイダの名前を表す、NULL で終わる文字列へのポインタである。lpProvider が NULL の場合や、空の文字列を指している場合、オペレーティングシステムは lpRemoteName が指す文字列を解析して正しいプロバイダを特定しようとする。 NULL 以外に設定すると、オペレーティングシステムは指定されたネットワークプロバイダにのみ接続を試みる。使いたいネットワークプロバイダが把握で来ている場合にのみ、このメンバを設定するべきである。それ以外の場合は、オペレーティングシステムからネットワーク名のマップ先プロバイダを特定する。

WNetUseConnection 関数は、構造体の上記以外のメンバを無視する。詳細については、この後の dwFlags パラメータの説明を参照す

    る。
lpUserID
    ［入力］接続に使うユーザー名を表す、NULL で終わる文字列へのポインタを指定する。
    lpUserID が NULL の場合、既定のユーザー名が使われる。(既定のユーザー名は、プロセスのユーザーコンテキストによって提供され

る。)
lpUserID パラメータは、既定のユーザー名やアカウントとは異なるユーザー名やアカウントを割り当てたネットワーク資源に接続したい場合に

    のみ指定する。
    ユーザー名の文字列は、セキュリティコンテキストを表す。セキュリティコンテキストは、ネットワークプロバイダ固有のものでもかまわない。
lpPassword
    ［入力］ネットワーク接続に使うパスワードを表す、NULL で終わる文字列へのポインタを指定する。
    lpPassword が NULL の場合、lpUserID で指定するユーザーの現在の既定パスワードが使われる。
    空の文字列を指定すると、何もパスワードを使わない。
    dwFlags パラメータで CONNECT_INTERACTIVE をセットした場合、パスワードが無効で関数が失敗すると、この関数は、ユーザーにパ

スワードの入力を求めるダイアログボックスを表示する。
dwFlags
［入力］接続を記述する一連のビットフラグを保持する 1 個の DWORD 値を指定する。このパラメータは、次の値の任意の組み合わせで

ある。

値	意味
CONNECT_INTERACTIVE	このフラグをセットすると、オペレーティングシステムが認証目的でユーザーと対話できる。
CONNECT_PROMPT	このフラグは、ユーザー名とパスワードの既定の設定を使わず、ユーザーに入力を求める。 CONNECT_INTERACTIVE をセットしない場合、このフラグは無視される。
CONNECT_REDIRECT	接続時、ローカルデバイスを強制的にリダイレクトする。構造体の lpLocalName メンバで、リダイレクトされるローカルデバイスを指定すると、このフラグは無視される。オペレーティングシステムが、指定されたデバイスをリダイレクトしようとするからである。オペレーティングシステムがローカルデバイスを自動的に選択する場合は、lpAccessName パラメータはリターンバッファを指さなければならない、dwType を RESOURCETYPE_ANY 以外の値に設定しておかなければならない。 ��のフラグをセットしない場合は、ネットワークがローカルデバイスのリダイレクトを必要とする場合にのみ、リダイレクトされるローカルデバイスを自動的に選択する。
CONNECT_UPDATE_PROFILE	このフラグは、ネットワーク資源への接続を記憶するようオペレーティングシステムに指示する。このビットフラグをセットすると、ユーザーのログオン時に、オペレーティングシステムは接続の復元を試みる。記憶されるのは、ローカルデバイスのリダイレクトに成功した接続だけである。成功しなかった接続やデバイスなしの接続は記憶されない。(lpLocalName が NULL である場合、または空の文字列を指している場合に、デバイスなしの接続が行われる。) このビットフラグをセットしない場合、オペレーティングシステムはログイン時に接続を復元しない。

lpAccessName
［出力］接続上でシステム要求を受け取るバッファへのポインタを指定する。
NETRESOURCE 構造体の lpLocalName メンバでローカルデバイスを指定する場合は、このバッファを省略できる。バッファを用意すると、

ローカルデバイスの名前がコピーされる。lpLocalName でデバイスを指定しない場合で、接続先ネットワークがローカルデバイスのリダイレクト

を必要とする場合、または CONNECT_REDIRECT をセットする場合は、このバッファを省略できない。このバッファに、リダイレクトされたロ

ーカルデバイスの名前が格納される。
それ以外の場合は、リモート資源の名前がこのバッファへコピーされる。指定するバッファは、少なくとも lpRemoteName が指す文字列と同

じ大きさでなければならない。
lpBufferSize
［入出力］lpAccessName が指すバッファのサイズ(文字数)を保持する変数へのポインタを指定する。バッファが小さすぎてこの関数が失敗

すると、必要なバッファサイズがこの変数に格納される。
lpResult
［出力］接続に関する追加情報を受け取る 1 個の変数へのポインタを指定する。このパラメータで、次の値を指定する。

値

意味

CONNECT_LOCALDRIVE

このフラグをセットした場合は、ローカルデバイスのリダイレクトを使って接続を確立したことを示す。

lpAccessName パラメータでバッファを指定した場合は、ローカルデバイスの名前をそのバッファへ自動的にコピーする。

戻り値
関数が成功すると、NO_ERROR が返る。
関数が失敗すると、次のいずれかのエラーコードが返る。

値	意味
ERROR_ACCESS_DENIED	ネットワーク資源へのアクセスが拒否された。
ERROR_ALREADY_ASSIGNED	lpLocalName メンバで指定したローカルデバイスはすでにネットワーク資源に接続されている。
ERROR_BAD_DEVICE	lpLocalName メンバで指定した値が無効である。
ERROR_BAD_NET_NAME	lpRemoteName メンバで指定した値は、どのネットワーク資源のプロバイダも受け付けない。資源の名前が無効か、指定した名前の資源が見つからない。
ERROR_BAD_PROVIDER	lpProvider メンバで指定した値がどのプロバイダとも一致しない。
ERROR_CANCELLED	ネットワーク資源のプロバイダのいずれかでユーザーがダイアログボックスを使って接続操作を取り消したか、接続先の資源が接続操作を取り消した。
ERROR_EXTENDED_ERROR	ネットワーク固有のエラーが発生した。エラーの説明を取得するには、WNetGetLastError 関数を使う。
ERROR_INVALID_ADDRESS	呼び出し側が渡したポインタが指すバッファにアクセスできなかった。
ERROR_INVALID_PARAMETER	次のいずれかの原因で、エラーが発生した。 1.lpRemoteName メンバが NULL である。さらに、lpAccessName が NULL 以外で、　 lpBufferSize が NULL であるか 0 を指している。 2.dwType メンバが RESOURCETYPE_DISK と RESOURCETYPE_PRINT のどちらでもない。さらに、dwFlags で CONNECT_REDIRECT がセットされているか、lpLocalName メンバが NULL か、ローカルデバイスのリダイレクトが必要なネットワークに接続しようとしている。
ERROR_INVALID_PASSWORD	指定したパスワードが無効で、CONNECT_INTERACTIVE がセットされていない。
ERROR_MORE_DATA	lpAccessName が指すバッファが小さすぎる。ローカルデバイスをリダイレクトする場合、このバッファはそのローカルデバイスの名前を保持できる大きさでなければならない。ローカルデバイスをリダイレクトしない場合、バッファは lpRemoteName メンバが指す文字列、または lpRemoteName メンバが指すエイリアスを持つ接続可能な資源の名前を保持できる大きさでなければならない。関数がこの値を返した場合、接続は確立されていない。
ERROR_NO_MORE_ITEMS	有効なローカルデバイスがすべて使われているため、ローカルリダイレクトを自動的に選択できない。
ERROR_NO_NET_OR_BAD_PATH	ネットワークコンポーネントが開始されていないか、指定した名前が認識できないために、操作を行えなかった。
ERROR_NO_NETWORK	ネットワークに接続されていない。