非同期実行操作の状態を返します。
構文
HRESULT GetStatus(
HCHAPTER hChapter,
DBASYNCHOP eOperation,
DBCOUNTITEM *pulProgress,
DBCOUNTITEM *pulProgressMax,
DBASYNCHPHASE *peAsynchPhase,
LPOLESTR *ppwszStatusText);
論争
hChapter[in]
チャプター ハンドル。 ポーリング対象のオブジェクトが行セット オブジェクトでない場合、または操作が章に適用されない場合は、DB_NULL_HCHAPTERに設定する必要があります。これはプロバイダーによって無視されます。
eOperation[in]
非同期状態が要求されている操作。 これは次の値である必要があります。
DBASYNCHOP_OPEN-The コンシューマーは、行セットの非同期開始または作成に関する情報、またはデータ ソース オブジェクトの非同期初期化に関する情報を要求します。 プロバイダーが直接 URL バインディングをサポートする OLE DB 2.5 準拠プロバイダーの場合、コンシューマーは、データ ソース、行セット、行、またはストリーム オブジェクトの非同期初期化または作成に関する情報を要求します。
pulProgress[out]
pulProgressMax パラメーターに示されている予想される最大値に対する非同期操作の現在の進行状況を返すメモリへのポインター。
pulProgress の意味の詳細については、peAsynchPhase の説明を参照してください。
pulProgress が null ポインターの場合、進行状況は返されません。
pulProgressMax[out]
pulProgress パラメーターの予想される最大値を返すメモリへのポインター。 この値は、このメソッドの呼び出し間で変更される可能性があります。
pulProgressMax の意味の詳細については、peAsynchPhase の説明を参照してください。
pulProgressMax が null ポインターの場合、予想される最大値は返されません。
peAsynchPhase[out]
非同期操作の進行状況に関する追加情報を返すメモリへのポインター。 有効な値は次のとおりです。
DBASYNCHPHASE_INITIALIZATION-The オブジェクトは初期化フェーズにあります。 引数 pulProgress と pulProgressMax は、推定完了率を示します。 オブジェクトはまだ完全には具体化されていません。 他のインターフェイスを呼び出そうとすると失敗し、オブジェクトでインターフェイスの完全なセットを使用できない可能性があります。 非同期操作が行の更新、削除、または挿入を行うコマンドに対して ICommand::Execute を 呼び出した結果である場合、 cParamSets が 1 より大きい場合、 pulProgress と pulProgressMax は、単一のパラメーター セットまたはパラメーター セットの完全な配列の進行状況を示す可能性があります。
オブジェクト DBASYNCHPHASE_POPULATION-The 作成フェーズにあります。 行セットは完全に初期化され、オブジェクトではさまざまなインターフェイスを使用できますが、行セットにはまだ追加の行が設定されていない可能性があります。 pulProgress と pulProgressMax は、設定された行の数に基づくことができますが、通常、行セットを設定するために必要な時間または労力に基づいています。 したがって、呼び出し元は、最終的な行数ではなく、プロセスにかかる時間の大まかな見積もりとしてこの情報を使用する必要があります。 このフェーズは、行セットの作成中にのみ返されます。データ ソース オブジェクトの初期化や、行の更新、削除、または挿入を行うコマンドの実行によって返されることはありません。
DBASYNCHPHASE_COMPLETE-All オブジェクトの非同期処理が完了しました。 ISSAsynchStatus::GetStatus は、操作の結果を示す HRESULT を返します。 通常、これは、操作が同期的に呼び出された場合に返された HRESULT になります。 非同期操作が行の更新、削除、または挿入を行うコマンドに対して ICommand::Execute を 呼び出した結果である場合、 pulProgress と pulProgressMax は、コマンドの影響を受ける行の合計数と等しくなります。 cParamSets が 1 より大きい場合、これは、実行で指定されたすべてのパラメーター セットの影響を受ける行の合計数です。 peAsynchPhase が null ポインターの場合、状態コードは返されません。
オブジェクトの DBASYNCHPHASE_CANCELED-Asynchronous 処理が中止されました。 ISSAsynchStatus::GetStatus はDB_E_CANCELEDを返します。 非同期操作が、行を更新、削除、または挿入するコマンドに対して ICommand::Execute を 呼び出した結果である場合、 pulProgress は、取り消し前のコマンドの影響を受けるすべてのパラメーター セットの行の合計数と同じです。
ppwszStatusText[in/out]
操作に関する追加情報を含むメモリへのポインター。 プロバイダーは、この値を使用して、操作のさまざまな要素 (たとえば、アクセスされるリソースなど) を区別できます。 この文字列は、データ ソース オブジェクトの DBPROP_INIT_LCID プロパティに従ってローカライズされます。
入力時に ppwszStatusText が null 以外の場合、プロバイダーは ppwszStatusText で識別される特定の要素に関連付けられた状態を返します。 ppwszStatusText が eOperation の要素を示さない場合、プロバイダーは、pulProgress と pulProgressMax が同じ値に設定されたS_OKを返します。 プロバイダーがテキスト識別子に基づいて要素を区別しない場合は、 ppwszStatusText を NULL に設定し、操作全体に関する情報を返します。それ以外の場合、 入力時に ppwszStatusText が null 以外の場合、プロバイダーは ppwszStatusText をそのまま残します。
入力時に ppwszStatusText が null の場合、プロバイダーは ppwszStatusText に操作に関する詳細情報を示す値を設定し、そのような情報が使用できない場合、または ISSAsynchStatus::GetStatus がエラーを返す場合は NULL に設定します。 入力時に ppwszStatusText が null の場合、プロバイダーは状態文字列のメモリを割り当て、このメモリにアドレスを返します。 コンシューマーは、文字列が不要になったときに IMalloc::Free でこのメモリを解放します。
入力時に ppwszStatusText が NULL の場合、状態文字列は返されません。プロバイダーは、操作の任意の要素または操作に関する一般的な情報を返します。
リターン コードの値
S_OK
メソッドが正常に返されました。
peAsynchPhase が DBASYNCHPHASE_INITIALIZATION と等しい場合、オブジェクトはまだ完全には初期化されていません。他のインターフェイスを呼び出そうとすると失敗し、オブジェクトでインターフェイスの完全なセットが使用できない可能性があります。
peAsynchPhase が DBASYNCHPHASE_POPULATION と等しい場合、行セットは完全に初期化され、オブジェクトでインターフェイスの全範囲を使用できます。ただし、行セットに追加の行がまだ設定されていない可能性があります。
peAsynchPhase が DBASYNCHPHASE_COMPLETE と等しい場合、オブジェクトのすべての非同期処理が完了しました。 オブジェクトは完全に初期化され、設定されます。
DB_E_CANCELED
行セットの作成中に非同期処理が取り消されました。 作成は停止しますが、行セットは既に設定されている行に対して有効なままです。
データ ソース オブジェクトの初期化中に非同期処理が取り消されました。 データ ソース オブジェクトが初期化されていない状態です。
無効な引数エラー (E_INVALIDARG)
hChapter パラメーターが正しくありません。
予期しないエラー
ISSAsynchStatus::GetStatus がデータ ソース オブジェクトで呼び出され、 IDBInitialize::Initialize がデータ ソース オブジェクトで呼び出されていません。
ISSAsynchStatus::GetStatus が行セットで呼び出され、 ITransaction::Commit または ITransaction::Abort が呼び出され、オブジェクトがゾンビ状態になっています。
ISSAsynchStatus::GetStatus は、初期化フェーズで非同期的に取り消された行セットで呼び出されました。 行セットはゾンビ状態です。
E_FAIL
プロバイダー固有のエラーが発生しました。
注釈
ISSAsynchStatus::GetStatus メソッドは IDBAsynchStatus::GetStatus メソッドとまったく同じように動作します。ただし、データ ソース オブジェクトの初期化が中止されると、DB_E_CANCELEDではなくE_UNEXPECTEDが返されます (ただし、ISSAsynchStatus::WaitForAsynchCompletion はDB_E_CANCELEDを返します)。 これは、それ以上の初期化操作が試行される可能性があるため、データ ソース オブジェクトが中止後に通常のゾンビ状態のままにならないためです。
行セットが初期化または非同期的に設定されている場合は、このメソッドをサポートする必要があります。
リストされている戻り値に加えて、 ISSAsynchStatus::GetStatus は、操作の成功または失敗を示す、非同期操作を開始したメソッドによって返された HRESULT を返すことができます。
一部の非同期操作では、"finished" と "not finished" 以外の状態を返すことができません。 pulProgressMax を値 1 に設定する必要があります。これは、見積もりのすべてまたは何もない粒度を示すので、回答は 0/1 または 1/1 になります。
プロバイダーは、連続する呼び出しで pulProgressMax を 変更し、以前よりも小さい比率を返す可能性があります。これが、タスクの完了度の見積もりの向上を反映している場合です。
プロバイダーは、それ以上の精度を保証する義務はありませんが、完了の妥当な見積もりが可能な場合は、これを行うことをお勧めします。 この機能の主な用途は、ユーザーに進行状況のフィードバックを提供する可能性が高いため、このような作業によってユーザー インターフェイスの品質が向上します。 目に見えない長時間実行されるタスクに関するフィードバックの品質によって、ユーザーの満足度が向上します。
初期化されたデータ ソース オブジェクトまたは設定された行セットで ISSAsynchStatus::GetStatus を呼び出すか、DBASYNCHOP_OPEN以外の eOperation の値を渡すと、pulProgress と pulProgressMax が同じ値に設定されたS_OKが返されます。 ISSAsynchStatus::GetStatus が、行を更新、削除、または挿入するコマンドの実行から作成されたオブジェクトに対して呼び出された場合、pulProgress と pulProgressMax の両方が、コマンドの影響を受ける行の合計数を示します。