Indications

From CIM point of view, an indication is the representation of the occurrence of an event. Indications are classes so they can have properties and methods. Instances of an indication are transient and can not be obtained by using CIM Operations, such as GetInstance() or EnumerateInstances(). Indications can only be received by subscribing to them.

An indication subscription is performed by the creation of an CIM_IndicationSubscription association instance that references an CIM_IndicationFilter (a filter) instance, and an CIM_IndicationHandler (a handler) instance. The filter contains the query that selects an Indication class or classes. The size and complexity of the result delivered to the destination is defined by the query.

LMIShell can perform an indication subscription, by which we can receive such event responses. The shell also provides a mechanism for the indication reception.

Indication handler

When working with indications, the first step is to set up an indication handler. This is a routine that will be triggered when the CIMOM sends us an indication for which we have subscribed (see below). It is important to set up the handler first so that we can generate a unique registration name and avoid conflicts with other clients that may wish to register for the same indication. The indication handler may be part of the same process that will initiate the provider registration or it may be an independent script, but the unique registration name must be acquired first in either case.

The following example describes creating a handler and a listener for an indication:

> def handler(indication, arg1, arg2, **kwargs):
...    """
...    Indication handler.
...
...    :param wbem.CIMInstance indication: exported wbem.CIMInstance
...    :param arg1: ...
...    :param arg2: ...
...    ...
...    """
...    do_something_with(indication)
> listener = LMIIndicationListener(listening_address, listening_port, certfile, keyfile, trust_store)
> unique_name = listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2, **kwargs)
> listener.start()
>

The first argument of the handler is a wbem.CIMInstance object; the exported indication. The other arguments are handler-specific; Any number of arguments may be specified as necessary; those arguments must then be provided to the LMIIndicationListener.add_handler() method of the listener. In the above example, the string used in the LMIIndicationListener.add_handler() call is specified with, at least, eight “X” characters. Those characters will be replaced by unique string, which is generated by the listeners to avoid a handler name clash. Use of this uniqueness capability is not mandatory but is highly recommended. The substituted name is returned as the result of the LMIIndicationListener.add_handler() method so it can be used later.

When all necessary handlers are registered, the listener can be started by calling LMIIndicationListener.start().

When a secure connection is desired, LMIIndicationListener can be constructed with keyfile, certfile and trust_store (paths to X509 certificate, private key in PEM format and trust store).

Subscribing to an indication

Now, when the indication listener is up and running, the indication subscription can be done. The LMIShell is capable of creating an indication subscription with the filter and handler objects in one single step.

Example of indication subscription with 3 mandatory arguments:

> c = connect("host", "privileged_user", "password")
> c.subscribe_indication(
...    Name=unique_name,
...    Query='SELECT * FROM CIM_InstModification',
...    Destination="http://192.168.122.1:%d" % listening_port
...  )
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

NOTE: Make sure, that you an account which has write privileges in the root/interop namespace.

The indication subscription can created with an extensive list of arguments, where optional arguments can be specified:

  • QueryLanguage: DMTF:CQL
  • CreationNamespace: root/interop
  • SubscriptionCreationClassName: CIM_IndicationSubscription
  • FilterCreationClassName: CIM_IndicationFilter
  • FilterSystemCreationClassName: CIM_ComputerSystem
  • FilterSourceNamespace: root/cimv2
  • HandlerCreationClassName: CIM_IndicationHandlerCIMXML
  • HandlerSystemCreationClassName: CIM_ComputerSystem
> c = connect("host", "privileged_user", "password")
> c.subscribe_indication(
...    QueryLanguage="WQL",
...    Query='SELECT * FROM CIM_InstModification',
...    Name=unique_name,
...    CreationNamespace="root/interop",
...    SubscriptionCreationClassName="CIM_IndicationSubscription",
...    FilterCreationClassName="CIM_IndicationFilter",
...    FilterSystemCreationClassName="CIM_ComputerSystem",
...    FilterSourceNamespace="root/cimv2",
...    HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
...    HandlerSystemCreationClassName="CIM_ComputerSystem",
...    Destination="http://192.168.122.1:%d" % listening_port
...  )
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

In this state, we have a indication subscription created.

Auto-delete subscriptions

By default all subscriptions created by LMIShell will be auto-deleted, when the shell quits. To change this behavior, you can pass Permanent=True keyword parameter to LMIConnection.subscribe_indication() call, which will prevent LMIShell from deleting the subscription.

Listing subscribed indications

To list all the subscribed indications, run following code:

> c.print_subscribed_indications()
...
> subscribed_ind_lst = c.subscribed_indications()
>

Unsubscribing from an indication

By default, the subscriptions created by the shell are auto-deleted, when the shell quits.

If you want to delete the subscriptions sooner, you can use the following methods:

To unsubscribe from a specific indication:

> c.unsubscribe_indication(unique_name)
LMIReturnValue(rval=True, rparams={}, errorstr="")

Or to unsubscribe from all indications:

> c.unsubscribe_all_indications()
>