IWbemProviderInit ::Initialize, méthode (wbemprov.h)

Article
08/27/2023

La méthode IWbemProviderInit ::Initialize est appelée par Windows Management pour initialiser un fournisseur afin de recevoir des requêtes client. Tous les types de fournisseurs doivent implémenter cette méthode.

Syntaxe

HRESULT Initialize(
  [in] LPWSTR                wszUser,
  [in] LONG                  lFlags,
  [in] LPWSTR                wszNamespace,
  [in] LPWSTR                wszLocale,
  [in] IWbemServices         *pNamespace,
  [in] IWbemContext          *pCtx,
  [in] IWbemProviderInitSink *pInitSink
);

Paramètres

[in] wszUser

Pointeur vers le nom d’utilisateur, si l’initialisation par utilisateur a été demandée dans le instance d’inscription __Win32Provider pour ce fournisseur. Sinon, il s’agit de NULL.

N’oubliez pas que ce paramètre est défini sur NULL pour les fournisseurs de consommateurs d’événements, quelle que soit la valeur de la propriété PerUserInitialization dans le __Win32Provider instance pour le fournisseur.

[in] lFlags

Réservé. Ce paramètre doit être égal à 0 (zéro).

[in] wszNamespace

Nom d’espace de noms pour lequel le fournisseur est initialisé.

[in] wszLocale

Nom des paramètres régionaux pour lesquels le fournisseur est initialisé.

Chaîne au format suivant, où la valeur hexadécimale est une valeur LCID standard Microsoft :

« MS_409 »

Ce paramètre peut être NULL.

[in] pNamespace

Pointeur IWbemServices vers Windows Management. Ce pointeur peut traiter toutes les demandes effectuées par le fournisseur. Le fournisseur doit utiliser la méthode IWbemProviderInit ::AddRef sur ce pointeur s’il veut rappeler Windows Management pendant son exécution.

[in] pCtx

Pointeur IWbemContext associé à l’initialisation. Ce paramètre peut être NULL.

Si le fournisseur effectue des requêtes dans Windows Management avant de terminer l’initialisation, il doit utiliser la méthode IWbemProviderInit ::AddRef sur ce pointeur. Pour plus d’informations, consultez Passer des appels à WMI.

Si un fournisseur doit effectuer une demande dépendante sur un autre fournisseur, vous devez renvoyer cette chaîne de contexte à WMI pour éviter les verrouillages potentiels. Toutefois, dans le cas d’une requête indépendante, cela n’est pas nécessaire et WMI génère une nouvelle chaîne de contexte pour celle-ci.

[in] pInitSink

Pointeur IWbemProviderInitSink utilisé par le fournisseur pour signaler l’initialisation status.

Valeur retournée

Le fournisseur doit retourner WBEM_S_NO_ERROR et indiquer son status à l’aide du récepteur d’objets fourni dans le paramètre pInitSink. Toutefois, si un fournisseur retourne WBEM_E_FAILED et n’utilise pas le récepteur, l’initialisation du fournisseur est considérée comme ayant échoué.

Remarques

En règle générale, le fournisseur implémente un objet COM à l’aide de plusieurs héritages pour prendre en charge l’interface IWbemProviderInit ainsi que son interface principale, telle que IWbemServices ou IWbemEventProvider.

L’status d’initialisation est signalée en appelant IWbemProviderInitSink ::SetStatus. Cette méthode peut être appelée à plusieurs reprises pour signaler les status incrémentielles si nécessaire. Le fournisseur doit incrémenter le nombre de références sur ce pointeur en appelant sa méthode IWbemProviderInit ::AddRef avant de l’utiliser pour communiquer status à Windows Management.

Le fournisseur peut utiliser le pointeur IWbemProviderInitSink de manière synchrone, comme dans l’exemple de code suivant.

