License / Documentation home / Help and feedback |
Sometimes, the user might find it convenient to poll stdin periodically, as a way of getting input from the user or as a way of allowing the user to control when certain events occur (such as when an audio device starts to listen). We provide a way of doing a non-blocking poll on stdin, and controlling the behavior when a line is read. This functionality is available with the MIT timed task loop or without. On Unix, this utility uses the timed task loop by default; on Windows, it uses Windows threads.
We have provided a complex example of this functionality in our toy travel end-to-end "system".
See the page on compiling and accessing these utilities.
typedef Gal_Frame (*MGal_StdinFrameCreator)(char *str)
MGal_StdinPoll *MGalIO_CreateStdinPoll(char
*prompt, GalIO_CommStruct *comm, MGal_StdinFrameCreator fn,
int ms, int activate)
The prompt is the string which will be printed out to stdout every time the
poll is activated. The comm is a connection to the Hub. The fn
is a function which is called whenever a line of text is read, which creates
a frame which will be sent to the Hub as a new message. The ms are
the number of milliseconds for the Galaxy timed task; 0 is the default (100
ms), -1 means don't set up a timed task, and anything else is taken as a
number of milliseconds. The activate argument should be 1 if the poll
should be activated immediately, 0 if the poll will be activated later.
The fn may choose not to return a frame, in which case polling continues.
MGal_StdinPoll *MGalSS_EnvCreateStdinPoll(char
*prompt, GalSS_Environment *env, MGal_StdinFrameCreator fn,
int ms, int activate)
The environment-aware version of MGalIO_CreateStdinPoll. See the documentation
on session management.
void MGal_ActivateStdinPoll(MGal_StdinPoll
*poll_struct)
This function activates the poll, which means that the prompt is printed
out and a timed task is created, if the polling milliseconds are not -1.
If you're in a dispatch function and you return the poll structure from _GalSS_init_server,
you can access the poll structure using GalIO_GetServerData:
Gal_Frame reinitialize(Gal_Frame f, void *server_data)Typically, you'll reactivate the poll every time you want to start listening again. It is possible to call MGal_ActivateStdinPoll within the frame creation function to restart the poll immediately, whether or not the frame creation function returns a frame.
{
/* set up poll for stdin */
MGal_ActivateStdinPoll((MGal_StdinPoll *) GalIO_GetServerData(server_data));
return f;
}
void MGal_SetStdinPollData(MGal_StdinPoll
*poll_struct, void *data)
This function sets the data for the poll object to some arbitrary element
for later retrieval.
void *MGal_GetStdinPollData(MGal_StdinPoll
*poll_struct)
This function retrieves the arbitrarily stored data.
void MGal_SetStdinPollPrompt(MGal_StdinPoll
*poll_struct, char *prompt)
Resets the poll's prompt. This does not take effect util MGal_ActivateStdinPoll
is called the next time.
void MGal_FreeStdinPoll(MGal_StdinPoll
*poll_struct)
Use this function to free a poll structure. This should always be called
when terminating. On Windows, it's especially important, because it notifies
the thread which reads from stdin to shut down.
int MGal_PollStdin(MGal_StdinPoll
*poll_struct)
This is the polling function to use with the polling structure. It returns
1 if it read a line successfully, 0 if it hasn't encountered a line yet.
License / Documentation home / Help and feedback |