ホーム › Networking.BackgroundIntelligentTransferService › IBackgroundCopyGroup

IBackgroundCopyGroup

COM

IID1ded80a7-53ea-424f-8a04-17fea9adc4f5継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IBackgroundCopyGroup インターフェイスは、グループを管理するために使用します。グループにはダウンロードジョブが含まれます。たとえば、グループへのジョブの追加、グループのプロパティの設定、ダウンロードキュー内でのグループの開始や停止などを行えます。

メソッド 15

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

vtbl 3 HRESULT GetProp(GROUPPROP propID, VARIANT* pvarVal)

GetProp メソッドは、グループからプロパティ値を取得するために使用します。

propID	GROUPPROP	in	取得するプロパティを指定します。プロパティの一覧については、GROUPPROP 列挙型を参照してください。
pvarVal	VARIANT*	out	プロパティ値。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	プロパティを正常に取得しました。
E_NOTIMPL	サポートされていないプロパティを指定しました。
E_INVALIDARG	プロパティと互換性のないバリアント型を指定しました。

vtbl 4 HRESULT SetProp(GROUPPROP propID, VARIANT* pvarVal)

SetProp メソッドは、グループのプロパティに値を設定するために使用します。

propID	GROUPPROP	in	設定するプロパティを指定します。プロパティの一覧については、GROUPPROP 列挙型を参照してください。
pvarVal	VARIANT*	in	プロパティ値。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	プロパティを正常に設定しました。
E_NOTIMPL	サポートされていないプロパティを指定しました。
E_INVALIDARG	プロパティと互換性のないバリアント型を指定しました。

vtbl 5 HRESULT GetProgress(DWORD dwFlags, DWORD* pdwProgress)

GetProgress メソッドは、ダウンロードの進行状況を取得するために使用します。

dwFlags

DWORD

取得する進行状況の種類。次のいずれかのフラグを指定します。

値	意味
QM_PROGRESS_PERCENT_DONE	ダウンロードの完了率を返します。
QM_PROGRESS_SIZE_DONE	ダウンロード済みのバイト数を返します。
QM_PROGRESS_TIME_DONE	サポートされていません。

pdwProgress

DWORD*

out

ダウンロードの進行状況。進行状況は、dwFlags に応じて、ダウンロード済みのバイト数またはダウンロードの完了率を表します。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループの進行状況を正常に取得しました。
E_NOTIMPL	dwFlags パラメーターに QM_PROGRESS_TIME_DONE を指定することはできません。

vtbl 6 HRESULT GetStatus(DWORD* pdwStatus, DWORD* pdwJobIndex)

GetStatus メソッドは、グループの状態を取得するために使用します。

pdwStatus

DWORD*

out

グループの状態。状態には次のフラグの 1 つ以上が設定されます。

値	意味
QM_STATUS_GROUP_FOREGROUND	QMGR はグループをフォアグラウンドでダウンロードしています。
QM_STATUS_GROUP_INCOMPLETE	QMGR はまだグループをダウンロード中です。
QM_STATUS_GROUP_SUSPENDED	グループは一時停止されています。
QM_STATUS_GROUP_ERROR	グループの処理中にエラーが発生しました。

pdwJobIndex

DWORD*

out

実行中の現在のジョブ。インデックスは常に 0 です (グループには 1 つのジョブしか含められません)。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループの状態を正常に取得しました。

vtbl 7 HRESULT GetJob(GUID jobID, IBackgroundCopyJob1** ppJob)

GetJob メソッドは、グループからジョブを取得するために使用します。

jobID	GUID	in	取得するジョブを指定します。
ppJob	IBackgroundCopyJob1**	out	IBackgroundCopyJob1 インターフェイスポインターへのポインター。このインターフェイスを使用して、ファイルの追加やジョブの状態の取得を行います。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループからジョブを正常に取得しました。
QM_E_ITEM_NOT_FOUND	グループ内にジョブが見つかりませんでした。

vtbl 8 HRESULT SuspendGroup()

SuspendGroup メソッドは、ダウンロードキュー内のグループを一時停止するために使用します。新しいグループ、エラー状態のグループ、およびダウンロードが完了したグループは自動的に一時停止されます。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ダウンロードキュー内のグループを正常に一時停止しました。

vtbl 9 HRESULT ResumeGroup()

ResumeGroup メソッドは、ダウンロードキュー内で一時停止されているグループを開始するために使用します。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ダウンロードキュー内のグループを正常に再開しました。

vtbl 10 HRESULT CancelGroup()

CancelGroup メソッドは、キューからグループを削除するために使用します。このメソッドを呼び出す前にダウンロードが完了していたファイルは、クライアントから利用できます。グループはいつでもキャンセルできますが、いったんキャンセルすると復元できません。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループを正常にキャンセルしました。

vtbl 11 HRESULT get_Size(DWORD* pdwSize)

get_Size メソッドは、グループ内のダウンロード対象となるすべてのファイルのサイズを取得するために使用します。

pdwSize

DWORD*

out

グループ内のダウンロード対象となるすべてのファイルの合計サイズ (バイト単位)。QMGR がサイズを判別できない場合は 0 になります。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループのサイズを正常に取得しました。

vtbl 12 HRESULT get_GroupID(GUID* pguidGroupID)

