Méthode IWbemServices ::GetObjectAsync (wbemcli.h)
La méthode IWbemServices ::GetObjectAsync récupère un objet, soit une définition de classe, soit instance, en fonction de son chemin d’accès. Ceci est similaire à IWbemServices ::GetObject , sauf que l’appel retourne immédiatement et que l’objet est fourni au récepteur d’objet fourni.
Actuellement, cette méthode récupère les objets uniquement à partir de l’espace de noms associé au pointeur IWbemServices .
Syntaxe
HRESULT GetObjectAsync(
[in] const BSTR strObjectPath,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Paramètres
[in] strObjectPath
Chemin de l’objet à récupérer. Pour un fournisseur instance, StrObjectPath peut être au format suivant :
- Namespace :Class.Key = « Value »
- Namespace :Class = « Value »
- Namespace :Class.Key = « Value », Key2 = « Value2 »
Si cette valeur est NULL, un objet vide, qui peut devenir une nouvelle classe, est retourné. Pour plus d’informations, consultez Création d'un commentaire.
[in] lFlags
Les indicateurs suivants affectent le comportement de cette méthode.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Si cet indicateur est défini, WMI récupère les qualificateurs modifiés stockés dans l’espace de noms localisé des paramètres régionaux de la connexion actuelle. S’il n’est pas défini, seuls les qualificateurs stockés dans l’espace de noms immédiat sont récupérés.
WBEM_FLAG_DIRECT_READ
Cet indicateur entraîne un accès direct au fournisseur pour la classe spécifiée sans égard à sa ou ses sous-classes parentes.
WBEM_FLAG_SEND_STATUS
Enregistre une demande de réception de rapports de status intermédiaires via l’implémentation par le client d’IWbemObjectSink ::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur modifie le comportement.
[in] pCtx
Généralement NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext qui peut être utilisé par le fournisseur qui produit la classe ou le instance demandé. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation du fournisseur en question. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.
[in] pResponseHandler
Pointeur vers l’implémentation d’IWbemObjectSink par l’appelant. Ce gestionnaire reçoit l’objet demandé lorsqu’il devient disponible via la méthode IWbemObjectSink ::Indicate . Le paramètre pObjParam contient l’objet . Si un code d’erreur est retourné, le pointeur IWbemObjectSink fourni n’est pas utilisé. Si WBEM_S_NO_ERROR est retourné, l’implémentation IWbemObjectSink de l’utilisateur est appelée pour indiquer le résultat de l’opération. Gestion Windows appelle uniquement AddRef vers le pointeur dans les cas où WBEM_S_NO_ERROR retourne. Dans les cas où un code d’erreur retourne, le nombre de références est le même que lors de l’entrée. Pour plus d’informations sur ce paramètre, consultez Appel d’une méthode.
Valeur retournée
Cette méthode retourne une valeur HRESULT qui indique l’état de l’appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.
En cas d’échec, vous pouvez obtenir toutes les informations disponibles à partir de la fonction COM GetErrorInfoGetErrorInfo.
Des codes d’erreur spécifiques à COM peuvent également être retournés si des problèmes réseau vous font perdre la connexion à distance à Windows Management.
Remarques
Lorsque vous implémentez un fournisseur de instance, vous devez utiliser l’exemple de code de l’analyseur de chemin d’accès d’objet dans la section WMI du PSDK pour analyser le chemin d’accès de l’objet afin de reconnaître l’objet demandé par le client. En outre, un fournisseur qui prend en charge une classe dérivée doit uniquement fournir les valeurs des propriétés locales de la classe, plutôt que les propriétés héritées. WMI demande que le fournisseur de la classe de base gère les propriétés héritées.
Lors de l’implémentation d’un fournisseur de classes, GetObjectAsync doit déterminer quelle classe est demandée en analysant le chemin d’accès de l’objet nom de classe stocké dans le paramètre strObjectPath . La méthode GetObjectAsync génère ensuite la classe dynamiquement ou prend la classe à partir d’un cache privé. Ensuite, GetObjectAsync envoie la classe à WMI à l’aide du pointeur IWbemObjectSink pointé vers le paramètre pResponseHandler . La méthode IWbemObjectSink ::SetStatus est appelée pour indiquer la fin du jeu de résultats. Il peut également être appelé sans appel intermédiaire à IWbemObjectSink ::Indiquer si des conditions d’erreur se produisent.
Étant donné que le rappel n’est peut-être pas retourné au même niveau d’authentification que le client, il est recommandé d’utiliser semi-synchrone au lieu d’une communication asynchrone. Si vous avez besoin d’une communication asynchrone, consultez Appel d’une méthode.
Pour plus d’informations sur l’utilisation semi-synchronisée des méthodes, consultez IWbemServices ::GetObject et Appel d’une méthode.
Exemples
L’exemple suivant explique comment implémenter GetObjectAsync pour un fournisseur de instance.
SCODE CInstPro::GetObjectAsync (BSTR ObjectPath,
long lFlags, IWbemContext *pCtx,
IWbemObjectSink FAR* pHandler)
{
ULONG cRef; // Reference count
SCODE sc;
BOOL bOK = FALSE;
IWbemServices * m_pNamespace;
IWbemClassObject FAR* pObj;
// Check arguments.
if(ObjectPath == NULL || pHandler == NULL ||
m_pNamespace == NULL)
return WBEM_E_INVALID_PARAMETER;
// Based on the object path, produce an empty instance
// of the class and gather required data,
// setting the instance's property values accordingly.
// This example assumes that GetByPath is implemented
// by the provider to do this.
// The IWbemPath interface can be used to parse
// the object path, separating the namespace and class name.
sc = GetByPath (ObjectPath, &pObj, pCtx);
if(sc == S_OK)
{
pHandler->Indicate (1, &pObj);
pObj->Release();
bOK = TRUE;
}
sc = (bOK) ? S_OK : WBEM_E_NOT_FOUND;
// Set status.
pHandler->SetStatus(0,sc, NULL, NULL);
// Free memory resources.
SysFreeString(ObjectPath);
m_pNamespace->Release();
pObj->Release();
return sc;
}
L’exemple suivant montre comment un fournisseur de classe classique implémente GetObjectAsync.
HRESULT CStdProvider::GetObjectAsync(
/* [in] */ BSTR strObjectPath,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
// Assume there is an IWbemServices pointer available.
// Retrieve an 'empty' object which is built up
// into the class definition.
HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
if (hRes)
return hRes;
// Parse the object path and determine which class is
// required. The path string is the required class name.
// Fill in the properties required for the class definition
// using pClass->Put(...), and so on.
// ...
// Send the class definition back to WMI.
pResponseHandler->Indicate(1, &pClass);
// Indicate that it is now finished.
pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
SysFreeString(strObjectPath);
m_pSvc->Release();
pClass->Release(); // This is no longer needed.
return WBEM_S_NO_ERROR;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista |
| Serveur minimal pris en charge | Windows Server 2008 |
| Plateforme cible | Windows |
| En-tête | wbemcli.h (inclure Wbemidl.h) |
| Bibliothèque | Wbemuuid.lib |
| DLL | Fastprox.dll ; Esscli.dll ; FrameDyn.dll ; FrameDynOS.dll ; Ntevt.dll ; Stdprov.dll ; Viewprov.dll ; Wbemcomn.dll ; Wbemcore.dll ; Wbemess.dll ; Wbemsvc.dll ; Wmipicmp.dll ; Wmidcprv.dll ; Wmipjobj.dll ; Wmiprvsd.dll |