silc_stream_set_notifier and silc_schedule_set_listen_fd now

[silc.git] / lib / silcutil / silcschedule.h

diff --git a/lib/silcutil/silcschedule.h b/lib/silcutil/silcschedule.h
index 85bbf339c6c8d4fb3f68fbfdedf20b4406bdb613..32557df955290a00467e7526e0335d35e56ee23b 100644 (file)
--- a/lib/silcutil/silcschedule.h
+++ b/lib/silcutil/silcschedule.h
@@ -293,6 +293,14 @@ void silc_schedule_stop(SilcSchedule schedule);
  *    When this returns the program is to be ended. Before this function can
  *    be called, one must call silc_schedule_init function.
  *
+ * NOTES
+ *
+ *    On Windows this will block the program, but will continue dispatching
+ *    window messages, and thus can be used as the main loop of the program.
+ *
+ *    On Symbian this will return immediately.  On Symbian calling
+ *    silc_schedule is same as calling silc_schedule_one.
+ *
  ***/
 void silc_schedule(SilcSchedule schedule);
 
@@ -311,6 +319,10 @@ void silc_schedule(SilcSchedule schedule);
  *    scheduler.  The function will not return in this timeout unless
  *    some other event occurs.
  *
+ *    Typically this would be called from a timeout or idle task
+ *    periodically (typically from 5-50 ms) to schedule SILC tasks.  In
+ *    this case the `timeout_usecs' is usually 0.
+ *
  ***/
 SilcBool silc_schedule_one(SilcSchedule schedule, int timeout_usecs);
 
@@ -363,6 +375,9 @@ void *silc_schedule_get_context(SilcSchedule schedule);
  *    handle.  To receive events for the file descriptor set the correct
  *    request events with silc_schedule_set_listen_fd function.
  *
+ *    The task will be initially set for SILC_TASK_READ events.  Setting that
+ *    event immediately after this call returns is not necessary.
+ *
  ***/
 #define silc_schedule_task_add_fd(schedule, fd, callback, context)     \
   silc_schedule_task_add(schedule, fd, callback, context, 0, 0,        SILC_TASK_FD)
@@ -381,12 +396,13 @@ void *silc_schedule_get_context(SilcSchedule schedule);
  *    Add timeout task to scheduler.  The `callback' will be called once
  *    the specified timeout has elapsed.  The task will be removed from the
  *    scheduler automatically once the task expires.  The event returned
- *    to the `callback' is SILC_TASK_EXPIRE.
+ *    to the `callback' is SILC_TASK_EXPIRE.  The task added with zero (0)
+ *    timeout will be executed immediately next time tasks are scheduled.
  *
  ***/
 #define silc_schedule_task_add_timeout(schedule, callback, context, s, u) \
-  silc_schedule_task_add(schedule, 0, callback, context, s, u,           \
-                        SILC_TASK_TIMEOUT)
+  silc_schedule_task_add(schedule, 0, callback, context, s, u,         \
+                         SILC_TASK_TIMEOUT)
 
 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_add_signal
  *
@@ -413,8 +429,8 @@ void *silc_schedule_get_context(SilcSchedule schedule);
  *    the signal call silc_schedule_task_del_by_fd.
  *
  ***/
-#define silc_schedule_task_add_signal(schedule, signal, callback, context) \
-  silc_schedule_task_add(schedule, signal, callback, context, 0, 0,    \
+#define silc_schedule_task_add_signal(schedule, sig, callback, context) \
+  silc_schedule_task_add(schedule, sig, callback, context, 0, 0,       \
                         SILC_TASK_SIGNAL)
 
 /****f* silcutil/SilcScheduleAPI/silc_schedule_task_del
@@ -517,9 +533,10 @@ void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
  *
  * SYNOPSIS
  *
- *    void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
- *                                     SilcTaskEvent mask,
- *                                     SilcBool send_events);
+ *    SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, 
+ *                                         SilcUInt32 fd,
+ *                                         SilcTaskEvent mask,
+ *                                         SilcBool send_events);
  *
  * DESCRIPTION
  *
@@ -537,9 +554,28 @@ void silc_schedule_task_del_by_all(SilcSchedule schedule, int fd,
  *    after the event occurs in reality.  In normal cases the `send_events'
  *    is set to FALSE.
  *
+ *    Returns FALSE if the operation could not performed and TRUE if it
+ *    was a success.
+ *
+ ***/
+SilcBool silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
+                                    SilcTaskEvent mask, SilcBool send_events);
+
+/****f* silcutil/SilcScheduleAPI/silc_schedule_get_fd_events
+ *
+ * SYNOPSIS
+ *
+ *    SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
+ *                                              SilcUInt32 fd);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the file descriptor `fd' current requested events mask,
+ *    or 0 on error.
+ *
  ***/
-void silc_schedule_set_listen_fd(SilcSchedule schedule, SilcUInt32 fd,
-                                SilcTaskEvent mask, SilcBool send_events);
+SilcTaskEvent silc_schedule_get_fd_events(SilcSchedule schedule,
+                                         SilcUInt32 fd);
 
 /****f* silcutil/SilcScheduleAPI/silc_schedule_unset_listen_fd
  *