| Solstice Enterprise Manager 4.1 Developing C++ Applications |
|
Handling Events
Any network management application that monitors and controls managed resources on a network needs to process information it receives from those managed resources. Such information is contained in event notifications. An event notification is an unsolicited message sent from a managed object that represents a managed resource. Event notifications contain error information and other types of status information.
This chapter explains how to enable applications to handle event notifications.
- Section 7.1 Event Notifications
- Section 7.2 Processing Information in Event Notifications
- Section 7.3 Scheduling Event Handling
- Section 7.4 Filtering Events
- Section 7.5 Simulating an Event
- Section 7.6 Subscribing to Log Record Events
7.1 Event Notifications
An event notification is an unsolicited message sent from a managed object which represents a managed resource. The meaning of an event and the information contained in it depend on the event type. The event types supported by a managed object are defined in the GDMO specification of the managed object class. The event types themselves are defined in the object model of the managed system.
The definition of the events supported by the satellite managed object class in the sample programs is shown in CODE EXAMPLE 7 -1.
The GDMO specification of the objectCreation event is shown in CODE EXAMPLE 7 -2.
CODE EXAMPLE 7-2 GDMO Specification of the objectCreation Event
REGISTERED AS {joint-iso-ccitt ms(9) smi(3) part2(2) notification(10) 6};Standards bodies such as the International Telecommunication Union - Telecommunication Standardization Sector (ITU-T) have written GDMO specifications for events that commonly occur in network management. Before defining your own event types, consult published network management standards to see if the event type you require has already been defined.
For example, recommendation ITU-T X.721/ISO-10165-2 Definition of Management Information defines the event types given in TABLE 7-1.
TABLE 7-1 Event Types Defined in Recommendation ITU-T X.721/ISO-10165-2 attributeValueChange Reports changes to an attribute such as: Addition or deletion of members to one or more multivalued attributes Replacement of the value of one or more attributes Setting attribute values to their defaults communicationsAlarm Reports when an object detects a communications error. environmentalAlarm Reports a problem in the environment. equipmentAlarm Reports a failure in the equipment. integrityViolation Reports that a potential interruption in information flow has occurred such that information may have been illegally modified, inserted, or deleted. objectCreation Reports the creation of a managed object to another open system. objectDeletion Reports the deletion of a managed object to another open system. operationalViolation Reports that the provision of the requested service was not possible due to the unavailability, malfunction, or incorrect invocation of the service. physicalViolation Reports that a physical resource has been violated in a way that indicates a potential security attack. processingErrorAlarm Reports processing failure in a managed object. qualityofServiceAlarm Reports a failure in the quality of service of the managed object. relationshipChange Reports a change in the value of one or more relationship attributes of a managed object. The change results from either internal operation of the managed object or via management operation. securityServiceOrMechanismViolation Reports that a security attack has been detected by a security service or mechanism. stateChange Reports a change in the value of one or more state attributes of a managed object. The change results from either internal operation of the managed object or via management operation. timeDomainViolation Reports that an event has occurred at an unexpected or prohibited time.
7.2 Processing Information in Event Notifications
To monitor and control managed resources, a network management application needs to process information it receives in event notifications. Processing the information in event notifications involves:
- Registering callback functions
- Writing callback functions
- Controlling event-related updates
7.2.1 Registering Callback Functions for Event Handling
Registering a callback function associates the callback function with a particular event type. Register a callback function for each event type you want to process. To register a callback function, call the when function of one of the following classes:
- Platform to handle events from all object instances in the management information server (MIS)
- Image to handle events from a single object instance
- Album to handle events from an object collection
In the call to the when function you have to:
- Specify the event type
- Initialize an instance of the Callback class to represent the callback function associated with the event type
7.2.1.1 Specifying the Event Type
If the event type is recognized by the when function, specify the shorthand form given in TABLE 7-2. If the event type is not recognized by the when function, specify the fully qualified name defined in the GDMO document.
TABLE 7-2 Event Types Recognized by the when Function All RAW_EVENT Album, Image, Platform An event has occurred. The callback is called when an event of any type is received. "Rec. X.721 | ISO/IEC 10165-2:1992":attributeValueChange ATTR_CHANGED Image, Platform An attribute value of an object has changed. "Rec. X.721 | ISO/IEC 10165-2:1992": objectCreation OBJECT_CREATED Album, Image, Platform An object has been created. "Rec. X.721 | ISO/IEC 10165-2:1992": objectDeletion OBJECT_DESTROYED Album, Image, Platform An object has been destroyed. Not defined in a GDMO specification DISCONNECTED Platform The MIS has become disconnected from the application. Not defined in a GDMO specification IMAGE_INCLUDED Album An Image instance was added to this Album instance. Not defined in a GDMO specification IMAGE_EXCLUDED Album An Image instance was deleted from the Album instance. This is an internal event, and has no MIS event information associated with it. Not defined in a GDMO specification WAIT Platform The PMI is entering a wait state. The callback is called again when leaving the wait state, but with a null name.
7.2.1.2 Initializing an Instance of the Callback Class
To initialize an instance of the Callback class, call its constructor in the call to the when function. In the call to the constructor of the Callback class, you must specify:
- The name of the callback function.
- A pointer to the data to be passed as an argument to the callback function. You can specify a null pointer if you do not want to pass any data to the callback function.
7.2.1.3 Example
Code for registering callback functions is shown in CODE EXAMPLE 7- 3.
CODE EXAMPLE 7-3 Registering Callback Functions
plat.when("RAW_EVENT", Callback(raw_cb,0)); //Register eventplat.when("DISCONNECTED",Callback(disc_cb,0));//callback routinesIn this example, the callback function raw_cb is registered so that it is called when the application receives an event of type RAW_EVENT. The callback function disc_cb is registered so that it is called when the application receives an event of type DISCONNECTED. The raw_cb callback function is also called, because an event of type DISCONNECTED is also an event of type RAW_EVENT. No data are passed to either callback function.
7.2.2 Writing Callback Functions for Event Handling
Write a callback function to handle each type of event you want to process. Each callback function you write must contain the code needed to carry out the processing you require. Writing a callback function involves:
- Defining the signature of the callback function
- Extracting information from an event notification
7.2.2.1 Defining the Signature of the Callback Function
The signature of any callback function you write must be in the following format:
- callbackName is the name you assign to your callback function.
- userdata is the data passed to the callback by your application.
- calldata is the data passed to the callback by the scheduler that calls the callback function.
7.2.2.2 Extracting Information From an Event Notification
Extract the information from event notifications that is useful to users of your application. To extract information from an event notification, call functions of the CurrentEvent class in the body of your callback function. An application represents every event notification it receives as an instance of the CurrentEvent class.
The functions for extracting information from an event are listed in TABLE 7-3. They extract the following types of information:
- Event information, which is information on what caused the event notification to be generated
- Contextual information, which is information on the event notification itself
TABLE 7-3 Functions for Extracting Information from Event Notifications Event information The entire event as text. get_event The entire event in encoded form. get_event_raw The event information as text. get_info The event information in encoded form. get_info_raw The name of the event. This name is the human-readable form of the event object identifier (OID). It indicates the event type as defined in the GDMO specification of the event, for example: "Rec. X.721 | ISO/IEC 1016 5-2 :1992":objectDeletion get_name The event OID defined in the GDMO specification of the event. get_oid A pointer to the event. This pointer has no meaning outside the scope of the CurrentEvent object that represents the event notification. get_message Contextual information The Album instance associated with the event. get_album The event type as specified in the call to the when function that registers the callback for the event. get_eventtype The Image instance associated with the event. get_image The class of the managed object represented by the Image instance associated with the event. get_objclass The fully distinguished name (FDN) of the managed object represented by the Image instance associated with the event. get_objname The location of the MIS associated with the event. get_platform The time of the event. get_time A callback function is shown in CODE EXAMPLE 7 -4.
CODE EXAMPLE 7-4 Callback Function
if (!plat.when("RAW_EVENT", Callback(raw_cb,0))) {{if (event_type.contains("objectCreation")) {if (event_class.contains("dish")) {if (!view_permission(distinguished_name)) {} else {When the raw_cb callback defined in this example is called, the application checks the user's permissions to watch the current channel based on the following information extracted from the event:
- The entire text of the event, from which the event type is extracted
- The FDN of the managed object that generated the event
- The class of the managed object that generated the event
7.2.3 Controlling Event-Related Updates
A managed object sends an event notification to inform a management application of a change that has occurred to the managed object. The managed object itself is in an MIS or an agent in the network. To ensure that your application has access to current data about managed resources, the changes need to be propagated to Image and Album instances cached in your application.
Depending on your requirements, you can choose how changes to managed objects are propagated to Image and Album instances cached in your application.
7.2.3.1 Automatically Tracking Changes
Automatically tracking changes causes the MIS to update Image and Album instances cached in your application whenever the MIS receives an event notification.
To track changes automatically, set the TRACKMODE property for Image and Album instances as described in:
- Section 5.9.1 Automatically Tracking Changes to an Object for Image instances
- Section 6.4.1.1 Automatically Maintaining the Membership of an Object Collection for Album instances
7.2.3.2 Overriding Automatic Updates for a Specific Event Type
Overriding automatic updates for a specific event type prevents the MIS from updating Image and Album instances cached in your application whenever the MIS receives an event notification of the specified type. By default, Image and Album instances cached in your application are updated each time an event is received if you track changes to managed objects automatically.
Override automatic updates for a specific event type if:
- You want your application to process the previous values of attributes after an event of the type has been received.
- You want to improve the performance of your application by reducing the traffic between your application and the MIS.
To override automatic updates for specific event types, call the do_nothing function of the CurrentEvent class. Include the call to do_nothing in the callback function for handling the type of event. When you override automatic updates, include code in your callback to process the old values.
7.2.3.3 Tracking Changes From Within a Callback
Tracking changes from within a callback updates Image and Album instances cached in your application when the callback is executed. Track changes from within a callback if:
- You want to track changes manually. Manually tracking changes gives you control over which changes you update Image and Album instances with, and enhances the performance of your application.
- You want to pre-empt automatic updates for a specific event type. Pre-empting automatic updates enables you to access the updated values updates within the callback. By default, automatically tracked Image and Album instances are updated only after the callback has returned control to the application.
To track changes from within a callback, call the do_something function of the CurrentEvent class. Include the call to do_something in the callback function for handling the type of event. When you track changes from within a callback, include code in your callback to process the new values.
Code for tracking changes from within a callback is shown in CODE EXAMPLE 7 -5.
CODE EXAMPLE 7-5 Tracking Changes From Within a Callback
void remove_cb( Ptr, Ptr calldata){if (event_class.contains("dish")) {} else if (event_class.contains("channel")) {In this example, Image and Album instances cached in the application are updated before the exclude function of the Album class is called. Updating the instances before calling exclude ensures that updated values are processed within the remove_cb callback.
7.3 Scheduling Event Handling
An application cannot predict when it will receive an event notification from a managed object. Therefore, to process an event notification, an application must be able to interrupt whatever function is being performed and process the event notification when it is received. To enable an application to interrupt the function it is currently performing, you must add a scheduler to your application. A scheduler retrieves each event from the event queue and calls the function required to process the event correctly.
Solstice EM provides the following schedulers:
- sched - For applications without a graphical user interface
- xtsched - For applications with a graphical user interface
If you want to develop your own scheduler, follow the guidelines given in Section 7.3.3 Guidelines for Developing Your Own Scheduler.
7.3.1 Scheduling for Applications Without a Graphical User Interface
To schedule event handling for an application without a graphical user interface, use the sched scheduler. To use the sched scheduler, call its dispatch_recursive function after all initialization is finished.
When you call the dispatch_recursive function, you have to specify whether the sched scheduler waits before processing an event. To specify this, set the boolean parameter of dispatch_recursive to:
- FALSE - Do not wait before processing events, then return
- TRUE - Wait for an event to be received, process the event, then return
To ensure that your application is able to receive events when they arrive, call the dispatch_recursive function in a loop. If you do not call dispatch_recursive in a loop, it is called only once. Any incoming events that arrive after the call to dispatch_recursive are not processed.
Note – It is typically more efficient to call dispatch_recursive with the parameter set to TRUE. Your application uses fewer CPU cycles while executing in the loop if you set the parameter to TRUE than if you set it to FALSE. If you set the parameter to FALSE, your application loops continually.
CODE EXAMPLE 7- 6 shows a call to the dispatch_recursive function.
CODE EXAMPLE 7-6 Calling the dispatch_recursive Function
while(MIS_Connected) {In this example, the dispatch_recursive function is called while the application remains connected to an MIS.
When the dispatch_recursive function is called, the sched scheduler performs the following actions:
- Checks the event queue for events
- Retrieves each event from the queue
- Identifies the correct callback function for each event retrieved
- Calls the required callback function for each event, passing the event data to it as an argument
To call the dispatch_recursive function in an infinite loop by using a single line of code, use the dispatch_main_loop function. A call to dispatch_main_loop is shown in CODE EXAMPLE 7- 7.
CODE EXAMPLE 7-7 Calling the dispatch_main_loop Function
The dispatch_main_loop function contains the code in CODE EXAMPLE 7- 8.
CODE EXAMPLE 7-8 Contents of the dispatch_main_loop Function
while(TRUE) {7.3.2 Scheduling for Applications With a Graphical User Interface
A graphical application must be able to process two types of events:
- Event notifications from managed objects
- X events resulting from user interaction with the application
To schedule the handling of both types of events, you must use the xtsched scheduler. The xtsched scheduler performs all the functions of the sched scheduler and handles all X events. Using the xtsched scheduler involves:
- Initializing and activating the xtsched scheduler
- Preventing erroneous user input
7.3.2.1 Initializing and Activating the xtsched Scheduler
Initializing the xtsched scheduler sets the application context. Every graphical application based on the X Window system requires an application context. After initializing the xtsched scheduler, activate it.
To initialize the xtsched scheduler, call the xtsched function set_app_context. The set_app_context routine passes the application context to the xtsched scheduler to enable the PMI to control X events.
To activate the xtsched scheduler, call its XtAppMainLoop function after all initialization is finished.
Code for initializing and activating the xtsched scheduler is shown in CODE EXAMPLE 7 -9.
CODE EXAMPLE 7-9 Initializing and Activating the xtsched Scheduler
7.3.2.2 Preventing Erroneous User Input
An application that has to process data from incoming events may fail to respond to user input. In such cases, users often repeat mouse clicks or keystrokes, resulting in erroneous input. By designing your graphical applications to prevent erroneous user input, you can improve their usability. Prevent erroneous user input while an application is processing data by:
- Giving feedback to the user. Indicate to the user that the application is busy by changing the pointer to a watch or an hour glass.
- Blocking user input to the application. Use the set_X_event_processing function of the xtsched scheduler to disable the processing of X events. The set_X_event_processing function accepts a boolean parameter:
- FALSE - Disables the processing of X events, thereby blocking user input
- TRUE - Enables processing of X events, thereby enabling the application to accept user input
Note – If you disable the processing of X events, you must call set_X_event_processing(TRUE) to enable your application to process them again.
Code for disabling and enabling the processing of X events is shown in CODE EXAMPLE 7 -10.
CODE EXAMPLE 7-10 Disabling and Enabling the Processing of X Events
{In this example, when the user selects an item and clicks the Delete button, all further user input is blocked until the item is removed. By blocking user input until the item is removed, the application prevents the user from attempting to delete an object that does not exist, thereby avoiding undesirable effects (for example, an error message or a failure of the application).
7.3.3 Guidelines for Developing Your Own Scheduler
The purpose of a scheduler is to enable an application to respond to events. A scheduler transfers control from the function an application is currently performing to the callback function registered to process the event.
Any scheduler that you develop must contain code that listens on all used file descriptors. In Solstice EM, whenever a callback is registered internally by the PMI or by an application, a file descriptor is used. When an event is received, the file descriptor is set, which causes the PMI to transfer control to the specified callback routine. The schedulers supplied with EM use the select() system call to check for any activity on the open file descriptors.
7.4 Filtering Events
Filtering events makes sure that the MIS only forwards to your application the events that are relevant to the application. Filter events to reduce the amount of network traffic between your application and the MIS it is connected to. By default, the MIS forwards all events it receives to your application.
Depending on the sources of events you want your application to receive, you can filter events by:
- Selecting managed object classes and event types
- Selecting a subtree of the management information tree (MIT)
- Specifying a discriminator construct
7.4.1 Selecting Managed Object Classes and Event Types
If you want your application to receive only events of particular types emitted by instances of particular managed object classes, select those managed object classes and event types. To filter events by selecting managed object classes and event types, call the replace_discriminator_classes function of the Platform class.
In the call to replace_discriminator_classes you must specify:
- A list of the managed object classes
- A list of event types
You must pass the lists of managed object classes and event types to the replace_discriminator_classes function in an array, even if there is only one managed object class or event type in the list.
Code for filtering events by selecting managed object classes and event types is shown in CODE EXAMPLE 7 -11.
CODE EXAMPLE 7-11 Selecting Managed Object Classes and Event Types
if (!plat.connect(server, "platform")) {In this example, the MIS forwards only communicationsAlarm events emitted by instances of the satellite, channel, and dish managed object classes. All other events received by the MIS are not forwarded to the application.
Note – To be certain that your application receives all the events it is interested in, specify only managed object classes in the call to replace_discriminator_classes. If you specify no event types, all events emitted by instances of the specified managed object classes are forwarded.
7.4.2 Selecting a Subtree of the MIT
If you want your application to receive events only from managed objects in a particular subtree of the MIT, select the subtree. To filter events by selecting a subtree of the MIT, call the replace_discriminator function of the Platform class.
In the call to replace_discriminator, you have to specify the subtree by specifying:
- Base managed object. The base managed object specifies the FDN of the object that is the root of the subtree you want to select.
- Scope. The scope specifies which objects contained by the base managed object are selected.
Note – The replace_discriminator function does not allow you to apply a filter to a subtree.
Possible values of the scope in a subtree for the replace_discriminator function are given in TABLE 7-4.
TABLE 7-4 Scope Values in a Subtree for the replace_discriminator Function 0 Only events from the base managed object are received. 1 Only events from first-level subordinates of the base managed object are received. 2 Events from the base managed object and its entire subtree are received. individualLevels : n Only events from level n subordinates of the base managed object are received, where n is an integer. baseToNthLevel : n Events from the base managed object and all its subordinates to level n are received, where n is an integer.
To specify a subtree, construct a filter that tests that the value of the "DNFILTER" : emDnScope attribute equals the base managed object and the scope. The ASN.1 type definition of the "DNFILTER" : emDnScope attribute specifies that it is a SEQUENCE containing a base managed object and a scope.
Code for filtering events by selecting a subtree of the MIT is shown in CODE EXAMPLE 7 -12.
CODE EXAMPLE 7-12 Selecting a Subtree of the MIT
strcpy(discr, "item : equality : {attributeId globalForm : \"DNFILTER\":emDnScope, attributeValue {base distinguishedName : {{{if (!plat.replace_discriminator(DU(discr))) {In this example, the MIS forwards only events emitted by the managed object "/systemId=wisconsin" and all managed objects in its entire subtree.
7.4.3 Specifying a Discriminator Construct
If you want your application to receive events selected according to the values of attributes in the events, specify a discriminator construct. Specifying a discriminator construct enables you to select events according to the values of the following attributes of an event:
- Managed object class
- Managed object instance
- Event type
- Any attribute specific to an event type, for example, for fault-related events:
To filter events by specifying a discriminator construct, call the replace_discriminator function of the Platform class.
In the call to replace_discriminator, you have to specify the discriminator construct. The format of a discriminator construct is identical to the format of a filter in a derivation string. This format is defined in Section 6.3.2.3 Filter.
Note – Section 6.3.2.3 Filter states that a filter in a derivation string is optional. This statement does not apply to a discriminator construct. Additionally, a discriminator construct cannot be combined with a base managed object and a scope.
Code for filtering events by specifying a discriminator construct is shown in CODE EXAMPLE 7 -13.
CODE EXAMPLE 7-13 Specifying a Discriminator Construct
and: {item: equality: {probableCause, corruptData},item: equality: {perceivedSeverity, critical}if (!plat.replace_discriminator(DU(discrim))) {In this example, the MIS forwards only events that have the value corruptData for probableCause and have the value critical for perceivedSeverity.
7.5 Simulating an Event
In a live network, events are generated as a result of activity on the network. If you want to test event handling by your application before it manages a live network, generate events for test purposes.
Depending on the type of event, and the rate at which you want to send events, you can simulate events without using the Solstice EM APIs, or you can simulate them programatically.
7.5.1 Simulating an Event Without Using the Solstice EM APIs
You can generate events for test purposes by simulating an agent object, and creating and modifying objects in the MIS to simulate activity on a network. For more information, see Section 5.11 Simulating an Agent Object.
If you do not want to simulate an agent, use request templates to generate events. For more information on how to use request templates, refer to the Customizing Guide.
7.5.2 Simulating an Event Programatically
To simulate an event programatically, write an application that is acting in an agent role. Simulating an event programmatically involves:
- Creating and initializing an instance of the Image class to represent the managed object that is emitting the event
- Requesting the event to be sent
- Sending the event to the MIS
For information on how to create and initialize an instance of Image, refer to Section 5.2.1 Creating and Initializing an Instance of Image.
To request an event to be sent, call the send_event function of the Image class. In the call to send_event, specify:
- The event type. The event type is defined in the object model of the managed system. It must be one of the event types supported by the managed object.
- The event information. The event information consists of a list of attributes and the values you want to set them to in the event. The list of attributes must be as defined in the GDMO specification of the event type.
To send an event to the MIS, call one of the following schedulers as described in Section 7.3 Scheduling Event Handling:
- sched - For applications without a graphical user interface
- xtsched - For applications with a graphical user interface
Note – The send_event function is a blocking function and does not send an event to the MIS. To send the event, you must call a scheduler after calling the send_event function. Otherwise, the event will be lost.
Code for simulating an event programmatically is shown in CODE EXAMPLE 7 -14.
CODE EXAMPLE 7-14 Simulating an Event Programatically
char event_info[100] = "{ probableCause localValue : 85,"if (im.get_error_type() != PMI_SUCCESS) {if (!im.send_event(event, event_info)) {In this code example, a communicationsAlarm event is sent to the MIS. The probableCause attribute is set to a locally defined value of 85, and the perceivedSeverity attribute is set to critical.
The variable fdn specifies the FDN of a managed object (for example "/systemId=\"mozes\"/satelliteId=\"NorthernLigh ts\""). The variable object_class specifies the name of a managed object class (for example the satellite class from the sample programs). The initialization of the fdn and object_class variables is not shown in the example.
7.6 Subscribing to Log Record Events
An application receives log record events only if it has subscribed to them. Log record events are not sent to an application unless the application has subscribed to them.
Subscribing to log record events involves:
- Selecting the managed object that represents the application's connection to the MIS
- Setting the emSpecialEvents attribute of the managed object to logRecordEvent
For information on how to select a managed object, refer to Section 5.3 Selecting a Managed Object. To obtain the FDN of the managed object that represents the application's connection to the MIS, call the get_prop function of the Platform class. In the call to get_prop, specify the APPLICATION_OBJNAME property.
For information on how to set an attribute of a managed object, refer to Section 5.7 Setting Attribute Values of an Object. You have to set the emSpecialEvents attribute to the text string logRecordEvent. Therefore, call the set_str function of the Image class to set this attribute in the Image instance.
Code for subscribing to log record events is shown in CODE EXAMPLE 7 -15.
CODE EXAMPLE 7-15 Subscribing to Log Record Events
if(!app_image.boot()) {if(!app_image.set_str("emSpecialEvents","{logRecordEvent}")){if(!app_image.store()){
|
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |