Win32 API 日本語リファレンス
ホーム › Storage.OfflineFiles › IOfflineFilesConnectionInfo

IOfflineFilesConnectionInfo

COM
📘 Microsoft Learn (日本語) · English
IIDefb23a09-a867-4be8-83a6-86969a7d0856継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

オフラインファイルのオンライン/オフライン遷移の動作に関連する、クエリ機能と操作機能を提供します。

メソッド 4

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetConnectState(OFFLINEFILES_CONNECT_STATE* pConnectState, OFFLINEFILES_OFFLINE_REASON* pOfflineReason)

項目がオンラインかオフラインかを判定し、オフラインの場合はその理由を取得します。

pConnectStateOFFLINEFILES_CONNECT_STATE*out

項目がオンラインかオフラインかを示す OFFLINEFILES_CONNECT_STATE 列挙値を受け取ります。

メモ この値は、Windows エクスプローラーの「オフライン状態」プロパティの値を設定します。
pOfflineReasonOFFLINEFILES_OFFLINE_REASON*out

項目がオフラインの場合、このパラメーターは、オフラインである理由を示す OFFLINEFILES_OFFLINE_REASON 列挙値を受け取ります。

メモ この値は、状態がオフラインのときに Windows エクスプローラーの「オフライン状態」プロパティの値に付加される括弧付きの接尾辞を生成します。

戻り値

成功した場合は S_OK、それ以外の場合はエラー値を返します。

解説(Remarks)

このメソッドは、項目に接続状態の情報が存在することを必要とします。このメソッドの呼び出し時点でその情報が利用できない場合、メソッド呼び出しは現在の接続状態を取得するためにキャッシュ項目への追加のクエリを開始します。

vtbl 4 HRESULT SetConnectState(HWND hwndParent, DWORD dwFlags, OFFLINEFILES_CONNECT_STATE ConnectState)

項目の接続状態を設定します。

hwndParentHWNDinoptional資格情報の要求ダイアログなど、対話的なユーザーインターフェイス要素に使用する親ウィンドウのハンドルを指定します。このパラメーターには NULL を指定できます。dwFlags パラメーターに OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが指定されていない場合、このパラメーターは無視されます。
dwFlagsDWORDin

次のフラグ値の 1 つ以上を指定します。

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE (0x00000001)

操作が必要に応じてユーザーインターフェイス要素を表示することを許可する場合に、このフラグを設定します。例としては、システムの資格情報要求ダイアログがあります。このフラグが設定されている場合、表示されるユーザーインターフェイス要素の親ウィンドウとして hwndParent パラメーターの値が使用されます。

OFFLINEFILES_TRANSITION_FLAG_CONSOLE (0x00000002)

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されていない場合、このフラグは無視されます。OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されている場合、このフラグは、生成される UI を操作の呼び出し元プロセスに関連付けられたコンソールウィンドウに出力することを示します。

ConnectStateOFFLINEFILES_CONNECT_STATEin

次の OFFLINEFILES_CONNECT_STATE 列挙値のいずれかを指定します。

OFFLINEFILES_CONNECT_STATE_OFFLINE

項目をオフラインに遷移させます。オフラインファイルによってキャッシュされていないファイルに対して現在開いているハンドルが存在する場合、この操作は失敗することに注意してください。IOfflineFilesConnectionInfo::TransitionOffline メソッドを使用すると、そのようなハンドルを閉じる動作を制御できます。

OFFLINEFILES_CONNECT_STATE_ONLINE

可能であれば項目をオンラインに遷移させます。これは IOfflineFilesConnectionInfo::TransitionOnline メソッドと同等です。

戻り値

成功した場合は S_OK、それ以外の場合はエラー値を返します。

解説(Remarks)

オンラインからオフラインへの遷移における、開いているハンドルの検出と処理をより細かく制御できるため、このメソッドよりも IOfflineFilesConnectionInfo::TransitionOnline メソッドおよび IOfflineFilesConnectionInfo::TransitionOffline メソッドの使用が推奨されます。

vtbl 5 HRESULT TransitionOnline(HWND hwndParent, DWORD dwFlags)

可能であれば項目をオンラインに遷移させます。

hwndParentHWNDinoptional資格情報の要求ダイアログなど、対話的なユーザーインターフェイス要素に使用する親ウィンドウのハンドルを指定します。このパラメーターには NULL を指定できます。dwFlags パラメーターに OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが指定されていない場合、このパラメーターは無視されます。
dwFlagsDWORDin

次のフラグ値の 1 つ以上を指定します。

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE (0x00000001)