get_GroupID メソッドは、グループの識別子を取得するために使用します。

pguidGroupID

GUID*

out

ダウンロードキュー内でグループを一意に識別する GUID。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループを識別する GUID を正常に取得しました。

vtbl 13 HRESULT CreateJob(GUID guidJobID, IBackgroundCopyJob1** ppJob)

CreateJob メソッドは、グループに新しいジョブを追加するために使用します。グループには 1 つのジョブしか含められません。

guidJobID	GUID	in	グループおよびキュー内でジョブを一意に識別します。
ppJob	IBackgroundCopyJob1**	out	IBackgroundCopyJob1 インターフェイスポインターへのポインター。このインターフェイスを使用して、ファイルの追加やジョブの状態の確認を行います。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブを正常に作成しました。
QM_E_INVALID_STATE	ジョブは既に実行中です。
E_NOTIMPL	1 つのグループにつきジョブは 1 つのみ許可されます。

vtbl 14 HRESULT EnumJobs(DWORD dwFlags, IEnumBackgroundCopyJobs1** ppEnumJobs)

EnumJobs メソッドは、グループ内のジョブの一覧を取得するために使用します。この一覧には 1 つのジョブのみが含まれます。

dwFlags	DWORD	in	0 を指定する必要があります。
ppEnumJobs	IEnumBackgroundCopyJobs1**	out	IEnumBackgroundCopyJobs1 インターフェイスポインターへのポインター。このインターフェイスを使用して、ジョブの一覧を列挙します。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループ内のジョブを正常に列挙しました。
E_NOTIMPL	dwFlags パラメーターは 0 でなければなりません。

vtbl 15 HRESULT SwitchToForeground()

SwitchToForeground メソッドは、グループをバックグラウンドではなくフォアグラウンドでダウンロードするために使用します。

戻り値

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	グループをフォアグラウンド処理に正常に切り替えました。

vtbl 16 HRESULT QueryNewJobInterface(GUID* iid, IUnknown** pUnk)

iid	GUID*	in	新しいジョブインターフェイスの識別子(IID)へのポインタ。
pUnk	IUnknown**	out	要求したインターフェイスを実装するオブジェクトを受け取る出力ポインタ。

vtbl 17 HRESULT SetNotificationPointer(GUID* iid, IUnknown* pUnk)

iid	GUID*	in	通知コールバックインターフェイスの識別子(IID)へのポインタ。
pUnk	IUnknown*	in	通知を受け取るコールバックオブジェクトのIUnknownポインタ。NULLで解除可能。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IBackgroundCopyGroup "{1DED80A7-53EA-424F-8A04-17FEA9ADC4F5}"
#usecom global IBackgroundCopyGroup IID_IBackgroundCopyGroup "{}"
#comfunc global IBackgroundCopyGroup_GetProp                 3 int,var
#comfunc global IBackgroundCopyGroup_SetProp                 4 int,var
#comfunc global IBackgroundCopyGroup_GetProgress             5 int,var
#comfunc global IBackgroundCopyGroup_GetStatus               6 var,var
#comfunc global IBackgroundCopyGroup_GetJob                  7 int,sptr
#comfunc global IBackgroundCopyGroup_SuspendGroup            8
#comfunc global IBackgroundCopyGroup_ResumeGroup             9
#comfunc global IBackgroundCopyGroup_CancelGroup             10
#comfunc global IBackgroundCopyGroup_get_Size                11 var
#comfunc global IBackgroundCopyGroup_get_GroupID             12 var
#comfunc global IBackgroundCopyGroup_CreateJob               13 int,sptr
#comfunc global IBackgroundCopyGroup_EnumJobs                14 int,sptr
#comfunc global IBackgroundCopyGroup_SwitchToForeground      15
#comfunc global IBackgroundCopyGroup_QueryNewJobInterface    16 var,sptr
#comfunc global IBackgroundCopyGroup_SetNotificationPointer  17 var,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IBackgroundCopyGroup "{1DED80A7-53EA-424F-8A04-17FEA9ADC4F5}"
#usecom global IBackgroundCopyGroup IID_IBackgroundCopyGroup "{}"
#comfunc global IBackgroundCopyGroup_GetProp                 3 int,sptr
#comfunc global IBackgroundCopyGroup_SetProp                 4 int,sptr
#comfunc global IBackgroundCopyGroup_GetProgress             5 int,sptr
#comfunc global IBackgroundCopyGroup_GetStatus               6 sptr,sptr
#comfunc global IBackgroundCopyGroup_GetJob                  7 int,sptr
#comfunc global IBackgroundCopyGroup_SuspendGroup            8
#comfunc global IBackgroundCopyGroup_ResumeGroup             9
#comfunc global IBackgroundCopyGroup_CancelGroup             10
#comfunc global IBackgroundCopyGroup_get_Size                11 sptr
#comfunc global IBackgroundCopyGroup_get_GroupID             12 sptr
#comfunc global IBackgroundCopyGroup_CreateJob               13 int,sptr
#comfunc global IBackgroundCopyGroup_EnumJobs                14 int,sptr
#comfunc global IBackgroundCopyGroup_SwitchToForeground      15
#comfunc global IBackgroundCopyGroup_QueryNewJobInterface    16 sptr,sptr
#comfunc global IBackgroundCopyGroup_SetNotificationPointer  17 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。