engine/dconf-engine.h

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #ifndef __dconf_engine_h__
  23 #define __dconf_engine_h__
  24
  25 #include "../common/dconf-changeset.h"
  26
  27 #include <gio/gio.h>
  28
  29 typedef struct _DConfEngine DConfEngine;
  30
  31 typedef struct _DConfEngineCallHandle DConfEngineCallHandle;
  32
  33 typedef enum
  34 {
  35   DCONF_ERROR_FAILED,
  36   DCONF_ERROR_NOT_WRITABLE
  37 } DConfEngineError;
  38
  39 #define DCONF_ERROR (g_quark_from_static_string ("dconf error quark"))
  40
  41 /* These functions need to be implemented by the client library */
  42 G_GNUC_INTERNAL
  43 void                    dconf_engine_dbus_init_for_testing              (void);
  44
  45 /* Sends a D-Bus message.
  46  *
  47  * When the reply comes back, the client library should call
  48  * dconf_engine_handle_dbus_reply with the given user_data.
  49  *
  50  * This is called with the engine lock held.  Re-entering the engine
  51  * from this function will cause a deadlock.
  52  */
  53 G_GNUC_INTERNAL
  54 gboolean                dconf_engine_dbus_call_async_func               (GBusType                 bus_type,
  55                                                                          const gchar             *bus_name,
  56                                                                          const gchar             *object_path,
  57                                                                          const gchar             *interface_name,
  58                                                                          const gchar             *method_name,
  59                                                                          GVariant                *parameters,
  60                                                                          DConfEngineCallHandle   *handle,
  61                                                                          GError                 **error);
  62
  63 /* Sends a D-Bus message, synchronously.
  64  *
  65  * The lock is never held when calling this function (for the sake of
  66  * not blocking requests in other threads) but you should have no reason
  67  * to re-enter, so don't.
  68  */
  69 G_GNUC_INTERNAL
  70 GVariant *              dconf_engine_dbus_call_sync_func                (GBusType                 bus_type,
  71                                                                          const gchar             *bus_name,
  72                                                                          const gchar             *object_path,
  73                                                                          const gchar             *interface_name,
  74                                                                          const gchar             *method_name,
  75                                                                          GVariant                *parameters,
  76                                                                          const GVariantType      *expected_type,
  77                                                                          GError                 **error);
  78
  79 /* Notifies that a change occured.
  80  *
  81  * The engine lock is never held when calling this function so it is
  82  * safe to run user callbacks or emit signals from this function.
  83  */
  84 G_GNUC_INTERNAL
  85 void                    dconf_engine_change_notify                      (DConfEngine             *engine,
  86                                                                          const gchar             *prefix,
  87                                                                          const gchar * const     *changes,
  88                                                                          const gchar             *tag,
  89                                                                          gpointer                 origin_tag,
  90                                                                          gpointer                 user_data);
  91
  92 /* These functions are implemented by the engine */
  93 G_GNUC_INTERNAL
  94 const GVariantType *    dconf_engine_call_handle_get_expected_type      (DConfEngineCallHandle   *handle);
  95 G_GNUC_INTERNAL
  96 void                    dconf_engine_call_handle_reply                  (DConfEngineCallHandle   *handle,
  97                                                                          GVariant                *parameters,
  98                                                                          const GError            *error);
  99
 100 G_GNUC_INTERNAL
 101 void                    dconf_engine_handle_dbus_signal                 (GBusType                 bus_type,
 102                                                                          const gchar             *bus_name,
 103                                                                          const gchar             *object_path,
 104                                                                          const gchar             *signal_name,
 105                                                                          GVariant                *parameters);
 106
 107 G_GNUC_INTERNAL
 108 DConfEngine *           dconf_engine_new                                (gpointer                 user_data,
 109                                                                          GDestroyNotify           free_func);
 110
 111 G_GNUC_INTERNAL
 112 void                    dconf_engine_unref                              (DConfEngine             *engine);
 113
 114 /* Read API: always handled immediately */
 115 G_GNUC_INTERNAL
 116 guint64                 dconf_engine_get_state                          (DConfEngine             *engine);
 117
 118 G_GNUC_INTERNAL
 119 gboolean                dconf_engine_is_writable                        (DConfEngine             *engine,
 120                                                                          const gchar             *key);
 121
 122 G_GNUC_INTERNAL
 123 GVariant *              dconf_engine_read                               (DConfEngine             *engine,
 124                                                                          GQueue                  *read_through,
 125                                                                          const gchar             *key);
 126
 127 G_GNUC_INTERNAL
 128 gchar **                dconf_engine_list                               (DConfEngine             *engine,
 129                                                                          const gchar             *dir,
 130                                                                          gint                    *length);
 131
 132 /* "Fast" API: all calls return immediately and look like they succeeded (from a local viewpoint) */
 133 G_GNUC_INTERNAL
 134 void                    dconf_engine_watch_fast                         (DConfEngine             *engine,
 135                                                                          const gchar             *path);
 136
 137 G_GNUC_INTERNAL
 138 void                    dconf_engine_unwatch_fast                       (DConfEngine             *engine,
 139                                                                          const gchar             *path);
 140
 141 G_GNUC_INTERNAL
 142 gboolean                dconf_engine_change_fast                        (DConfEngine             *engine,
 143                                                                          DConfChangeset          *changeset,
 144                                                                          gpointer                 origin_tag,
 145                                                                          GError                 **error);
 146
 147 /* Synchronous API: all calls block until completed */
 148 G_GNUC_INTERNAL
 149 void                    dconf_engine_watch_sync                         (DConfEngine             *engine,
 150                                                                          const gchar             *path);
 151
 152 G_GNUC_INTERNAL
 153 void                    dconf_engine_unwatch_sync                       (DConfEngine             *engine,
 154                                                                          const gchar             *path);
 155
 156 G_GNUC_INTERNAL
 157 gboolean                dconf_engine_change_sync                        (DConfEngine             *engine,
 158                                                                          DConfChangeset          *changeset,
 159                                                                          gchar                  **tag,
 160                                                                          GError                 **error);
 161 G_GNUC_INTERNAL
 162 gboolean                dconf_engine_has_outstanding                    (DConfEngine             *engine);
 163 G_GNUC_INTERNAL
 164 void                    dconf_engine_sync                               (DConfEngine             *engine);
 165
 166 /* Asynchronous API: not implemented yet (and maybe never?) */
 167
 168 #endif /* __dconf_engine_h__ */