User's Manual

4-20 Millennial Net
Using the MeshScape API
Notes on Event Notification and Event Masks - It is important to note that there are two
techniques for receiving event notification: either by registering a callback which will be called
when the event(s) occur or by waiting (blocking) until the desired event(s) occur.
When using the callback mechanism the event mask must be registered by using
ibApi_SetEventMask(). This API will register a global event mask for all devices in the network.
When any of the events specified in the mask occur for any device in the network, the callback
registered via ibApi_RegisterEvent() will be called. If there is data associated with the event, it will
be passed to the callback function.
When using the wait (blocking) mechanism an event mask is specified as an argument to the wait
call (see api definitions below). NOTE that if a global event mask is in place (set with
ibApi_SetEventMask()) ONLY THE EVENTS that occur in the INTERSECTION of the two event
masks will be received while waiting. This allows you to specify a general event mask for your
entire network, and to filter on a very specific subset of events specified in the global mask. Also
note that when using the wait mechanism that an additional call is required to retreive the data (if
any) associated with the event.
11. ibApi_WaitForDeviceEvent()
ibApi_FUNC ibApi_WaitForDeviceEvent(
ibApi_APIHANDLE api_hdl,
ibApi_DEVICEEVENTTYPEevent_types,
ibApi_INT32 timeout ms,
ibApi_DEVICEID * device_id
);
Note: This function is now obsolete and only retained for backward
compatibility. Please use ibApi_WaitForDeviceEvents() instead.
This function implements the simplest form of event notification using the application thread
content: It causes the calling thread to sleep until a network packet has arrived (i.e., the
sequence number has incremented), and then returns the ID of the device that was updated.
If multiple devices have changed since the last call, ibApi_WaitForDeviceEvent() will
return their ID’s in sequential round-robin order. If time timeout expires and nothing has
changed, the return value ibApi_RESULT_ERR_TIMEOUT.
Parameters:
api_hdl: (input) API handle returned from ibApi_Open().
event_types: (input) This parameter is reserved for a future feature allowing the wait
condition to be restricted to a subset of the possible event types.
timeout_ms: Number of milliseconds to wait before giving up (use -1 to wait indefinitely).
device_id: (output) ID of the device that changed.
Return Value:
An ibApi_RESULT_SUCCESS if a device changed, ibApi_RESULT_ERR_TIMEOUT if not, or an
error code (<0) if unsuccessful.