ISSAsynchStatus::GetStatus (OLE DB)

Devuelve el estado de una operación de ejecución asincrónica.

Sintaxis

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

Argumentos

hChapter[in]
Identificador del capítulo. Si el objeto que se sondea no es un objeto de conjunto de filas o la operación no se aplica a un capítulo, se debe establecer en DB_NULL_HCHAPTER, que el proveedor omite.

eOperation[in]
Operación para la que se solicita el estado asincrónico. Debe ser el siguiente valor:

DBASYNCHOP_OPEN-The consumidor solicita información sobre la apertura asincrónica o el rellenado de un conjunto de filas o sobre la inicialización asincrónica de un objeto de origen de datos. Si el proveedor es un proveedor compatible con OLE DB 2.5 que admite el enlace de direcciones URL directas, el consumidor solicita información sobre la inicialización asincrónica o el rellenado de un origen de datos, conjunto de filas, fila o objeto de secuencia.

pulProgress[out]
Puntero a la memoria en la que se devuelve el progreso actual de la operación asincrónica con respecto al máximo esperado indicado en el parámetro pulProgressMax . Para obtener más información sobre el significado de pulProgress, vea la descripción de peAsynchPhase.

Si pulProgress es un puntero nulo, no se devuelve ningún progreso.

pulProgressMax[out]
Puntero a la memoria en la que se devuelve el valor máximo esperado del parámetro pulProgress . Este valor puede cambiar entre llamadas a este método. Para obtener más información sobre el significado de pulProgressMax, vea la descripción de peAsynchPhase.

Si pulProgressMax es un puntero nulo, no se devuelve ningún valor máximo esperado.

peAsynchPhase[out]
Puntero a la memoria en la que se devuelve información adicional sobre el progreso de la operación asincrónica. Entre los valores válidos se incluyen:

DBASYNCHPHASE_INITIALIZATION-The objeto está en una fase de inicialización. Los argumentos pulProgress y pulProgressMax indican una relación estimada de finalización. El objeto aún no está totalmente materializado. Se puede producir un error al intentar llamar a cualquier otra interfaz y es posible que el conjunto completo de interfaces no esté disponible en el objeto . Si la operación asincrónica era el resultado de llamar a ICommand::Execute para un comando que actualiza, elimina o inserta filas y si cParamSets es mayor que 1, pulProgress y pulProgressMax pueden indicar el progreso de un único conjunto de parámetros o para la matriz completa de conjuntos de parámetros.

DBASYNCHPHASE_POPULATION-The objeto se encuentra en una fase de rellenado. Aunque el conjunto de filas está completamente inicializado y el intervalo completo de interfaces está disponible en el objeto, puede haber filas adicionales que aún no se hayan rellenado en el conjunto de filas. Aunque pulProgress y pulProgressMax se pueden basar en el número de filas rellenadas, generalmente se basan en el tiempo o esfuerzo necesario para rellenar el conjunto de filas. Por lo tanto, un autor de la llamada debe usar esta información como una estimación aproximada del tiempo que puede tardar el proceso, no el recuento de filas final. Esta fase solo se devuelve durante la población de un conjunto de filas; nunca se devuelve en la inicialización de un objeto de origen de datos o mediante la ejecución de un comando que actualiza, elimina o inserta filas.

DBASYNCHPHASE_COMPLETE-All procesamiento asincrónico del objeto se ha completado. ISSAsynchStatus::GetStatus devuelve un HRESULT que indica el resultado de la operación. Normalmente, este será el HRESULT que se habría devuelto si se llamara a la operación de forma sincrónica. Si la operación asincrónica era el resultado de llamar a ICommand::Execute para un comando que actualiza, elimina o inserta filas, pulProgress y pulProgressMax son iguales al número total de filas afectadas por el comando. Si cParamSets es mayor que 1, este es el número total de filas afectadas por todos los conjuntos de parámetros especificados en la ejecución. Si peAsynchPhase es un puntero nulo, no se devuelve ningún código de estado.

DBASYNCHPHASE_CANCELED-Asynchronous se anuló el procesamiento del objeto. ISSAsynchStatus::GetStatus devuelve DB_E_CANCELED. Si la operación asincrónica era el resultado de llamar a ICommand::Execute para un comando que actualiza, elimina o inserta filas, pulProgress es igual al número total de filas, para todos los conjuntos de parámetros, afectados por el comando antes de la cancelación.

ppwszStatusText[in/out]
Puntero a la memoria que contiene información adicional sobre la operación. Un proveedor puede usar este valor para distinguir entre distintos elementos de una operación; por ejemplo, se accede a distintos recursos. Esta cadena se localiza según la propiedad DBPROP_INIT_LCID en el objeto de origen de datos.

Si ppwszStatusText no es null en la entrada, el proveedor devuelve el estado asociado al elemento determinado identificado por ppwszStatusText. Si ppwszStatusText no indica un elemento de eOperation, el proveedor devuelve S_OK con pulProgress y pulProgressMax establecido en el mismo valor. Si el proveedor no distingue entre elementos basados en un identificador de texto, establece ppwszStatusText en NULL y devuelve información sobre la operación en su conjunto; De lo contrario, si ppwszStatusText no es null en la entrada, el proveedor deja ppwszStatusText sin modificar.

