Indication manager (draft)

A set of functions for managing indications for openlmi project. Generally the manager will provide few functions and will also require some.

I'm still doing changes and developing missing pieces. This is just a dump of mind, how am I seeing how it could work.

Provided functions

• im_create_manager - creates manager with given properties and callback functions
• im_destroy_manager - destroy manager
• im_verify_filter - Call verification callback on given manager and filter
• im_add_filter - add given filter to manager
• im_remove_filter - Remove given filter from manager
• im_start_ind - Start indications manager
• im_stop_ind - Stop indications

The functions are designed to be easily called from CMPI providers.

Required functions - callbacks

• IMFilterChecker - Function called for checking whether filter is allowed for this provider
• IMEventSpawner - blocking function, called when manager is active. When function returns True, the event has occured
• IMInstGather - Called after event occurance. Should return instances which manager will use to send indication

IMInstGather callback function is used only when you don't want to use manager's polling mechanism.

How to use manager in CMPI provider

• You have to provide IMFilterChecker and IMEventSpawner functions. IMInstGather function is also needed if you don't want to use polling (basically because you know after event occurence what instance(s) to provide).
• In Initialize() create manager by calling im_create_manager. Here you will pass callback functions (IMFilterChecker, IMEventSpawner), decide if you want to use polling, provide broker pointer and so on (It has many parameteres and it is not very nice).
• In Cleanup() call im_destroy_manager().
• In AuthorizeFilter() call im_verify_filter().
• In ActivateFilter() call im_add_filter() and rather im_verify_filter() also
• In DeActivateFilter() call im_remove_filter().
• In EnableIndications() call im_start_ind().
• In DisableIndications() call im_stop_ind().

Polling mechanism

For polling the manager is using CBEnumInstances(), which returns enumeration of instances. The enumeration is converted to CMPIArray, cloned and stored. The first poll is done at the start of managing (run by im_start_ind()). Every other poll is done after event occurence. Manager is storing pair of enumerations (arrays), older polled instances and current instances, so it can be easily used for further indication delivery - for instance modification you need previous and current instance properties.

How manager knows which instances to poll? The manager go thru all stored filters. The filter is broken down to select expression and further to predicates. The first occurance of ISA operator is recognised and RHS of such predicate is used. Example filter Query: "SELECT * FROM LMI_AccountInstanceCreationIndication WHERE SourceInstance ISA LMI_Account". In this case the manager will be polling LMI_Account instances.

C function prototypes and typedefs

// callback functions
typedef bool (*IMInstGather) (CMPIInstance *old, CMPIInstance *new, void *data);
typedef bool (*IMFilterChecker) (const CMPISelectExp *filter);
typedef bool (*IMEventSpawner) (void *data);

// Create manager with given properties and callbacks.                          
// gather may not be specified if you want to use polling                       
// Return newly created IMManager or NULL and appropiate IMError is set         
IMManager* im_create_manager(IMInstGather gather, IMFilterChecker f_checker,    
                             bool polling, IMEventSpawner spawner,              
                             IMIndType type, CMPIBroker *broker,                
                             CMPIContext *ctx, IMError *err);                   
                                                                                                                                  
// Destroy given manager.                                                                                                         
// Return true when ok or false and IMError is set                              
bool im_destroy_manager(IMManager *manager, IMError *err);                      
                                                                                                                                  
// Call verification callback on given manager and filter.                      
// Return true if filter is verified. False if not.                             
// IMError will be set to to other value than IM_ERR_OK                         
// if verification failed                                                                                                         
bool im_verify_filter(const IMManager *manager,                                 
                      const CMPISelectExp *filter, IMError *err);               
                                                                                                                                  
// add given filter to manager.                                                 
// Return true when all is ok, otherwise false and IMError                      
// is as appropriate.                                                           
bool im_add_filter(IMManager *manager, CMPISelectExp *filter,                   
                   IMError *err);                                               
                                                                                
// Remove given filter from manager.                                            
// Return true when removed, false if not and appropriate IMError is set.       
bool im_remove_filter(IMManager *manager, const CMPISelectExp *filter,          
                      IMError *err);                                            
                                                                                
// Start indications.                                                           
// Return true when correctly started, false if not and                         
// appropriate IMError is set,                                                  
bool im_start_ind(IMManager *manager, IMError *err); 

// Stop indications.                                                            
// Return true when correctly stopped, false if not and                         
// appropriate IMError is set,                                                  
bool im_stop_ind(IMManager *manager, IMError *err);

Sources