HRESULT SampleProvider::Initialize( 
    /* [unique][in] */  LPWSTR wszUser,
    /* [in] */          LONG lFlags,
    /* [in] */          LPWSTR wszNamespace,
    /* [unique][in] */  LPWSTR wszLocale,
    /* [in] */          IWbemServices __RPC_FAR *pNamespace,
    /* [in] */          IWbemContext __RPC_FAR *pCtx,
    /* [in] */          IWbemProviderInitSink __RPC_FAR *pInitSink
    )
{
    // Use AddRef on the pNamespace pointer, if required.

    // Analyze other parameters.

    // Tell Windows Management that you are initialized.
    pInitSink->SetStatus(WBEM_S_INITIALIZED, 0);
    return WBEM_S_NO_ERROR;
}

Le fournisseur peut également utiliser la méthode AddRef sur le pointeur et créer un thread distinct pour terminer son initialisation et revenir immédiatement à partir de l’appel.

Le processus d’initialisation de certains fournisseurs peut impliquer un rappel dans WMI. Un fournisseur qui rappelle WMI et qui doit attendre la fin de cet appel est appelé fournisseur dépendant. De même, un appel à WMI est appelé demande dépendante. Lors de l’implémentation d’Initialize, WMI nécessite qu’un fournisseur dépendant obéisse aux règles suivantes :

Les requêtes dépendantes doivent réutiliser le pointeur IWbemContext que WMI a passé à Initialize.
Cela signifie que tous les appels à WMI effectués pendant l’initialisation doivent réutiliser le pointeur IWbemContext transmis par WMI. Si vous ne le faites pas, cela peut entraîner un blocage.
Les requêtes non dépendantes ne doivent pas réutiliser le pointeur IWbemContext .
Les fournisseurs dépendants doivent envoyer des demandes à WMI à l’aide de l’une des deux stratégies suivantes :
1. Effectuez des requêtes dépendantes avec le thread reçu de WMI.
2. Effectuez des requêtes dépendantes avec un nouveau thread créé par le fournisseur.
Tous les fournisseurs doivent retourner le thread reçu de WMI.
WMI n’autorise en aucun cas un fournisseur à bloquer un thread reçu de WMI.
Le risque de ne pas gérer soigneusement les threads fournis par WMI est qu’un fournisseur peut acquérir tous les threads dans le pool de threads WMI et continuer à bloquer ces threads. Cela entraînerait un blocage du système.

Vous pouvez choisir d’implémenter votre fournisseur in-process. Un fournisseur in-process qui doit se connecter à WMI séparément du processus d’initialisation doit utiliser l’identificateur de classe CLSID_WbemAdministrativeLocator pour accéder à IWbemLocator dans un appel à CoCreateInstance.

L’exemple de code suivant décrit comment utiliser l’identificateur CLSID_WbemAdministrativeLocator dans un tel appel.

  IWbemLocator *pLoc = 0;

  DWORD dwRes = CoCreateInstance(CLSID_WbemAdministrativeLocator, 0, 
      CLSCTX_INPROC_SERVER, IID_IWbemLocator, (LPVOID *) &pLoc);

L’échec de l’utilisation de l’identificateur CLSID_WbemAdministrativeLocator entraîne une erreur Accès refusé. Pour plus d’informations sur l’établissement d’une connexion à WMI, consultez Création d’une application ou d’un script WMI.

Exemples

L’exemple de code suivant décrit comment implémenter Initialize pour un fournisseur de consommateurs d’événements.

HRESULT CMyEventConsumer::Initialize( 
    /* [in] */ LPWSTR pszUser,
    /* [in] */ LONG lFlags,
    /* [in] */ LPWSTR pszNamespace,
    /* [in] */ LPWSTR pszLocale,
    /* [in] */ IWbemServices __RPC_FAR *pNamespace,
    /* [in] */ IWbemContext __RPC_FAR *pCtx,
    /* [in] */ IWbemProviderInitSink __RPC_FAR *pInitSink
    )
{
    pInitSink->SetStatus(WBEM_S_INITIALIZED, 0);

// Optionally, examine the namespace, locale, and so on 
// being used.

    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	wbemprov.h (include Wbemidl.h)
Bibliothèque	Wbemuuid.lib
DLL	Wbemsvc.dll

Voir aussi

IWbemProviderInit

Initialisation d’un fournisseur

Partager via