Функция 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 — пользователь запрашивает сведения об асинхронном открытии или заполнении набора строк или асинхронной инициализации объекта источника данных. Если поставщик совместим с OLE DB 2.5 и поддерживает прямую привязку URL-адресов, то потребитель запрашивает сведения об асинхронной инициализации или заполнении объекта источника данных, набора строк, строки или потока.
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 могут указывать ход выполнения для единого набора параметров или для полного массива наборов параметров.
DBASYNCHPHASE_POPULATION — объект находится в стадии заполнения. Несмотря на то что набор строк полностью инициализирован, а объекту доступен полный диапазон интерфейсов, в наборе строк могут быть дополнительные, еще не заполненные строки. И хотя параметры pulProgress и pulProgressMax могут быть основаны на числе заполненных строк, обычно в их основе лежит время или действие, которое необходимо, чтобы заполнить набор строк. Поэтому вызывающий должен использовать эти сведения в качестве приблизительной оценки того, сколько времени может быть затрачено на выполнение процесса, а не в качестве эквивалента счетчика строк. Эта стадия возвращается только во время заполнения набора строк. Она никогда не возвращается при инициализации объекта источника данных или выполнении команды, которая обновляет, удаляет или вставляет строки.
DBASYNCHPHASE_COMPLETE — вся асинхронная обработка объекта завершена. Метод ISSAsynchStatus::GetStatus возвращает значение 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, поставщик возвращает S_OK с параметрами pulProgress и pulProgressMax, которым задано такое же значение. Если поставщик не различает элементы по текстовому идентификатору, то он устанавливает параметру ppwszStatusText значение NULL и возвращает сведения об операции в целом; в противном случае, если значение параметра ppwszStatusText на входе не равно NULL, поставщик не изменяет параметр ppwszStatusText.
Если значение параметра ppwszStatusText на входе равно NULL, то поставщик устанавливает параметру ppwszStatusText значение, указывающее больший объем сведений об операции, либо значение NULL, если такие сведения недоступны или если метод ISSAsynchStatus::GetStatus возвращает ошибку. Когда значение параметра 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
Метод ISSAsynchStatus::GetStatus был вызван для объекта источника данных, а метод IDBInitialize::Initialize — не был.Метод ISSAsynchStatus::GetStatus был вызван для набора строк, затем был вызван метод ITransaction::Commit или ITransaction::Abort, а объект находится в состоянии зомби.
Метод ISSAsynchStatus::GetStatus был вызван для набора строк, который был асинхронно отменен на стадии его инициализации. Набор строк находится в состоянии зомби.
E_FAIL
Произошла ошибка, зависящая от поставщика.
Замечания
Метод ISSAsynchStatus::GetStatus ведет себя точно так, как ожидает метод IDBAsynchStatus::GetStatus: если инициализация объекта источника данных прервана, возвращается E_UNEXPECTED, а не DB_E_CANCELED (хотя метод ISSAsynchStatus::WaitForAsynchCompletion возвратит DB_E_CANCELED). Происходит это потому, что после прерывания объект источника данных не остается в обычном состоянии зомби. Делается этого для того, чтобы можно было попытаться выполнить последующие операции инициализации.
Если набор строк инициализируется или заполняется асинхронно, он должен поддерживать этот метод.
Помимо указанных возвращаемых значений метод ISSAsynchStatus::GetStatus может возвращать любой HRESULT, который был бы возвращен методом, инициировавшим асинхронную операцию, с указанием успешного или неуспешного завершения операции.
Некоторые асинхронные операции могут быть не в состоянии возвращать какие-либо состояния, кроме «завершена» и «не завершена». Они должны задавать параметру pulProgressMax значение 1, указывая, что их оценка основана на гранулярности «все или ничего», то есть их ответ будет либо 0/1, либо 1/1.
Поставщик может изменить параметр pulProgressMax при последующих вызовах и даже возвратить меньшее соотношение, чем раньше, если это отражает улучшение оценки степени выполнения задачи.
Поставщик не обязан гарантировать более высокую точность, но ему рекомендуется стремиться к ней в тех случаях, когда возможно рассчитать разумные оценки завершения. Такие действия повышают качество пользовательского интерфейса, поскольку основным вариантом применения этой функции является информирования пользователя о ходе выполнения. Пользователи будут довольны повышением качества обратной связи по невидимой и долгосрочной задаче.
В случае вызова метода ISSAsynchStatus::GetStatus для инициализированного объекта источника данных или заполненного набора строк, либо передачи значения для параметра eOperation, отличного от DBASYNCHOP_OPEN, возвращается S_OK с параметрами pulProgress и pulProgressMax, которым установлено такое же значение. Если метод ISSAsynchStatus::GetStatus вызывается для объекта, созданного в результате выполнения команды, которая обновляет, удаляет или уставляет строки, оба параметра pulProgress и pulProgressMax указывают общее число строк, затронутых при выполнении этой команды.