Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Retorna o status de uma operação de execução assíncrona.
Sintaxe
HRESULT GetStatus(
HCHAPTER hChapter,
DBASYNCHOP eOperation,
DBCOUNTITEM *pulProgress,
DBCOUNTITEM *pulProgressMax,
DBASYNCHPHASE *peAsynchPhase,
LPOLESTR *ppwszStatusText);
Argumentos
hChapter[in]
O identificador do capítulo. Se o objeto que está sendo sondado não for um objeto de conjunto de linhas ou a operação não se aplicar a um capítulo, isso deverá ser definido como DB_NULL_HCHAPTER, o que é ignorado pelo provedor.
eOperation[in]
A operação para a qual o status assíncrono está sendo solicitado. Esse deve ser o seguinte valor:
DBASYNCHOP_OPEN-The consumidor solicita informações sobre a abertura assíncrona ou população de um conjunto de linhas ou sobre a inicialização assíncrona de um objeto de fonte de dados. Se o provedor for um provedor compatível com OLE DB 2.5 que dá suporte à associação direta de URL, o consumidor solicitará informações sobre a inicialização assíncrona ou população de uma fonte de dados, conjunto de linhas, linha ou objeto de fluxo.
pulProgress[out]
Um ponteiro para a memória na qual retornar o progresso atual da operação assíncrona em relação ao máximo esperado indicado no parâmetro pulProgressMax . Para obter mais informações sobre o significado do pulProgress, consulte a descrição de peAsynchPhase.
Se pulProgress for um ponteiro nulo, nenhum progresso será retornado.
pulProgressMax[out]
Um ponteiro para a memória na qual retornar o valor máximo esperado do parâmetro pulProgress . Esse valor pode ser alterado entre chamadas para esse método. Para obter mais informações sobre o significado de pulProgressMax, consulte a descrição de peAsynchPhase.
Se pulProgressMax for um ponteiro nulo, nenhum valor máximo esperado será retornado.
peAsynchPhase[out]
Um ponteiro para a memória na qual retornar informações adicionais sobre o progresso da operação assíncrona. Os valores válidos incluem:
DBASYNCHPHASE_INITIALIZATION-The objeto está em uma fase de inicialização. Os argumentos pulProgress e pulProgressMax indicam uma taxa estimada de conclusão. O objeto ainda não foi totalmente materializado. A tentativa de chamar outras interfaces pode falhar e o conjunto completo de interfaces pode não estar disponível no objeto. Se a operação assíncrona foi resultado da chamada ICommand::Execute para um comando que atualiza, exclui ou insere linhas e se cParamSets for maior que 1, pulProgress e pulProgressMax poderá indicar o progresso para um único conjunto de parâmetros ou para a matriz completa de conjuntos de parâmetros.
DBASYNCHPHASE_POPULATION-The objeto está em uma fase de população. Embora o conjunto de linhas seja totalmente inicializado e toda a gama de interfaces esteja disponível no objeto, pode haver linhas adicionais ainda não preenchidas no conjunto de linhas. Embora pulProgress e pulProgressMax possam ser baseados no número de linhas preenchidas, eles geralmente são baseados no tempo ou esforço necessário para preencher o conjunto de linhas. Portanto, um chamador deve usar essas informações como uma estimativa aproximada de quanto tempo o processo pode levar, não a contagem de linhas eventual. Essa fase é retornada somente durante a população de um conjunto de linhas; nunca é retornado na inicialização de um objeto de fonte de dados ou pela execução de um comando que atualiza, exclui ou insere linhas.
DBASYNCHPHASE_COMPLETE-All processamento assíncrono do objeto foi concluído. ISSAsynchStatus::GetStatus retorna um HRESULT que indica o resultado da operação. Normalmente, esse será o HRESULT que teria sido retornado se a operação tivesse sido chamada de forma síncrona. Se a operação assíncrona foi resultado da chamada ICommand::Execute para um comando que atualiza, exclui ou insere linhas, pulProgress e pulProgressMax são iguais ao número total de linhas afetadas pelo comando. Se cParamSets for maior que 1, esse será o número total de linhas afetadas por todos os conjuntos de parâmetros especificados na execução. Se peAsynchPhase for um ponteiro nulo, nenhum código de status será retornado.
DBASYNCHPHASE_CANCELED-Asynchronous processamento do objeto foi anulado. ISSAsynchStatus::GetStatus retorna DB_E_CANCELED. Se a operação assíncrona foi resultado da chamada ICommand::Execute para um comando que atualiza, exclui ou insere linhas, pulProgress é igual ao número total de linhas, para todos os conjuntos de parâmetros, afetados pelo comando antes do cancelamento.
ppwszStatusText[in/out]
Um ponteiro para a memória que contém informações adicionais sobre a operação. Um provedor pode usar esse valor para distinguir entre diferentes elementos de uma operação, por exemplo, recursos diferentes sendo acessados. Essa cadeia de caracteres é localizada de acordo com a propriedade DBPROP_INIT_LCID no objeto da fonte de dados.
Se ppwszStatusText não for nulo na entrada, o provedor retornará o status associado ao elemento específico identificado por ppwszStatusText. Se ppwszStatusText não indicar um elemento de eOperation, o provedor retornará S_OK com pulProgress e pulProgressMax definidos com o mesmo valor. Se o provedor não distinguir entre elementos com base em um identificador textual, ele definirá ppwszStatusText como NULL e retornará informações sobre a operação como um todo; caso contrário, se ppwszStatusText não for nulo na entrada, o provedor deixará ppwszStatusText intocado.
Se ppwszStatusText for nulo na entrada, o provedor definirá ppwszStatusText como um valor que indica mais informações sobre a operação ou null se essas informações não estiverem disponíveis ou se ISSAsynchStatus::GetStatus retornar um erro. Quando ppwszStatusText é nulo na entrada, o provedor aloca memória para a cadeia de caracteres de status e retorna o endereço para essa memória. O consumidor libera essa memória com IMalloc::Free quando não precisa mais da cadeia de caracteres.
Se ppwszStatusText for NULL na entrada, nenhuma cadeia de caracteres de status será retornada e o provedor retornará informações sobre qualquer elemento da operação ou sobre a operação em geral.
Valores do código de retorno
S_OK
O método retornou com êxito.
Se peAsynchPhase for igual a DBASYNCHPHASE_INITIALIZATION, o objeto ainda não está totalmente inicializado; a tentativa de chamar outras interfaces pode falhar e o conjunto completo de interfaces pode não estar disponível no objeto.
Se peAsynchPhase for igual a DBASYNCHPHASE_POPULATION, o conjunto de linhas será totalmente inicializado e o intervalo completo de interfaces estará disponível no objeto; no entanto, pode haver linhas adicionais ainda não preenchidas no conjunto de linhas.
Se peAsynchPhase for igual a DBASYNCHPHASE_COMPLETE, todo o processamento assíncrono do objeto foi concluído. O objeto é totalmente inicializado e preenchido.
DB_E_CANCELED
O processamento assíncrono foi cancelado durante a população do conjunto de linhas. A população para, mas o conjunto de linhas permanece válido para as linhas já preenchidas.
O processamento assíncrono foi cancelado durante a inicialização do objeto da fonte de dados. O objeto da fonte de dados está em um estado não inicializado.
E_INVALIDARG
O parâmetro hChapter está incorreto.
E_UNEXPECTED
ISSAsynchStatus::GetStatus foi chamado em um objeto de fonte de dados e IDBInitialize::Initialize não foi chamado no objeto da fonte de dados.
ISSAsynchStatus::GetStatus foi chamado em um conjunto de linhas, ITransaction::Commit ou ITransaction::Abort foi chamado e o objeto está em um estado zumbi.
ISSAsynchStatus::GetStatus foi chamado em um conjunto de linhas que foi cancelado de forma assíncrona em sua fase de inicialização. O conjunto de linhas está em um estado zumbi.
E_FAIL
Ocorreu um erro específico do provedor.
Observações
O método ISSAsynchStatus::GetStatus se comporta exatamente como o método IDBAsynchStatus::GetStatus , exceto que, se a inicialização de um objeto de fonte de dados for anulada, E_UNEXPECTED será retornado em vez de DB_E_CANCELED (embora ISSAsynchStatus::WaitForAsynchCompletion retornará DB_E_CANCELED). Isso ocorre porque o objeto da fonte de dados não é deixado no estado zumbi habitual após uma anulação, para que novas operações de inicialização possam ser tentadas.
Se o conjunto de linhas for inicializado ou preenchido de forma assíncrona, ele deverá dar suporte a esse método.
Além dos valores retornados listados, ISSAsynchStatus::GetStatus pode retornar qualquer HRESULT que teria sido retornado pelo método que iniciou a operação assíncrona, indicando o êxito ou a falha da operação.
Algumas operações assíncronas podem não ser capazes de retornar nenhum estado que não seja "concluído" e "não concluído". Eles devem definir pulProgressMax como um valor de 1, indicando a granularidade tudo ou nada de sua estimativa, de modo que suas respostas seriam 0/1 ou 1/1.
Um provedor pode alterar pulProgressMax em chamadas sucessivas e até mesmo retornar uma taxa menor do que anteriormente, se isso refletir uma estimativa de melhoria do grau de conclusão da tarefa.
O provedor não é obrigado a garantir qualquer precisão adicional, mas é incentivado a fazê-lo em casos em que estimativas razoáveis de conclusão são possíveis. Esses esforços melhorarão a qualidade da interface do usuário porque o uso principal dessa função provavelmente será fornecer comentários de progresso ao usuário. A satisfação do usuário aumenta com a qualidade dos comentários sobre uma tarefa invisível e de execução longa.
Chamar ISSAsynchStatus::GetStatus em um objeto de fonte de dados inicializado ou um conjunto de linhas populado ou passar um valor para eOperation diferente de DBASYNCHOP_OPEN retorna S_OK com pulProgress e pulProgressMax definidos com o mesmo valor. Se ISSAsynchStatus::GetStatus for chamado em um objeto criado a partir da execução de um comando que atualiza, exclui ou insere linhas, tanto pulProgress quanto pulProgressMax indicam o número total de linhas afetadas pelo comando.