Indications

Indication is a reaction to some specific event that occurs in response to a particular change in data. LMIShell can perform an indication subscription, by which we can receive such event responses.

Indication handler

The first step is to set up an indication handler. This is a routine that will be triggered when the OpenLMI sends us an indication for which we have registered (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 CIMInstance indication: exported lmiwbem.CIMInstance
...    :param arg1: ...
...    :param arg2: ...
...    ...
...    """
...    do_something_with(indication)
> listener = LMIIndicationListener()
> unique_name = listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2, **kwargs)
> listener.start(listening_port, cert_file, key_file)
>

The first argument of the handler is a lmiwbem.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(), which takes up to three arguments, one mandatory (port) and two optional when using SSL (cert_file and key_file; paths to X509 certificate and private key in PEM format).

Subscribing to an indication

The LMIShell is capable of creating an indication subscription with the filter and handler objects in one single step. This example is based upon sblim-cmpi-base provider.

How to subscribe to an indication, please, follow the next example:

> 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 computer, where the indications will be delivered
...    Destination="http://192.168.122.1:%d" % listening_port
...  )
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

The previous code can be simplified by omitting some optional parameters:

  • QueryLanguage: DMTF:CQL
  • CreationNamespace: root/interop
  • SubscriptionCreationClassName: CIM_IndicationSubscription
  • FilterCreationClassName: CIM_IndicationFilter
  • FilterSystemCreationClassName: CIM_ComputerSystem
  • FilterSourceNamespace: root/cimv2
  • HandlerCreationClassName: CIM_IndicationHandlerCIMXML
  • HandlerSystemCreationClassName: CIM_ComputerSystem

Simplified subscription:

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

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

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()
>