Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Gibt den Status eines asynchron ausgeführten Vorgangs zurück.
Syntax
HRESULT GetStatus(
HCHAPTER hChapter,
DBASYNCHOP eOperation,
DBCOUNTITEM *pulProgress,
DBCOUNTITEM *pulProgressMax,
DBASYNCHPHASE *peAsynchPhase,
LPOLESTR *ppwszStatusText);
Argumente
hChapter[in]
Das Kapitelhandle. Wenn das abgerufene Objekt kein Rowsetobjekt ist oder der Vorgang nicht auf ein Kapitel angewendet wird, sollte dies auf DB_NULL_HCHAPTER festgelegt werden, das vom Anbieter ignoriert wird.
eOperation[in]
Der Vorgang, für den der asynchrone Status angefordert wird. Dies sollte der folgende Wert sein:
DBASYNCHOP_OPEN-The Consumer fordert Informationen über die asynchrone Öffnung oder Population eines Rowsets oder über die asynchrone Initialisierung eines Datenquellenobjekts an. Wenn es sich beim Anbieter um einen OLE DB 2.5-kompatiblen Anbieter handelt, der die direkte URL-Bindung unterstützt, fordert der Consumer Informationen zur asynchronen Initialisierung oder Grundgesamtheit einer Datenquelle, eines Rowsets, einer Zeile oder eines Datenstromobjekts an.
pulProgress[out]
Ein Zeiger auf den Speicher, in dem der aktuelle Fortschritt des asynchronen Vorgangs relativ zum erwarteten Maximum zurückgegeben wird, das im Parameter pulProgressMax angegeben ist. Weitere Informationen zur Bedeutung von pulProgress finden Sie in der Beschreibung von peAsynchPhase.
Wenn pulProgress ein NULL-Zeiger ist, wird kein Fortschritt zurückgegeben.
pulProgressMax[out]
Ein Zeiger auf den Speicher, in dem der erwartete Maximalwert des pulProgress-Parameters zurückgegeben wird. Dieser Wert kann sich über Aufrufe dieser Methode hinweg ändern. Weitere Informationen zur Bedeutung von pulProgressMax finden Sie in der Beschreibung von peAsynchPhase.
Wenn pulProgressMax ein Nullzeiger ist, wird kein erwarteter Maximalwert zurückgegeben.
peAsynchPhase[out]
Ein Zeiger auf den Speicher, in dem zusätzliche Informationen zum Fortschritt des asynchronen Vorgangs zurückgegeben werden. Gültige Werte sind:
DBASYNCHPHASE_INITIALIZATION-The Objekt befindet sich in einer Initialisierungsphase. Die Argumente pulProgress und pulProgressMax geben ein geschätztes Verhältnis der Fertigstellung an. Das Objekt ist noch nicht vollständig materialisiert. Beim Versuch, andere Schnittstellen aufzurufen, tritt möglicherweise ein Fehler auf, und der vollständige Satz von Schnittstellen ist für das Objekt möglicherweise nicht verfügbar. Wenn der asynchrone Vorgang das Ergebnis des Aufrufs von "ICommand::Execute " für einen Befehl war, der Zeilen aktualisiert, löscht oder einfügt, und wenn cParamSets größer als 1 ist, kann pulProgress und pulProgressMax den Fortschritt für einen einzelnen Satz von Parametern oder für das vollständige Array von Parametersätzen angeben.
DBASYNCHPHASE_POPULATION-The Objekt befindet sich in einer Populationsphase. Obwohl das Rowset vollständig initialisiert ist und der gesamte Schnittstellenbereich für das Objekt verfügbar ist, gibt es möglicherweise noch keine zusätzlichen Zeilen, die noch nicht in das Rowset aufgefüllt wurden. Während pulProgress und pulProgressMax auf der Anzahl der aufgefüllten Zeilen basieren können, basieren sie in der Regel auf der Zeit oder dem Aufwand, die zum Auffüllen des Rowsets erforderlich sind. Daher sollte ein Aufrufer diese Informationen als grobe Schätzung verwenden, wie lange der Prozess dauern kann, nicht die spätere Zeilenanzahl. Diese Phase wird nur während der Grundgesamtheit eines Rowsets zurückgegeben. sie wird nie in der Initialisierung eines Datenquellenobjekts oder durch die Ausführung eines Befehls zurückgegeben, der Zeilen aktualisiert, löscht oder einfügt.
DBASYNCHPHASE_COMPLETE-All asynchrone Verarbeitung des Objekts abgeschlossen ist. ISSAsynchStatus::GetStatus gibt ein HRESULT zurück, das das Ergebnis des Vorgangs angibt. In der Regel ist dies das HRESULT, das zurückgegeben wurde, wenn der Vorgang synchron aufgerufen wurde. Wenn der asynchrone Vorgang das Ergebnis des Aufrufs von "ICommand::Execute " für einen Befehl war, der Zeilen aktualisiert, löscht oder einfügt, entsprechen pulProgressund pulProgressMax der Gesamtzahl der vom Befehl betroffenen Zeilen. Wenn cParamSets größer als 1 ist, ist dies die Gesamtanzahl der Zeilen, die von allen in der Ausführung angegebenen Parametersätzen betroffen sind. Wenn peAsynchPhase ein Nullzeiger ist, wird kein Statuscode zurückgegeben.
DBASYNCHPHASE_CANCELED-Asynchronous Verarbeitung des Objekts abgebrochen wurde. ISSAsynchStatus::GetStatus gibt DB_E_CANCELED zurück. Wenn der asynchrone Vorgang das Ergebnis des Aufrufs von "ICommand::Execute " für einen Befehl war, der Zeilen aktualisiert, löscht oder einfügt, entspricht pulProgress der Gesamtzahl der Zeilen für alle Parametersätze, die vom Befehl vor dem Abbruch betroffen sind.
ppwszStatusText[in/out]
Ein Zeiger auf den Arbeitsspeicher, der zusätzliche Informationen zum Vorgang enthält. Ein Anbieter kann diesen Wert verwenden, um zwischen verschiedenen Elementen eines Vorgangs zu unterscheiden, z. B. unterschiedliche Ressourcen, auf die zugegriffen wird. Diese Zeichenfolge wird gemäß der DBPROP_INIT_LCID-Eigenschaft des Datenquellenobjekts lokalisiert.
Wenn ppwszStatusText für eingaben nicht null ist, gibt der Anbieter den Status zurück, der dem durch ppwszStatusText identifizierten Element zugeordnet ist. Wenn ppwszStatusText kein Element von eOperation angibt, gibt der Anbieter S_OK zurück, wobei pulProgress und pulProgressMax auf denselben Wert festgelegt sind. Wenn der Anbieter nicht zwischen Elementen basierend auf einem Textbezeichner unterscheidet, legt er ppwszStatusText auf NULL fest und gibt Informationen über den Vorgang als Ganzes zurück. andernfalls bleibt "ppwszStatusText " bei eingaben nicht null, lässt der Anbieter "ppwszStatusText " unverändert.
Wenn ppwszStatusText für die Eingabe null ist, legt der Anbieter ppwszStatusText auf einen Wert fest, der weitere Informationen zum Vorgang angibt, oder auf NULL, wenn keine solchen Informationen verfügbar sind oder wenn ISSAsynchStatus::GetStatus einen Fehler zurückgibt. Wenn ppwszStatusText für die Eingabe null ist, weist der Anbieter Speicher für die Statuszeichenfolge zu und gibt die Adresse an diesen Speicher zurück. Der Consumer gibt diesen Speicher mit "IMalloc::Free " frei, wenn er die Zeichenfolge nicht mehr benötigt.
Wenn ppwszStatusText für die Eingabe NULL ist, wird keine Statuszeichenfolge zurückgegeben, und der Anbieter gibt Informationen zu jedem Element des Vorgangs oder über den Vorgang im Allgemeinen zurück.
Rückgabecodewerte
S_OK
Die Methode wurde erfolgreich zurückgegeben.
Wenn peAsynchPhase gleich DBASYNCHPHASE_INITIALIZATION ist, wird das Objekt noch nicht vollständig initialisiert. Der Versuch, andere Schnittstellen aufzurufen, schlägt möglicherweise fehl, und der vollständige Satz von Schnittstellen ist für das Objekt möglicherweise nicht verfügbar.
Wenn peAsynchPhase gleich DBASYNCHPHASE_POPULATION ist, wird das Rowset vollständig initialisiert, und der gesamte Schnittstellenbereich ist für das Objekt verfügbar; Es können jedoch weitere Zeilen vorhanden sein, die noch nicht in das Rowset aufgefüllt wurden.
Wenn peAsynchPhase gleich DBASYNCHPHASE_COMPLETE ist, wurde die gesamte asynchrone Verarbeitung des Objekts abgeschlossen. Das Objekt wird vollständig initialisiert und aufgefüllt.
DB_E_CANCELED
Die asynchrone Verarbeitung wurde während der Rowsetgesamtheit abgebrochen. Die Population wird beendet, aber das Rowset bleibt gültig für die bereits aufgefüllten Zeilen.
Die asynchrone Verarbeitung wurde während der Initialisierung des Datenquellenobjekts abgebrochen. Das Datenquellenobjekt befindet sich in einem nicht initialisierten Zustand.
E_INVALIDARG
Der hChapter-Parameter ist falsch.
E_UNEXPECTED
ISSAsynchStatus::GetStatus wurde für ein Datenquellenobjekt aufgerufen, und IDBInitialize::Initialize wurde für das Datenquellenobjekt nicht aufgerufen.
ISSAsynchStatus::GetStatus wurde für ein Rowset, ITransaction::Commit oder ITransaction::Abort aufgerufen, und das Objekt befindet sich in einem Zombie-Zustand.
ISSAsynchStatus::GetStatus wurde für ein Rowset aufgerufen, das in der Initialisierungsphase asynchron abgebrochen wurde. Das Rowset befindet sich in einem Zombie-Zustand.
E_FAIL
Ein anbieterspezifischer Fehler ist aufgetreten.
Bemerkungen
Die ISSAsynchStatus::GetStatus-Methode verhält sich genau wie die IDBAsynchStatus::GetStatus-Methode , mit der Ausnahme, dass die Initialisierung eines Datenquellenobjekts abgebrochen wird, E_UNEXPECTED statt DB_E_CANCELED zurückgegeben wird (obwohl ISSAsynchStatus::WaitForAsynchCompletion DB_E_CANCELED zurückgibt). Dies liegt daran, dass das Datenquellenobjekt nicht im üblichen Zombie-Zustand nach einem Abbruch verbleibt, damit weitere Initialisierungsvorgänge versucht werden können.
Wenn das Rowset asynchron initialisiert oder aufgefüllt wird, muss es diese Methode unterstützen.
Zusätzlich zu den aufgelisteten Rückgabewerten kann ISSAsynchStatus::GetStatus jedes HRESULT zurückgeben, das von der Methode zurückgegeben wurde, die den asynchronen Vorgang initiiert hat und den Erfolg oder Fehler des Vorgangs angibt.
Einige asynchrone Vorgänge können möglicherweise keine anderen Zustände als "finished" und "not finished" zurückgeben. Sie sollten pulProgressMax auf einen Wert von 1 festlegen, der die gesamte oder nichts Granularität ihrer Schätzung angibt, sodass ihre Antworten entweder 0/1 oder 1/1 sein würden.
Ein Anbieter kann pulProgressMax in aufeinander folgenden Aufrufen ändern und sogar ein kleineres Verhältnis als zuvor zurückgeben, wenn dies eine verbesserte Schätzung des Abschlussgrads des Vorgangs widerspiegelt.
Der Anbieter ist nicht verpflichtet, eine weitere Genauigkeit zu garantieren, sondern wird ermutigt, dies in Fällen zu tun, in denen angemessene Schätzungen zur Fertigstellung möglich sind. Diese Bemühungen werden die Qualität der Benutzeroberfläche verbessern, da die Hauptverwendung dieser Funktion wahrscheinlich dem Benutzer Fortschrittsfeedback geben wird. Die Benutzerzufriedenheit erhöht sich mit der Qualität des Feedbacks zu einer unsichtbaren, lang andauernden Aufgabe.
Aufrufen von ISSAsynchStatus::GetStatus für ein initialisiertes Datenquellenobjekt oder ein ausgefülltes Rowset oder das Übergeben eines Werts für eOperation außer DBASYNCHOP_OPEN, gibt S_OK zurück, wobei pulProgress und pulProgressMax auf denselben Wert festgelegt sind. Wenn ISSAsynchStatus::GetStatus für ein Objekt aufgerufen wird, das aus der Ausführung eines Befehls erstellt wurde, der Zeilen aktualisiert, löscht oder einfügt, geben sowohl pulProgress als auch pulProgressMax die Gesamtanzahl der vom Befehl betroffenen Zeilen an.