Si ppwszStatusText es null en la entrada, el proveedor establece ppwszStatusText en un valor que indica más información sobre la operación, o en NULL si no hay ninguna información disponible o si ISSAsynchStatus::GetStatus devuelve un error. Cuando ppwszStatusText es null en la entrada, el proveedor asigna memoria para la cadena de estado y devuelve la dirección a esta memoria. El consumidor libera esta memoria con IMalloc::Free cuando ya no necesita la cadena.

Si ppwszStatusText es NULL en la entrada, no se devuelve ninguna cadena de estado y el proveedor devuelve información sobre cualquier elemento de la operación o sobre la operación en general.

Valores de código de retorno

S_OK
El método devolvió correctamente.

• Si peAsynchPhase es igual a DBASYNCHPHASE_INITIALIZATION, el objeto aún no se inicializa completamente; Es posible que se produzca un error al intentar llamar a cualquier otra interfaz y es posible que el conjunto completo de interfaces no esté disponible en el objeto .

• Si peAsynchPhase es igual a DBASYNCHPHASE_POPULATION, el conjunto de filas se inicializa completamente y el intervalo completo de interfaces está disponible en el objeto ; sin embargo, puede haber filas adicionales que aún no se han rellenado en el conjunto de filas.

• Si peAsynchPhase es igual a DBASYNCHPHASE_COMPLETE, se ha completado todo el procesamiento asincrónico del objeto. El objeto se inicializa completamente y se rellena.

DB_E_CANCELED
El procesamiento asincrónico se canceló durante el rellenado de conjuntos de filas. El rellenado se detiene, pero el conjunto de filas sigue siendo válido para las filas ya rellenadas.

El procesamiento asincrónico se canceló durante la inicialización del objeto de origen de datos. El objeto de origen de datos está en un estado no inicializado.

E_INVALIDARG
El parámetro hChapter es incorrecto.

Error_Inesperado
Se llamó a ISSAsynchStatus::GetStatus en un objeto de origen de datos y no se ha llamado a IDBInitialize::Initialize en el objeto de origen de datos.

Se llamó a ISSAsynchStatus::GetStatus en un conjunto de filas, se llamó a ITransaction::Commit o ITransaction::Abort y el objeto está en estado zombie.

Se llamó a ISSAsynchStatus::GetStatus en un conjunto de filas que se canceló de forma asincrónica en su fase de inicialización. El conjunto de filas está en estado zombie.

E_FAIL
Error específico del proveedor.

Observaciones

El método ISSAsynchStatus::GetStatus se comporta exactamente como el método IDBAsynchStatus::GetStatus , excepto que si se anula la inicialización de un objeto de origen de datos, se devuelve E_UNEXPECTED en lugar de DB_E_CANCELED (aunque ISSAsynchStatus::WaitForAsynchCompletion devolverá DB_E_CANCELED). Esto se debe a que el objeto de origen de datos no se deja en el estado zombi habitual después de una anulación, para que se puedan intentar más operaciones de inicialización.

Si el conjunto de filas se inicializa o se rellena de forma asincrónica, debe admitir este método.

Además de los valores devueltos enumerados, ISSAsynchStatus::GetStatus puede devolver cualquier HRESULT que hubiera sido devuelto por el método que inició la operación asincrónica, lo que indica el éxito o error de la operación.

Es posible que algunas operaciones asincrónicas no puedan devolver ningún estado distinto de "finalizado" y "no finalizado". Deben establecer pulProgressMax en un valor de 1, lo que indica la granularidad todo o nada de su estimación, por lo que sus respuestas serían 0/1 o 1/1.

Un proveedor puede cambiar pulProgressMax en llamadas sucesivas e incluso devolver una relación menor que antes, si esto refleja una estimación de mejora del grado de finalización de la tarea.

El proveedor no está obligado a garantizar ninguna precisión adicional, pero se recomienda hacerlo en los casos en los que se puedan realizar estimaciones razonables de finalización. Estos esfuerzos mejorarán la calidad de la interfaz de usuario, ya que es probable que el uso principal de esta función sea proporcionar comentarios de progreso al usuario. La satisfacción del usuario aumenta con la calidad de los comentarios sobre una tarea invisible y de larga duración.

Llamar a ISSAsynchStatus::GetStatus en un objeto de origen de datos inicializado o un conjunto de filas rellenado, o pasar un valor para eOperation distinto de DBASYNCHOP_OPEN, devuelve S_OK con pulProgress y pulProgressMax establecido en el mismo valor. Si se llama a ISSAsynchStatus::GetStatus en un objeto creado a partir de la ejecución de un comando que actualiza, elimina o inserta filas, pulProgress y pulProgressMax indican el número total de filas afectadas por el comando.

Véase también

Realización de operaciones asincrónicas
ISSAsynchStatus (OLE DB)