Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Retourne l’état d’une opération en cours d’exécution asynchrone.
Syntaxe
HRESULT GetStatus(
HCHAPTER hChapter,
DBASYNCHOP eOperation,
DBCOUNTITEM *pulProgress,
DBCOUNTITEM *pulProgressMax,
DBASYNCHPHASE *peAsynchPhase,
LPOLESTR *ppwszStatusText);
Les arguments
hChapter[in]
Handle de chapitre. Si l’objet interrogé n’est pas un objet d’ensemble de lignes ou que l’opération ne s’applique pas à un chapitre, il doit être défini sur DB_NULL_HCHAPTER, qui est ignoré par le fournisseur.
eOperation[in]
Opération pour laquelle l’état asynchrone est demandé. Il doit s’agir de la valeur suivante :
DBASYNCHOP_OPEN-The consommateur demande des informations sur l’ouverture ou la population asynchrone d’un ensemble de lignes ou sur l’initialisation asynchrone d’un objet source de données. Si le fournisseur est un fournisseur compatible OLE DB 2.5 qui prend en charge la liaison d’URL directe, le consommateur demande des informations sur l’initialisation asynchrone ou la population d’une source de données, d’un ensemble de lignes, d’une ligne ou d’un objet de flux.
pulProgress[out]
Pointeur vers la mémoire dans lequel retourner la progression actuelle de l’opération asynchrone par rapport au maximum attendu indiqué dans le paramètre pulProgressMax . Pour plus d’informations sur la signification de pulProgress, consultez la description de peAsynchPhase.
Si pulProgress est un pointeur Null, aucune progression n’est retournée.
pulProgressMax[out]
Pointeur vers la mémoire dans lequel retourner la valeur maximale attendue du paramètre pulProgress . Cette valeur peut changer entre les appels à cette méthode. Pour plus d’informations sur la signification de pulProgressMax, consultez la description de peAsynchPhase.
Si pulProgressMax est un pointeur Null, aucune valeur maximale attendue n’est retournée.
peAsynchPhase[out]
Pointeur vers la mémoire dans lequel retourner des informations supplémentaires concernant la progression de l’opération asynchrone. Les valeurs valides sont les suivantes :
DBASYNCHPHASE_INITIALIZATION-The objet est dans une phase d’initialisation. Les arguments pulProgress et pulProgressMax indiquent un ratio estimé d’achèvement. L’objet n’est pas encore entièrement matérialisé. Toute tentative d’appel d’autres interfaces peut échouer et l’ensemble complet d’interfaces peut ne pas être disponible sur l’objet. Si l’opération asynchrone a été le résultat de l’appel d’ICommand ::Execute pour une commande qui met à jour, supprime ou insère des lignes et si cParamSets est supérieur à 1, pulProgress et pulProgressMax peut indiquer la progression pour un seul ensemble de paramètres ou pour le tableau complet des jeux de paramètres.
DBASYNCHPHASE_POPULATION-The objet se trouve dans une phase de remplissage. Bien que l’ensemble de lignes soit entièrement initialisé et que la plage complète d’interfaces soit disponible sur l’objet, il peut y avoir des lignes supplémentaires qui ne sont pas encore remplies dans l’ensemble de lignes. Bien que pulProgress et pulProgressMax puissent être basés sur le nombre de lignes remplies, ils sont généralement basés sur le temps ou l’effort nécessaire pour remplir l’ensemble de lignes. Un appelant doit donc utiliser ces informations comme estimation approximative de la durée pendant laquelle le processus peut prendre, et non le nombre de lignes éventuels. Cette phase est retournée uniquement pendant la population d’un ensemble de lignes ; elle n’est jamais retournée dans l’initialisation d’un objet source de données ou par l’exécution d’une commande qui met à jour, supprime ou insère des lignes.
DBASYNCHPHASE_COMPLETE-All traitement asynchrone de l’objet s’est terminé. ISSAsynchStatus ::GetStatus retourne un HRESULT indiquant le résultat de l’opération. En règle générale, il s’agit du HRESULT qui aurait été retourné si l’opération a été appelée de façon synchrone. Si l’opération asynchrone a été le résultat de l’appel d’ICommand ::Execute pour une commande qui met à jour, supprime ou insère des lignes, pulProgress et pulProgressMax sont égales au nombre total de lignes affectées par la commande. Si cParamSets est supérieur à 1, il s’agit du nombre total de lignes affectées par tous les ensembles de paramètres spécifiés dans l’exécution. Si peAsynchPhase est un pointeur Null, aucun code d’état n’est retourné.
DBASYNCHPHASE_CANCELED-Asynchronous traitement de l’objet a été abandonné. ISSAsynchStatus ::GetStatus retourne DB_E_CANCELED. Si l’opération asynchrone a été le résultat de l’appel d’ICommand ::Execute pour une commande qui met à jour, supprime ou insère des lignes, pulProgress est égal au nombre total de lignes, pour tous les jeux de paramètres, affectés par la commande avant l’annulation.
ppwszStatusText[in/out]
Pointeur vers la mémoire contenant des informations supplémentaires sur l’opération. Un fournisseur peut utiliser cette valeur pour faire la distinction entre différents éléments d’une opération, par exemple, différentes ressources accessibles. Cette chaîne est localisée en fonction de la propriété DBPROP_INIT_LCID sur l’objet source de données.
Si ppwszStatusText n’est pas null lors de l’entrée, le fournisseur retourne l’état associé à l’élément particulier identifié par ppwszStatusText. Si ppwszStatusText n’indique pas d’élément d’eOperation, le fournisseur retourne S_OK avec pulProgress et pulProgressMax défini sur la même valeur. Si le fournisseur ne fait pas la distinction entre les éléments basés sur un identificateur textuel, il définit ppwszStatusText sur NULL et retourne des informations sur l’opération dans son ensemble ; sinon, si ppwszStatusText n’est pas null lors de l’entrée, le fournisseur laisse ppwszStatusText inchangé.
Si ppwszStatusText est null lors de l’entrée, le fournisseur définit ppwszStatusText sur une valeur indiquant plus d’informations sur l’opération, ou sur NULL si aucune telle information n’est disponible ou si ISSAsynchStatus ::GetStatus retourne une erreur. Lorsque ppwszStatusText est null lors de l’entrée, le fournisseur alloue de la mémoire pour la chaîne d’état et retourne l’adresse à cette mémoire. Le consommateur libère cette mémoire avec IMalloc ::Free quand il n’a plus besoin de la chaîne.
Si ppwszStatusText est NULL lors de l’entrée, aucune chaîne d’état n’est retournée et le fournisseur retourne des informations sur n’importe quel élément de l’opération ou sur l’opération en général.
Codet de retour
S_OK
La méthode a été retournée avec succès.
Si peAsynchPhase est égal à DBASYNCHPHASE_INITIALIZATION, l’objet n’est pas encore entièrement initialisé ; toute tentative d’appel d’autres interfaces peut échouer, et l’ensemble complet d’interfaces peut ne pas être disponible sur l’objet.
Si peAsynchPhase est égal à DBASYNCHPHASE_POPULATION, l’ensemble de lignes est entièrement initialisé et la plage complète d’interfaces est disponible sur l’objet ; toutefois, il peut y avoir des lignes supplémentaires qui ne sont pas encore remplies dans l’ensemble de lignes.
Si peAsynchPhase est égal à DBASYNCHPHASE_COMPLETE, tout le traitement asynchrone de l’objet est terminé. L’objet est entièrement initialisé et rempli.
DB_E_CANCELED
Le traitement asynchrone a été annulé pendant la population de l’ensemble de lignes. La population s’arrête, mais l’ensemble de lignes reste valide pour les lignes déjà remplies.
Le traitement asynchrone a été annulé lors de l’initialisation de l’objet source de données. L’objet source de données est dans un état non initialisé.
E_INVALIDARG
Le paramètre hChapter est incorrect.
ERREUR_IMPRÉVUE
ISSAsynchStatus ::GetStatus a été appelé sur un objet de source de données, et IDBInitialize ::Initialize n’a pas été appelé sur l’objet source de données.
ISSAsynchStatus ::GetStatus a été appelé sur un ensemble de lignes, ITransaction ::Commit ou ITransaction ::Abort a été appelé, et l’objet est dans un état zombie.
ISSAsynchStatus ::GetStatus a été appelé sur un ensemble de lignes qui a été annulé de manière asynchrone dans sa phase d’initialisation. L’ensemble de lignes est dans un état zombie.
E_FAIL
Une erreur spécifique au fournisseur s’est produite.
Remarques
La méthode ISSAsynchStatus ::GetStatus se comporte exactement comme la méthode IDBAsynchStatus ::GetStatus , sauf que si l’initialisation d’un objet source de données est abandonnée, E_UNEXPECTED est retournée plutôt que DB_E_CANCELED (bien que ISSAsynchStatus ::WaitForAsynchCompletion retourne DB_E_CANCELED). Cela est dû au fait que l’objet source de données n’est pas laissé dans l’état zombie habituel après une abandon, afin que d’autres opérations d’initialisation puissent être tentées.
Si l’ensemble de lignes est initialisé ou rempli de manière asynchrone, il doit prendre en charge cette méthode.
Outre les valeurs de retour répertoriées, ISSAsynchStatus ::GetStatus peut retourner n’importe quel HRESULT qui aurait été retourné par la méthode qui a lancé l’opération asynchrone, indiquant la réussite ou l’échec de l’opération.
Certaines opérations asynchrones peuvent ne pas être en mesure de retourner des états autres que « terminés » et « non terminés ». Ils doivent définir pulProgressMax sur une valeur de 1, indiquant la granularité tout ou rien de leur estimation, afin que leurs réponses soient soit 0/1 ou 1/1.
Un fournisseur peut modifier pulProgressMax dans les appels successifs et même retourner un ratio plus petit que précédemment, si cela reflète une estimation améliorée du degré d’achèvement de la tâche.
Le fournisseur n’est pas obligé de garantir une précision supplémentaire, mais il est encouragé à le faire dans les cas où des estimations raisonnables de l’achèvement sont possibles. Ces efforts permettront d’améliorer la qualité de l’interface utilisateur, car l’utilisation principale de cette fonction est susceptible d’être d’envoyer des commentaires sur la progression à l’utilisateur. La satisfaction des utilisateurs augmente avec la qualité des commentaires sur une tâche invisible et longue.
Appel de ISSAsynchStatus ::GetStatus sur un objet source de données initialisé ou un ensemble de lignes rempli, ou en passant une valeur pour eOperation autre que DBASYNCHOP_OPEN, retourne S_OK avec pulProgress et pulProgressMax défini sur la même valeur. Si ISSAsynchStatus ::GetStatus est appelé sur un objet créé à partir de l’exécution d’une commande qui met à jour, supprime ou insère des lignes, pulProgress et pulProgressMax indiquent le nombre total de lignes affectées par la commande.