Callbacks & Events

Changes in the system/computers’ statuses/their devices can happen any moment.

To enable the application to respond promptly to the changes, the callback function is used, that is called by the Development Kit library as the new events arrive.

The events themselves can be polled either by the callback function or on schedule, or using any other method.

Use FH_SetEventCallback function to set the custom callback function to process the events.
To discard the custom callback function, pass NULL parameter to FH_SetEventCallback.
When setting the custom callback function, adding new events to the queue is included automatically.

Your application can also explicitly permit or prohibit adding events to the queue via FH_EnableEventsQueue function.
The explicit queue management has priority over the automatic one.

FH_IsEventsQueueEnabled is used to check whether adding events to the queue is allowed.

To read new events from the queue use FH_GetEvents function. It allows reading events one by one or several at a time, or just check whether there are unread events in the queue. Each read event is deleted from the queue automatically.

Notes:

  1. The callback function is called no matter whether adding new events to the queue is currently allowed or not.
  2. In case the events queue is allowed and it contains events, the events are not deleted from the queue when FH_EnableEventsQueue(FALSE) is called.
  3. Calling FH_GetEvents(0, NULL) allows checking whether the queue contains unread events without deleting them.
  4. Calling FH_GetEvents(-1, NULL) deletes all the events in the queue and returns an indication whether events exist in the queue.
  5. The callback function is called again only when new events arrive.
    In case the callback function is called after the arrival of several events but the application does not read all the queued events and exits the callback function, there will be no second callback function calling until a new event arrives.
  6. It’s possible to read events via FH_GetEvents function using either the callback function or any other function of the client’s application.
  7. Upon changes of the info about the specified computer or the devices list, only one event is added to the events queue until it is read and deleted from the queue. However, only the current computer status is returned to the application upon reading of such event.