Método IWbemProviderInit::Initialize (wbemprov.h)

Artigo
08/27/2023

O método IWbemProviderInit::Initialize é chamado pelo Gerenciamento do Windows para inicializar um provedor para receber solicitações de cliente. Todos os tipos de provedores devem implementar esse método.

Sintaxe

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

Parâmetros

[in] wszUser

Um ponteiro para o nome de usuário, se a inicialização por usuário tiver sido solicitada no __Win32Provider instância de registro para esse provedor. Caso contrário, isso será NULL.

Lembre-se de que esse parâmetro é definido como NULL para provedores de consumidores de eventos, independentemente do valor da propriedade PerUserInitialization na instância __Win32Provider para o provedor.

[in] lFlags

Reservado. Esse parâmetro deve ser 0 (zero).

[in] wszNamespace

Um nome de namespace para o qual o provedor é inicializado.

[in] wszLocale

Nome da localidade para a qual o provedor está sendo inicializado.

Uma cadeia de caracteres do seguinte formato, em que o valor hexadecimal é um valor LCID padrão da Microsoft:

"MS_409"

Esse parâmetro pode ser NULL.

[in] pNamespace

Um ponteiro IWbemServices de volta para o Gerenciamento do Windows. Esse ponteiro pode atender a todas as solicitações feitas pelo provedor. O provedor deve usar o método IWbemProviderInit::AddRef nesse ponteiro se ele for chamar de volta para o Gerenciamento do Windows durante sua execução.

[in] pCtx

Um ponteiro IWbemContext associado à inicialização. Esse parâmetro pode ser NULL.

Se o provedor executar solicitações de volta no Gerenciamento do Windows antes de concluir a inicialização, ele deverá usar o método IWbemProviderInit::AddRef nesse ponteiro. Para obter mais informações, consulte Fazer chamadas para o WMI.

Caso um provedor precise fazer uma solicitação dependente em outro provedor, você deverá passar essa cadeia de caracteres de contexto de volta para o WMI para evitar possíveis bloqueios. No entanto, no caso de uma solicitação independente, isso não é necessário e o WMI gera uma nova cadeia de caracteres de contexto para ela.

[in] pInitSink

Um ponteiro IWbemProviderInitSink usado pelo provedor para relatar status de inicialização.

Retornar valor

O provedor deve retornar WBEM_S_NO_ERROR e indicar sua status usando o coletor de objeto fornecido no parâmetro pInitSink. No entanto, se um provedor retornar WBEM_E_FAILED e não usar o coletor, a inicialização do provedor será considerada como com falha.

Comentários

Normalmente, o provedor implementa um objeto COM usando várias heranças para dar suporte à interface IWbemProviderInit , bem como à interface primária, como IWbemServices ou IWbemEventProvider.

A inicialização status é relatada chamando IWbemProviderInitSink::SetStatus. Esse método pode ser chamado repetidamente para relatar status incrementais, se necessário. O provedor deve incrementar a contagem de referência nesse ponteiro chamando seu método IWbemProviderInit::AddRef antes de usá-lo para comunicar status ao Gerenciamento do Windows.

O provedor pode usar o ponteiro IWbemProviderInitSink de forma síncrona, como no exemplo de código a seguir.

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;
}

O provedor também pode usar o método AddRef no ponteiro e criar um thread separado para concluir sua inicialização e retornar imediatamente da chamada.

O processo de inicialização de alguns provedores pode envolver a chamada de volta para o WMI. Um provedor que chama de volta para o WMI e deve aguardar a conclusão dessa chamada é chamado de provedor dependente. Da mesma forma, uma chamada ao WMI é chamada de solicitação dependente. Ao implementar Initialize, o WMI exige que um provedor dependente obedeça às seguintes regras:

As solicitações dependentes devem reutilizar o ponteiro IWbemContext que o WMI passou para Inicializar.
Isso significa que todas as chamadas feitas no WMI durante a inicialização devem reutilizar o ponteiro IWbemContext que o WMI passou. Não fazer isso pode resultar em deadlock.
As solicitações não dependentes não devem reutilizar o ponteiro IWbemContext .
Os provedores dependentes devem fazer solicitações ao WMI usando uma das duas estratégias a seguir:
1. Faça solicitações dependentes com o thread recebido do WMI.
2. Faça solicitações dependentes com um novo thread criado pelo provedor.
Todos os provedores devem retornar o thread recebido do WMI.
Em nenhuma circunstância, o WMI permite que um provedor bloqueie um thread recebido do WMI.
O perigo de não lidar cuidadosamente com os threads fornecidos pelo WMI é que um provedor pode adquirir todos os threads no pool de threads WMI e continuar bloqueando esses threads. Isso resultaria em um sistema com deadlock.

Você pode optar por implementar seu provedor em processo. Um provedor em processo que deve se conectar ao WMI separadamente do processo de inicialização deve usar o identificador de classe CLSID_WbemAdministrativeLocator para acessar IWbemLocator em uma chamada para CoCreateInstance.

O exemplo de código a seguir descreve como usar o identificador CLSID_WbemAdministrativeLocator em tal chamada.

  IWbemLocator *pLoc = 0;

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

A falha ao usar o identificador CLSID_WbemAdministrativeLocator resulta em um erro de Acesso Negado. Para obter mais informações sobre como fazer uma conexão com o WMI, consulte Criando um aplicativo WMI ou script.

Exemplos

O exemplo de código a seguir descreve como implementar Initialize para um provedor de consumidor de eventos.

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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wbemprov.h (include Wbemidl.h)
Biblioteca	Wbemuuid.lib
DLL	Wbemsvc.dll

Confira também

IWbemProviderInit

Inicializar um provedor

Compartilhar via

Método IWbemProviderInit::Initialize (wbemprov.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais