ser_sr24_set_event_handler


int   ser_sr24_set_event_handler(
     ser_sr24 handle,   //serial board handle
     ser_event_spec *event   //data structure describing the event notification mechanism
     );

Summary

The ser_sr24_set_event_handler function is used to define the event handler mechanism that will be notified when a hardware event occurs. The event handler mechanism is code that you have written; it will automatically be executed when events occur. This could be a callback function or a Windows message processing loop.

Note: This function disables the previous event-handling mechanism (if any) before processing the event data structure you have passed. This means that if you set an invalid or unsupported event ID in your structure, and this function returns an error, you will be left without an event handler, even if one was set before this function was called.

Parameters

handle:
    This is the handle to the serial board; it is actually a pointer to the data structure for the board.
event:
    This is a pointer to the ser_event_spec data structure which contains data about the event handler mechanism you plan to use. You may pass a NULL pointer for event, in which case the API will disable all event-handling mechanisms (the same effect as setting the type member of your ser_event_spec structure to zero). In all other cases, you must define this data structure and then pass a pointer to the structure to this function. The data structure deserves a complete explanation.
  Data Structure:  ser_event_spec
    typedef struct     /* specifies how events should be handled */
    {
      int type;
      ser_eventfn eventfn;
      void *window;
      unsigned int msgid;
      void *extra;
    } ser_event_spec;

    type: Specifies which event handler mechanism to use. Possible values are:

    0 - None; no event handler will be notified if an event occurs

    1 - Callback function: Using this mechanism, a callback function defined by you, the programmer, will be called whenever a registered event occurs. You must assign the address of your callback function to the 'eventfn' member of this structure (see eventfn below). Using this mechanism, your callback function will be called any time a registered event occurs, regardless of what your program is currently doing. In other words, you do not need to worry about keeping up with a message loop as you do with types 2 and 3. In order to implement this, the callbacks are made by a separate thread, which is created internally by the API. It is important for you, the programmer, to realize and consider this, because it could introduce problems if, for example, your callback attempts to modify a data structure at the same time as your main program.

    2 - Windows messages (Microsoft Windows only): A Windows message will be sent to the window that you specify. You must set the 'window' member of this structure to be the HANDLE of the window that event messages will be sent to. NOTE that a HANDLE is actually a void pointer so you must simply assign your window handle to 'window'. You must also specify which Windows message will be sent to your window. This is set by the 'msgid' member of this structure. A typical value to use would be WM_USER. When the message is sent, wParam will be the event id that occurred, and lParam will be the value of the port or bit.

    3 - Thread-safe callback (Microsoft Windows only): As opposed to event type 1, the callback is not made in a separate thread. This has the advantage of being compatible with Visual Basic, and any other application that cannot handle multiple threads. To implement this, the API internally creates and maintains its own window. Because of this implementation, your application must have a window message processing loop in order for events to work. Note that almost all applications that already create their own window will not require any modification for this mechanism to work.
    Also note that although the above description may sound confusing, you, the programmer, do not need to worry about the details. As with event mechanism 1 above, simply assign the address of your callback function to the 'eventfn' member of this structure (see eventfn below), and any extra data to the 'extra' member.
    eventfn: Used if type is 1 or 3. Pointer to a user defined callback function.
    Your callback function must have this format:

    void function_name(int id, int value, void *extra)

    id specifies the event id that you specified when you registered the event, value is the value that the port or bit now has, and extra is the extra value that you specified in this ser_event_spec data structure.

    Important Note: If you are programming in C or C++ on a Microsoft Windows platform, your callback must use standard calling convention. Most compilers (including Microsoft Visual C++ and lcc) allow you to specify this using the __stdcall keyword. Your function would then be defined as follows:

    void __stdcall function_name(int id, int value, void *extra)

    If you are programming on a Linux platform, nothing special must be done.
    window: Used if type is 2: Window handle to send a message to
    msgid: Used if type is 2: The windows message id to be sent. Examples: WM_USER, WM_CLICK, etc.
    extra: Used if type is 1 or 3: extra data to be passed to the callback.
   

Return Values

Function returns 0 upon success. Possible error codes include:

Sample

The following code segment illustrates how to set the event handler to your own callback function (type 1). Simply changing the type to 3 would allow this code to set a thread-safe callback handler.

First, define your callback function in your source file:

/* The __stdcall keyword is only necessary for Windows programs.  Simply
   remove it for a Linux program.
 */

void __stdcall event_callback(int id, int value, void *extra)
{
	/* substitute your own custom code here */
	
	printf("Event id %d has occurred with a value of %d\n", id, value);
}

This code segment would then appear in your main program:


/* serial board has already been opened, and the handle stored in 'handle' */
ser_event_spec evspec;
int result;

evspec.type = 1;
evspec.eventfn = event_callback; /* store the address of the function defined above */
evspec.extra = 0;

result = ser_sr24_set_event_handler(handle, &evspec);

if(result) /* if the function didn't return zero, there was an error */
	printf("Error setting event handler: %s\n", ser_sr24_error_string(result));

Visual Basic Notes

There is no need for a Visual Basic equivalent of this function. The object.HardwareEvent routine is automatically set up to execute when any hardware event occurs. Put code in here to respond to events.




Back to Contents Winford Engineering (2000)