操作が必要に応じてユーザーインターフェイス要素を表示することを許可する場合に、このフラグを設定します。例としては、システムの資格情報要求ダイアログがあります。このフラグが設定されている場合、表示されるユーザーインターフェイス要素の親として hwndParent の値が使用されます。

OFFLINEFILES_TRANSITION_FLAG_CONSOLE (0x00000002)

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されていない場合、このフラグは無視されます。OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されている場合、このフラグは、生成される UI を操作の呼び出し元プロセスに関連付けられたコンソールウィンドウに出力することを示します。

戻り値

成功した場合は S_OK、それ以外の場合はエラー値を返します。

解説(Remarks)

オンラインに遷移するのは項目だけではなく、項目のスコープ全体である点に注意してください。項目のスコープは、その項目に最も近い上位の共有フォルダーとして定義されます。

vtbl 6 HRESULT TransitionOffline(HWND hwndParent, DWORD dwFlags, BOOL bForceOpenFilesClosed, BOOL* pbOpenFilesPreventedTransition)

可能であれば項目をオフラインに遷移させます。

hwndParentHWNDinoptional資格情報の要求ダイアログなど、対話的なユーザーインターフェイス要素に使用する親ウィンドウのハンドルを指定します。このパラメーターには NULL を指定できます。OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されていない場合、このパラメーターは無視されます。
dwFlagsDWORDin

次のフラグ値の 1 つ以上を指定します。

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE (0x00000001)

操作が必要に応じてユーザーインターフェイス要素を表示することを許可する場合に、このフラグを設定します。例としては、システムの資格情報要求ダイアログがあります。このフラグが設定されている場合、表示されるユーザーインターフェイス要素の親として hwndParent の値が使用されます。

OFFLINEFILES_TRANSITION_FLAG_CONSOLE (0x00000002)

OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されていない場合、このフラグは無視されます。OFFLINEFILES_TRANSITION_FLAG_INTERACTIVE フラグが設定されている場合、このフラグは、生成される UI を操作の呼び出し元プロセスに関連付けられたコンソールウィンドウに出力することを示します。

bForceOpenFilesClosedBOOLin

既定では、オフラインファイルによってキャッシュされていないファイルに対して開いているハンドルが存在すると、オフラインへの遷移は行われません。このパラメーターが TRUE の場合、操作はそれらのファイルハンドルを強制的に閉じ、スコープをオフラインに遷移できるようにします。

メモ ファイルハンドルを強制的に閉じると、それらのファイルを使用しているアプリケーションによっては、予期しない結果を招くおそれがあります。
pbOpenFilesPreventedTransitionBOOL*out開いているファイルによって遷移が妨げられた場合は TRUE を、それ以外の場合は FALSE を受け取ります。この値は、bForceOpenFilesClosed パラメーターに FALSE を指定した場合にのみ意味があります。

戻り値

成功した場合は S_OK、それ以外の場合はエラー値を返します。

解説(Remarks)

オフラインに遷移するのは項目だけではなく、項目のスコープ全体である点に注意してください。項目のスコープは、その項目に最も近い上位の共有フォルダーとして定義されます。

開いているハンドルによってオフラインへの遷移が妨げられた場合、この関数は成功値を返し、*pbOpenFilesPreventTransition は TRUE を受け取ります。

このメソッドの使用例を次に示します。Windows Vista のエクスプローラーの「オフライン作業」ボタンによってスコープをオフラインに遷移させる場合、まず bForceOpenFilesClosed パラメーターに FALSE を指定してこのメソッドが呼び出されます。開いているファイルによってオフラインへの遷移が妨げられたことが関数から示された場合、Windows エクスプローラーは、それらのファイルを強制的に閉じて再試行するかどうかをユーザーに確認するダイアログを表示します。ユーザーが肯定的に応答した場合、bForceOpenFilesClosed パラメーターに TRUE を指定して関数呼び出しが繰り返されます。

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IOfflineFilesConnectionInfo "{EFB23A09-A867-4BE8-83A6-86969A7D0856}"
#usecom global IOfflineFilesConnectionInfo IID_IOfflineFilesConnectionInfo "{}"
#comfunc global IOfflineFilesConnectionInfo_GetConnectState    3 var,var
#comfunc global IOfflineFilesConnectionInfo_SetConnectState    4 sptr,int,int
#comfunc global IOfflineFilesConnectionInfo_TransitionOnline   5 sptr,int
#comfunc global IOfflineFilesConnectionInfo_TransitionOffline  6 sptr,int,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。