Implementing a Physical Consumer

A physical consumer is a COM object that implements the IWbemUnboundObjectSink interface. WMI loads your physical consumer and passes events through IWbemUnboundObjectSink in response to one or more events, as defined by the associated logical consumer. Permanent consumers have special security requirements. For more information, see Securing WMI Events.

The following procedure describes how to implement a physical consumer for a permanent event consumer.

To implement a physical consumer for a permanent event consumer

1. Create a COM object.

   You must implement a physical consumer as a local or remote server using the COM protocol.

2. Determine if you want to support synchronous or asynchronous event notification.

   With asynchronous event notification, the sending thread is unrelated to the receiving thread. Therefore, neither WMI nor the event provider gets blocked while WMI delivers a notification to any consumer registered to receive the event. The disadvantage to asynchronous delivery is that a context switch occurs between the time the provider produces the event and the time the consumer receives the event. For more information about working asynchronously, see the COM Fundamentals topic in the COM section of the Microsoft Windows Software Development Kit (SDK). For more information about context switches, see the Context Switches topic in the DLLs, Processes, and Threads section of the Windows SDK.

   Note

   Because the callback to the sink might not be returned at the same authentication level as the client requires, it is recommended that you use semisynchronous instead of asynchronous communication. For more information, see Calling a Method.

    

   With synchronous notification, WMI delivers the notification on the same thread that the event provider used to deliver the event to WMI. In this case, when an event provider sends a notification, the event provider is blocked by WMI until WMI delivers the notification. Only if your consumer is extremely fast and can process an event in 100 microseconds or less should you consider supporting synchronous notification. Synchronous consumers that take too long to process events can seriously slow the delivery of events to all other consumers. Furthermore, they can inadvertently block the provider. For more information, see Binding an Event Filter with a Logical Consumer.

3. Implement the IWbemUnboundObjectSink::IndicateToConsumer function.

   WMI uses the IndicateToConsumer function to pass the necessary pointers and events to your physical consumer for both synchronous and asynchronous communications. Your implementation of IndicateToConsumer should contain all of the necessary code to respond to an event.

   Unlike a temporary event consumer, you do not need to call the IWbemLocator interface to contact WMI. Instead, WMI locates a pointer to your consumer through the event consumer provider. For more information, see Writing an Event Consumer Provider.

   However, if you wish to call back into WMI, use the IWbemLocator and IWbemServices interfaces. The traditional method for connecting to WMI is during the initialization process of your COM object. For more information, see Creating a WMI Application or Script.

   If you implement your physical consumer as an in-process COM server and connect to WMI separately from the initialization process, you must use the CLSID_WbemAdministrativeLocator class identifier to access the IWbemLocator interface in the call to CoCreateInstance.

   The following example shows how to use the CLSID_WbemAdministrativeLocator class identifier to access the IWbemLocator interface.

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

   The IWbemLocator interface obtains the initial namespace pointer to WMI on a particular host computer. Failure to use the CLSID_WbemAdministrativeLocator identifier in the CoCreateInstance call results in an "access denied" error.

   Under usual circumstances, WMI delivers asynchronous events to the client one at a time. However, if a client cannot receive asynchronous event notifications as fast as the events arrive, WMI starts to automatically batch events into a single call. Automatic batching helps if the round-trip times are a problem, as is often the case in high-throughput scenarios. However, batching does not improve system performance if the client or the network bandwidth are at fault.