gmain.h

00001 /* gmain.h - the GLib Main loop
00002  * Copyright (C) 1998-2000 Red Hat, Inc.
00003  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Library General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Library General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Library General Public
00016  * License along with this library; if not, write to the
00017  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018  * Boston, MA 02111-1307, USA.
00019  */
00020 
00021 #ifndef __G_MAIN_H__
00022 #define __G_MAIN_H__
00023 
00024 #include <_ansi.h>
00025 #include <glib/gslist.h>
00026 #include <glib/gthread.h>
00027 
00028 G_BEGIN_DECLS
00029 
00030 typedef struct _GMainContext            GMainContext;   /* Opaque */
00031 typedef struct _GMainLoop               GMainLoop;      /* Opaque */
00032 typedef struct _GSource                 GSource;
00033 typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
00034 typedef struct _GSourceFuncs            GSourceFuncs;
00035 
00036 typedef gboolean (*GSourceFunc)       (gpointer data);
00037 typedef void     (*GChildWatchFunc)   (GPid     pid,
00038                                        gint     status,
00039                                        gpointer data);
00040 struct _GSource
00041 {
00042   /*< private >*/
00043   gpointer callback_data;
00044   GSourceCallbackFuncs *callback_funcs;
00045 
00046   GSourceFuncs *source_funcs;
00047   guint ref_count;
00048 
00049   GMainContext *context;
00050 
00051   gint priority;
00052   guint flags;
00053   guint source_id;
00054 
00055   GSList *poll_fds;
00056   
00057   GSource *prev;
00058   GSource *next;
00059 
00060   gpointer reserved1;
00061   gpointer reserved2;
00062 };
00063 
00064 struct _GSourceCallbackFuncs
00065 {
00066   void (*ref)   (gpointer     cb_data);
00067   void (*unref) (gpointer     cb_data);
00068   void (*get)   (gpointer     cb_data,
00069                  GSource     *source, 
00070                  GSourceFunc *func,
00071                  gpointer    *data);
00072 };
00073 
00074 typedef void (*GSourceDummyMarshal) (void);
00075 
00076 struct _GSourceFuncs
00077 {
00078   gboolean (*prepare)  (GSource    *source,
00079                         gint       *timeout_);
00080   gboolean (*check)    (GSource    *source);
00081   gboolean (*dispatch) (GSource    *source,
00082                         GSourceFunc callback,
00083                         gpointer    user_data);
00084   void     (*finalize) (GSource    *source); /* Can be NULL */
00085 
00086   /* For use by g_source_set_closure */
00087   GSourceFunc     closure_callback;        
00088   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
00089 };
00090 
00091 /* Any definitions using GPollFD or GPollFunc are primarily
00092  * for Unix and not guaranteed to be the compatible on all
00093  * operating systems on which GLib runs. Right now, the
00094  * GLib does use these functions on Win32 as well, but interprets
00095  * them in a fairly different way than on Unix. If you use
00096  * these definitions, you are should be prepared to recode
00097  * for different operating systems.
00098  *
00099  *
00100  * On Win32, the fd in a GPollFD should be Win32 HANDLE (*not* a file
00101  * descriptor as provided by the C runtime) that can be used by
00102  * MsgWaitForMultipleObjects. This does *not* include file handles
00103  * from CreateFile, SOCKETs, nor pipe handles. (But you can use
00104  * WSAEventSelect to signal events when a SOCKET is readable).
00105  *
00106  * On Win32, fd can also be the special value G_WIN32_MSG_HANDLE to
00107  * indicate polling for messages.
00108  *
00109  * But note that G_WIN32_MSG_HANDLE GPollFDs should not be used by GDK
00110  * (GTK) programs, as GDK itself wants to read messages and convert them
00111  * to GDK events.
00112  *
00113  * So, unless you really know what you are doing, it's best not to try
00114  * to use the main loop polling stuff for your own needs on
00115  * Win32. It's really only written for the GIMP's needs so
00116  * far.
00117  */
00118 typedef struct _GPollFD GPollFD;
00119 typedef gint    (*GPollFunc)    (GPollFD *ufds,
00120                                  guint    nfsd,
00121                                  gint     timeout_);
00122 
00123 struct _GPollFD
00124 {
00125   gint          fd;
00126   gushort       events;
00127   gushort       revents;
00128 };
00129 
00130 /* Standard priorities */
00131 
00132 #define G_PRIORITY_HIGH            -100
00133 #define G_PRIORITY_DEFAULT          0
00134 #define G_PRIORITY_HIGH_IDLE        100
00135 #define G_PRIORITY_DEFAULT_IDLE     200
00136 #define G_PRIORITY_LOW              300
00137 
00138 /* GMainContext: */
00139 
00140 IMPORT_C GMainContext *g_main_context_new       (void);
00141 IMPORT_C GMainContext *g_main_context_ref       (GMainContext *context);
00142 IMPORT_C void          g_main_context_unref     (GMainContext *context);
00143 IMPORT_C GMainContext *g_main_context_default   (void);
00144 
00145 IMPORT_C gboolean      g_main_context_iteration (GMainContext *context,
00146                                         gboolean      may_block);
00147 IMPORT_C gboolean      g_main_context_pending   (GMainContext *context);
00148 
00149 /* For implementation of legacy interfaces
00150  */
00151 IMPORT_C GSource      *g_main_context_find_source_by_id              (GMainContext *context,
00152                                                              guint         source_id);
00153 IMPORT_C GSource      *g_main_context_find_source_by_user_data       (GMainContext *context,
00154                                                              gpointer      user_data);
00155 IMPORT_C GSource      *g_main_context_find_source_by_funcs_user_data (GMainContext *context,
00156                                                              GSourceFuncs *funcs,
00157                                                              gpointer      user_data);
00158 
00159 /* Low level functions for implementing custom main loops.
00160  */
00161 IMPORT_C void     g_main_context_wakeup  (GMainContext *context);
00162 IMPORT_C gboolean g_main_context_acquire (GMainContext *context);
00163 IMPORT_C void     g_main_context_release (GMainContext *context);
00164 IMPORT_C gboolean g_main_context_is_owner (GMainContext *context);
00165 IMPORT_C gboolean g_main_context_wait    (GMainContext *context,
00166                                  GCond        *cond,
00167                                  GMutex       *mutex);
00168 
00169 IMPORT_C gboolean g_main_context_prepare  (GMainContext *context,
00170                                   gint         *priority);
00171 IMPORT_C gint     g_main_context_query    (GMainContext *context,
00172                                   gint          max_priority,
00173                                   gint         *timeout_,
00174                                   GPollFD      *fds,
00175                                   gint          n_fds);
00176 IMPORT_C gint     g_main_context_check    (GMainContext *context,
00177                                   gint          max_priority,
00178                                   GPollFD      *fds,
00179                                   gint          n_fds);
00180 IMPORT_C void     g_main_context_dispatch (GMainContext *context);
00181 
00182 IMPORT_C void      g_main_context_set_poll_func (GMainContext *context,
00183                                         GPollFunc     func);
00184 IMPORT_C GPollFunc g_main_context_get_poll_func (GMainContext *context);
00185 
00186 /* Low level functions for use by source implementations
00187  */
00188 IMPORT_C void g_main_context_add_poll      (GMainContext *context,
00189                                    GPollFD      *fd,
00190                                    gint          priority);
00191 IMPORT_C void g_main_context_remove_poll   (GMainContext *context,
00192                                    GPollFD      *fd);
00193 
00194 IMPORT_C int g_main_depth (void);
00195 
00196 /* GMainLoop: */
00197 
00198 IMPORT_C GMainLoop *g_main_loop_new        (GMainContext *context,
00199                                    gboolean      is_running);
00200 IMPORT_C void       g_main_loop_run        (GMainLoop    *loop);
00201 IMPORT_C void       g_main_loop_quit       (GMainLoop    *loop);
00202 IMPORT_C GMainLoop *g_main_loop_ref        (GMainLoop    *loop);
00203 IMPORT_C void       g_main_loop_unref      (GMainLoop    *loop);
00204 IMPORT_C gboolean   g_main_loop_is_running (GMainLoop    *loop);
00205 IMPORT_C GMainContext *g_main_loop_get_context (GMainLoop    *loop);
00206 
00207 /* GSource: */
00208 
00209 IMPORT_C GSource *g_source_new             (GSourceFuncs   *source_funcs,
00210                                    guint           struct_size);
00211 IMPORT_C GSource *g_source_ref             (GSource        *source);
00212 IMPORT_C void     g_source_unref           (GSource        *source);
00213 
00214 IMPORT_C guint    g_source_attach          (GSource        *source,
00215                                    GMainContext   *context);
00216 IMPORT_C void     g_source_destroy         (GSource        *source);
00217 
00218 IMPORT_C void     g_source_set_priority    (GSource        *source,
00219                                    gint            priority);
00220 IMPORT_C gint     g_source_get_priority    (GSource        *source);
00221 IMPORT_C void     g_source_set_can_recurse (GSource        *source,
00222                                    gboolean        can_recurse);
00223 IMPORT_C gboolean g_source_get_can_recurse (GSource        *source);
00224 IMPORT_C guint    g_source_get_id          (GSource        *source);
00225 
00226 IMPORT_C GMainContext *g_source_get_context (GSource       *source);
00227 
00228 IMPORT_C void g_source_set_callback          (GSource              *source,
00229                                      GSourceFunc           func,
00230                                      gpointer              data,
00231                                      GDestroyNotify        notify);
00232 
00233 
00234 /* Used to implement g_source_connect_closure and internally*/
00235 IMPORT_C void g_source_set_callback_indirect (GSource              *source,
00236                                      gpointer              callback_data,
00237                                      GSourceCallbackFuncs *callback_funcs);
00238 
00239 IMPORT_C void     g_source_add_poll         (GSource        *source,
00240                                     GPollFD        *fd);
00241 IMPORT_C void     g_source_remove_poll      (GSource        *source,
00242                                     GPollFD        *fd);
00243 
00244 IMPORT_C void     g_source_get_current_time (GSource        *source,
00245                                     GTimeVal       *timeval);
00246 
00247  /* void g_source_connect_closure (GSource        *source,
00248                                   GClosure       *closure);
00249  */
00250 
00251 /* Specific source types
00252  */
00253 IMPORT_C GSource *g_idle_source_new        (void);
00254 IMPORT_C GSource *g_child_watch_source_new (GPid pid);
00255 IMPORT_C GSource *g_timeout_source_new     (guint interval);
00256 
00257 /* Miscellaneous functions
00258  */
00259 IMPORT_C void g_get_current_time                        (GTimeVal       *result);
00260 
00261 /* ============== Compat main loop stuff ================== */
00262 
00263 #ifndef G_DISABLE_DEPRECATED
00264 
00265 /* Legacy names for GMainLoop functions
00266  */
00267 #define         g_main_new(is_running)  g_main_loop_new (NULL, is_running);
00268 #define         g_main_run(loop)        g_main_loop_run(loop)
00269 #define         g_main_quit(loop)       g_main_loop_quit(loop)
00270 #define         g_main_destroy(loop)    g_main_loop_unref(loop)
00271 #define         g_main_is_running(loop) g_main_loop_is_running(loop)
00272 
00273 /* Functions to manipulate the default main loop
00274  */
00275 
00276 #define g_main_iteration(may_block) g_main_context_iteration      (NULL, may_block)
00277 #define g_main_pending()            g_main_context_pending        (NULL)
00278 
00279 #define g_main_set_poll_func(func)   g_main_context_set_poll_func (NULL, func)
00280 
00281 #endif /* G_DISABLE_DEPRECATED */
00282 
00283 /* Source manipulation by ID */
00284 IMPORT_C gboolean g_source_remove                     (guint          tag);
00285 IMPORT_C gboolean g_source_remove_by_user_data        (gpointer       user_data);
00286 IMPORT_C gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
00287                                               gpointer       user_data);
00288 
00289 /* Idles, child watchers and timeouts */
00290 IMPORT_C guint    g_timeout_add_full     (gint            priority,
00291                                  guint           interval,
00292                                  GSourceFunc     function,
00293                                  gpointer        data,
00294                                  GDestroyNotify  notify);
00295 IMPORT_C guint    g_timeout_add          (guint           interval,
00296                                  GSourceFunc     function,
00297                                  gpointer        data);
00298 IMPORT_C guint    g_child_watch_add_full (gint            priority,
00299                                  GPid            pid,
00300                                  GChildWatchFunc function,
00301                                  gpointer        data,
00302                                  GDestroyNotify  notify);
00303 IMPORT_C guint    g_child_watch_add      (GPid            pid,
00304                                  GChildWatchFunc function,
00305                                  gpointer        data);
00306 IMPORT_C guint    g_idle_add             (GSourceFunc     function,
00307                                  gpointer        data);
00308 IMPORT_C guint    g_idle_add_full        (gint            priority,
00309                                  GSourceFunc     function,
00310                                  gpointer        data,
00311                                  GDestroyNotify  notify);
00312 IMPORT_C gboolean g_idle_remove_by_data  (gpointer        data);
00313 
00314 /* Hook for GClosure / GSource integration. Don't touch */
00315 #ifdef SYMBIAN
00316 IMPORT_C GSourceFuncs * _g_timeout_funcs();
00317 #endif /*SYMBIAN */
00318 GLIB_VAR GSourceFuncs g_timeout_funcs;
00319 #ifdef SYMBIAN
00320 IMPORT_C GSourceFuncs * _g_child_watch_funcs();
00321 #endif /* SYMBIAN */
00322 GLIB_VAR GSourceFuncs g_child_watch_funcs;
00323 #ifdef SYMBIAN
00324 IMPORT_C GSourceFuncs * _g_idle_funcs();
00325 #endif/* SYMBIAN */
00326 GLIB_VAR GSourceFuncs g_idle_funcs;
00327 
00328 G_END_DECLS
00329 
00330 #endif /* __G_MAIN_H__ */