|
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.
|
|