ISSAsynchStatus::GetStatus (OLE DB)

非同期に実行されている操作の状態を返します。

構文

HRESULT GetStatus(
        HCHAPTER hChapter,
        DBASYNCHOP eOperation,
        DBCOUNTITEM *pulProgress,
        DBCOUNTITEM *pulProgressMax,
        DBASYNCHPHASE *peAsynchPhase,
        LPOLESTR *ppwszStatusText);

引数

• hChapter[in]
  チャプタ ハンドル。ポーリングされているオブジェクトが行セット オブジェクトではないか、操作がチャプタに適用されない場合は、この引数を DB_NULL_HCHAPTER に設定する必要があります。プロバイダでは、この設定が無視されます。

• eOperation[in]
  非同期状態が要求されている操作。この引数には、

  DBASYNCHOP_OPEN を設定する必要があります。コンシューマは、この設定により、行セットを開くか行セットにデータを設定する非同期操作に関する情報、またはデータ ソース オブジェクトを初期化する非同期操作に関する情報を要求します。プロバイダが URL の直接バインドをサポートする OLE DB 2.5 に準拠したプロバイダの場合、コンシューマは、データ ソース、行セット、行、またはストリーム オブジェクトの初期化やデータ設定の非同期操作に関する情報を要求します。

• pulProgress[out]
  pulProgressMax パラメータで示される予想最大値と比較した、現在の非同期操作の進行状況を返すメモリへのポインタ。pulProgress の詳細については、peAsynchPhase の説明を参照してください。

  pulProgress に NULL ポインタを指定すると、進行状況は返されません。

• pulProgressMax[out]
  pulProgress パラメータの予想最大値を返すメモリへのポインタ。この値は、このメソッドを呼び出すたびに変化することがあります。pulProgressMax の詳細については、peAsynchPhase の説明を参照してください。

  pulProgressMax に NULL ポインタを指定すると、予想最大値は返されません。

• peAsynchPhase[out]
  非同期操作の進行状況に関する詳細情報を返すメモリへのポインタ。有効な値は次のとおりです。

  DBASYNCHPHASE_INITIALIZATION は、オブジェクトが初期化フェーズにあることを示します。引数 pulProgress と pulProgressMax は、完了の推定比率を示します。オブジェクトはまだ完全に具体化されていません。そのため、他のインターフェイスの呼び出しを試みると失敗したり、このオブジェクトのすべてのインターフェイスを使用できない場合があります。行を更新、削除、または挿入するコマンドに対して ICommand::Execute を呼び出すことにより非同期操作が実行された場合、および cParamSets が 1 より大きい場合、pulProgress と pulProgressMax は、パラメータの 1 つのセットの進行状況か、パラメータ セットの配列全体の進行状況を示します。

  DBASYNCHPHASE_POPULATION は、オブジェクトが作成フェーズにあることを示します。行セットは完全に初期化されていて、オブジェクトのすべてのインターフェイスを使用できますが、まだ行セットに追加されていない行が存在する場合があります。pulProgress と pulProgressMax は、設定した行数に基づくこともできますが、通常は、行セットの設定に必要な時間または作業に基づきます。そのため、呼び出し元では最終的な行数ではなく、処理にかかる時間の大まかな推定値としてこの情報を使用する必要があります。このフェーズが返されるのは、行セットの設定中のみです。データ ソース オブジェクトの初期化中や、行を更新、削除、または挿入するコマンドの実行により返されることはありません。

  DBASYNCHPHASE_COMPLETE は、オブジェクトのすべての非同期処理が完了したことを示します。ISSAsynchStatus::GetStatus により、操作の結果を示す HRESULT が返されます。通常、この HRESULT は、同期をとって操作を呼び出した場合に返される HRESULT です。行を更新、削除、または挿入するコマンドに対して ICommand::Execute を呼び出すことにより非同期操作が実行された場合、pulProgress と pulProgressMax は、そのコマンドで処理された行の合計数と等しくなります。cParamSets が 1 より大きい場合、この値は、コマンドの実行で指定したすべてのパラメータ セットによって処理された行の合計数になります。peAsynchPhase に NULL ポインタを指定すると、状態コードは返されません。

  DBASYNCHPHASE_CANCELED は、オブジェクトの非同期処理が中止されたことを示します。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 パラメータが正しくありません。

• E_UNEXPECTED
  IDBInitialize::Initialize が呼び出されていないデータ ソース オブジェクトに対して ISSAsynchStatus::GetStatus が呼び出されたことを示します。

  また、ITransaction::Commit や ITransaction::Abort が呼び出された行セットに対して ISSAsynchStatus::GetStatus が呼び出されたことを示している場合もあります。この場合、オブジェクトはゾンビ状態になります。

  初期化フェーズで非同期にキャンセルされた行セットに対して ISSAsynchStatus::GetStatus が呼び出された場合もこの値が返されます。行セットはゾンビ状態になります。

• E_FAIL
  プロバイダ固有のエラーが発生しました。

説明

ISSAsynchStatus::GetStatus メソッドの動作は、IDBAsynchStatus::GetStatus メソッドとまったく同じです。ただし、データ ソース オブジェクトの初期化が中止された場合は、DB_E_CANCELED ではなく E_UNEXPECTED が返されます (ISSAsynchStatus::WaitForAsynchCompletion の場合は DB_E_CANCELED が返されます)。これは、初期化の中止後、追加の初期化操作が試行される場合に備えて、データ ソース オブジェクトの状態が通常のゾンビ状態のままにならないためです。

行セットを初期化またはデータ設定する非同期操作では、このメソッドをサポートする必要があります。

ISSAsynchStatus::GetStatus では、上記の戻り値に加えて、非同期操作を開始するメソッドから返されることになる、操作の成功または失敗を示す HRESULT を返すことができます。

一部の非同期操作では、"完了" または "未完了" 以外の状態を返すことができません。これらの操作では、pulProgressMax の値を 1 に設定する必要があります。これにより、推定値の粒度がすべて完了したか、まったく処理されていないかの状態になるので、0/1 または 1/1 が返されます。

プロバイダでは、タスクの完了の度合いに応じて推定値が向上する場合、これを pulProgressMax に反映して、連続した呼び出しでこの値が変化したり、場合のよっては前回よりも少ない比率を返すこともあります。

プロバイダは、より正確な値を保証することが義務付けられているわけではありませんが、可能な場合は妥当な推定完了率を返すように設定されています。この関数の主な目的は、ユーザーへの進行状況のフィードバックを提供することなので、このような動作によりユーザー インターフェイスの品質が向上します。非表示で行われる、実行時間が長いタスクに対するフィードバックの品質を向上することで、ユーザーの満足度も向上します。

初期化されたデータ ソース オブジェクトまたはデータが設定された行セットに対して ISSAsynchStatus::GetStatus を呼び出すか、eOperation に BASYNCHOP_OPEN 以外の値を渡すと、pulProgress と pulProgressMax に同じ値が設定され、S_OK が返されます。行を更新、削除、または挿入するコマンドの実行により作成されたオブジェクトに対して ISSAsynchStatus::GetStatus を呼び出した場合、pulProgress と pulProgressMax は、どちらもそのコマンドによって処理された行の合計数を示します。

関連項目

参照

ISSAsynchStatus (OLE DB)

概念

非同期操作の実行