CHAPTER 2. OPENIPMI
When an external event comes into OpenIPMI, the user will always receive that event in some manner (unless they do not register with a generic event handler, but they should always do that). The event may come through a callback for a sensor, control, entity, or other callback.
All the callbacks you should be using return a value telling whether the handler has “handled” the event. Handling the event means that the callback is going to manage the event. Primarily, this means that it is responsible for deleting the event from the event log with ipmi_event_delete(). If no callback handles the event, then it will be delivered to the main event handler(s). This allows calls to receive events but the events to be managed in a single location.
To handle the event, the event handler should return IPMI_EVENT_HANDLED. To pass the event on, it should return IPMI_EVENT_NOT_HANDLED.
If a callback handles the event, then all future callbacks called due to the event will receive a NULL for the event. So be ready to handle a NULL event in all your event handlers. A NULL may also be passed to an event handler if the callback was not due to an event.
Where OpenIPMI Gets Its Data
OpenIPMI generally gets all of its data from the IPMI system, either from SDRs, the event log, or via commands. OpenIPMI will pull in anything it can recognize. Note that some data in an IPMI system is duplicated; if the data is not consistent it will continue to be inconsistent in OpenIPMI.
For instance, OpenIPMI gets all the information about a management controller from the “Get Device Id” command. However, the system may have a record in the SDR repository describing an entity that represents the management controller. If the data from the command and the SDR repository is inconsistent, OpenIPMI will happily provide the data from the SDR repository when looking at the entity, and the data from the “Get Device Id” command when looking at the MC.
If the system has OEM controls and sensors, they may have been created by OEM code and may not have come from SDRs (thus the phrase “generally” in the first sentance of this section). This is a major reason not to use direct IPMI messaging with OpenIPMI. OpenIPMI provides an abstraction for the sensors and controls and thus multiple implementations can sit below it. If software bypasses the abstraction, it will loose the ability to talk to non-standard sensors and controls that use the same abstraction.
As you will discover, OpenIPMI is very callback based. The callbacks are somewhat fined grained; you register for exactly what you want to see on individual objects. This is not as bad as you might imagine (even though it may seem somewhat strange). It does mean that you have to do a lot of registering in all the right places, though. IPMI has a large number of asyncronous things that it has to inform you about. If it delivered all these through one interface, you would have to look at each call and try to figure out what type of things was being reported, what object is was associated, etc. In effect, that work is done by OpenIPMI.
For user-level callbacks, the object the callback is for will always be valid, it will never be NULL. This means, for instance, if you request a reading from a sensor, the reading response will always get called and the sensor parameter will always be valid. It may be in the destruction process and you cannot set any setting, get any readings, or anything else that requires sending a message. If the handler gets an ECANCELED error, the sensor is being destroyed. This also applies to all control, entity, and most domain callbacks. This is new for OpenIPMI 1.4, but is fully backwards compatible.