206 lines
8.3 KiB
Plaintext
206 lines
8.3 KiB
Plaintext
WMI Pseudo Provider Programming Guide
|
|
=====================================
|
|
|
|
All information contained herein is Copyrighted by Microsoft
|
|
Corporation. This is preliminary documentation and subject
|
|
to change without notice. It will be superceded by the
|
|
SDK documentation when published.
|
|
|
|
Introduction
|
|
============
|
|
The Pseudo Provider has been designed to allow an Event
|
|
Provider to be decoupled from Windows Management. When an
|
|
Event Provider has been implemented to use the Pseudo
|
|
Provider, Windows Management will not start the Event
|
|
Provider in response to a query for the events provided by
|
|
the Event Provider. The Event Provider may start, execute,
|
|
provide events, and shut down all without direct interaction
|
|
with Windows Management. The Event Provider does not even
|
|
need to support any CoCreate-able objects.
|
|
Requirements
|
|
|
|
In addition to the Windows Management requirements, the
|
|
Pseudo Provider requires that three DLLs be installed and
|
|
registered with RegSvr32. The DLLs are PseuProx.DLL (proxy);
|
|
PseudoProv.DLL (In Proc to Windows Management); and
|
|
PseudoSink.DLL (In Proc to the provider).
|
|
|
|
Limitations
|
|
===========
|
|
The Pseudo Provider can handle up to 256 different Event
|
|
Providers all providing the same event class in the same
|
|
namespace. Note that Windows Management is unaware that
|
|
multiple providers are involved, therefor all calls that
|
|
would go to one provider (e.g. AccessCheck()) will go to all
|
|
providers registered for that class in that namespace.
|
|
|
|
Programming Interface
|
|
=====================
|
|
The Event Provider must provide a MOF that registers its
|
|
event class and provider. The event class is derived from
|
|
__ExtrinsicEvent. The provider is declared as an instance of
|
|
Win32PseudoProvider, the Class ID (CLSID) for the provider is
|
|
defaulted by the base class and must not be overridden. An
|
|
instance of __EventProviderRegistration associates the
|
|
Win32PseudoProvider and Event classes.
|
|
|
|
The Win32PseudoProvider class has a DACL property that can be
|
|
used to limit who may publish events. The property is an
|
|
array of bytes which is a representation of an Access Control
|
|
List (ACL.) A Pseudo Provider must be running under a
|
|
context which has GENERIC_WRITE access allowed by the DACL
|
|
property in order to raise events. If the DACL property is
|
|
left NULL, then any user is allowed to raise events.
|
|
|
|
In general, the Event Provider will obtain the
|
|
IWBemDecoupledEventSink interface via CoCreateInstance, then
|
|
call Connect to obtain the sink; call Indicate for each
|
|
instance of the event; and call Disconnect when finished
|
|
providing events. The Pseudo Provider will forward the
|
|
events on to Windows Management if a query is currently
|
|
active for those events.
|
|
|
|
The methods for IWbemDecoupledEventSink, in vtable order:
|
|
|
|
HRESULT Connect(/* [string][in] */ LPCWSTR wszNamespace,
|
|
/* [string][in] */ LPCWSTR wszProviderName,
|
|
/* [in] */ long lFlags,
|
|
/* [out] */ IWbemObjectSink** ppSink,
|
|
/* [out] */ IWbemServices** ppNamespace);
|
|
|
|
|
|
HRESULT SetProviderServices(/* [in] */ IUnknown* pProviderServices,
|
|
/* [in] */ long lFlags);
|
|
|
|
|
|
HRESULT Disconnect(void);
|
|
|
|
API Reference
|
|
=============
|
|
|
|
HRESULT IWbemDecoupledEventSink::Connect(/* [string][in] */ LPCWSTR wszNamespace,
|
|
/* [string][in] */ LPCWSTR wszProviderName,
|
|
/* [in] */ long lFlags,
|
|
/* [out] */ IWbemObjectSink** ppSink,
|
|
/* [out] */ IWbemServices** ppNamespace);
|
|
|
|
|
|
Connects the Event Provider to the Pseudo Provider, and the
|
|
Pseudo Provider to Windows Management. This method must be
|
|
called prior to any other method on this interface. This
|
|
call should always be paired with a corresponding Disconnect
|
|
call.
|
|
|
|
Calls can not be nested; multiple calls to Connect without an
|
|
intervening Disconnect call will result in a memory leak in
|
|
your process.
|
|
|
|
Arguments:
|
|
wszNamespace, wszProviderName - identify the namespace
|
|
and the provider as registered in the MOF. This may be
|
|
in any valid format "root\default", "\\.\root\default",
|
|
or "\\MyComputer\root\default"
|
|
|
|
lFlags - unused in this release, should be zero to
|
|
ensure compatibility with future releases.
|
|
|
|
ppSink - pointer to an IWbemObjectSink*, this is the
|
|
sink to which events must be indicated. The pointer
|
|
returned is AddRef'd: you must call Release() when you
|
|
are finished with it.
|
|
|
|
ppNamespace - pointer to an IWbemServices*, from this
|
|
interface the Event Provider may obtain the class
|
|
object to spawn instances of the Event Object. The
|
|
pointer returned is AddRef'd: you must call Release
|
|
when you are finished with it.
|
|
|
|
Returns:
|
|
WBEM_S_NO_ERROR (0) on successful connection
|
|
WBEM_E_FAILED general failure
|
|
WBEM_E_ACCESS_DENIED if the user's context is
|
|
not allowed by the DACL
|
|
supplied in the
|
|
Win32PseudoProvider instance.
|
|
WBEM_E_OUT_OF_MEMORY if an allocation fails
|
|
WBEM_E_ALREADY_EXISTS upon attempt to connect
|
|
the 257th identical provider
|
|
WBEM_E_INVALID_PARAMETER if unrecognized flags
|
|
were passed in,
|
|
or if the format of the
|
|
namespace is incorrect.
|
|
WBEM_E_INVALID_PROVIDER_REGISTRATION
|
|
If the Win32PseudoProvider
|
|
instance is invalid
|
|
CO_E_WRONG_SERVER_IDENTITY if application is not
|
|
properly registered
|
|
|
|
As well as the documented returns from
|
|
IWbemLocator::ConnectServer
|
|
|
|
|
|
HRESULT IWbemDecoupledEventSink::Disconnect(void);
|
|
|
|
Call this to disconnect the sink from Windows Management.
|
|
You may then call Connect again should you decide to start
|
|
providing events. If you neglect to call Disconnect, You
|
|
should call Release() on the Sink retrieved from the Connect
|
|
call at the same time.
|
|
|
|
Arguments:
|
|
|
|
Returns:
|
|
WBEM_S_NO_ERROR
|
|
|
|
HRESULT IWbemDecoupledEventSink::SetProviderServices(
|
|
/* [in] */ IUnknown* pProviderServices
|
|
/* [in] */ long lFlags);
|
|
|
|
This call is optional, you may call it any time after calling
|
|
Connect. It allows you more communication with Windows
|
|
Management via the IWbemEventProviderQuerySink,
|
|
IWbemEventProviderSecurity, and IWbemEventProvider
|
|
interfaces. If you support any of those interfaces, use
|
|
SetProviderServices to pass it to Windows Management. The
|
|
IUnknown you pass in will be AddRef'd and held by the Pseudo
|
|
Provider, it will not be released until you call Disconnect.
|
|
|
|
Before this call returns, you will receive calls to NewQuery
|
|
on the IWbemEventProviderQuerySink interface; AccessCheck on
|
|
the IWbemEventProviderSecurity and/or ProvideEvents on the
|
|
IWbemEventProvider interface if there are any consumers
|
|
currently interested in your events.
|
|
|
|
The Pseudo Provider supports a specialized version of the
|
|
IWbemEventProvider interface. If you expose this interface,
|
|
the ProvideEvents method will be called with one of two
|
|
flags: WBEM_FLAG_START_PROVIDING when WinMgmt receives a
|
|
request for any event supplied by your provider; and
|
|
WBEM_FLAG_STOP_PROVIDING when the last query is cancelled.
|
|
You may use these notifications to optimize your application
|
|
by controlling the generation of events.
|
|
|
|
Arguments:
|
|
pProviderServices an IUnknown that should be QI-able
|
|
for any or all of IWbemEventProviderQuerySink,
|
|
IWbemEventProviderSecurity, and IWbemEventProvider.
|
|
|
|
lFlags controls the calls to the interfaces. May be a
|
|
combination of:
|
|
WBEM_FLAG_NOTIFY_START_STOP
|
|
To receive ProvideEvents notifications
|
|
|
|
WBEM_FLAG_NOTIFY_QUERY_CHANGE
|
|
To receive NewQuery notifications
|
|
|
|
WBEM_FLAG_CHECK_SECURITY
|
|
To receive AccessCheck inquiries
|
|
|
|
Returns:
|
|
WBEM_S_NO_ERROR (0) on successful connection
|
|
WBEM_E_FAILED general failure
|
|
WBEM_E_OUT_OF_MEMORY if an allocation fails
|
|
WBEM_E_INVALID_PARAMETER if unrecognized flags
|
|
were passed in
|
|
|