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, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Author: Ryan Lortie <desrt@desrt.ca>
  18  */
  19
  20 #ifndef __dconf_engine_h__
  21 #define __dconf_engine_h__
  22
  23 #include "../common/dconf-changeset.h"
  24 #include "../common/dconf-enums.h"
  25
  26 #include <gio/gio.h>
  27
  28 typedef struct _DConfEngine DConfEngine;
  29
  30 typedef struct _DConfEngineCallHandle DConfEngineCallHandle;
  31
  32 /* These functions need to be implemented by the client library */
  33 G_GNUC_INTERNAL
  34 void                    dconf_engine_dbus_init_for_testing              (void);
  35
  36 /* Sends a D-Bus message.
  37  *
  38  * When the reply comes back, the client library should call
  39  * dconf_engine_handle_dbus_reply with the given user_data.
  40  *
  41  * This is called with the engine lock held.  Re-entering the engine
  42  * from this function will cause a deadlock.
  43  */
  44 G_GNUC_INTERNAL
  45 gboolean                dconf_engine_dbus_call_async_func               (GBusType                 bus_type,
  46                                                                          const gchar             *bus_name,
  47                                                                          const gchar             *object_path,
  48                                                                          const gchar             *interface_name,
  49                                                                          const gchar             *method_name,
  50                                                                          GVariant                *parameters,
  51                                                                          DConfEngineCallHandle   *handle,
  52                                                                          GError                 **error);
  53
  54 /* Sends a D-Bus message, synchronously.
  55  *
  56  * The lock is never held when calling this function (for the sake of
  57  * not blocking requests in other threads) but you should have no reason
  58  * to re-enter, so don't.
  59  */
  60 G_GNUC_INTERNAL
  61 GVariant *              dconf_engine_dbus_call_sync_func                (GBusType                 bus_type,
  62                                                                          const gchar             *bus_name,
  63                                                                          const gchar             *object_path,
  64                                                                          const gchar             *interface_name,
  65                                                                          const gchar             *method_name,
  66                                                                          GVariant                *parameters,
  67                                                                          const GVariantType      *expected_type,
  68                                                                          GError                 **error);
  69
  70 /* Notifies that a change occured.
  71  *
  72  * The engine lock is never held when calling this function so it is
  73  * safe to run user callbacks or emit signals from this function.
  74  */
  75 G_GNUC_INTERNAL
  76 void                    dconf_engine_change_notify                      (DConfEngine             *engine,
  77                                                                          const gchar             *prefix,
  78                                                                          const gchar * const     *changes,
  79                                                                          const gchar             *tag,
  80                                                                          gboolean                 is_writability,
  81                                                                          gpointer                 origin_tag,
  82                                                                          gpointer                 user_data);
  83
  84 /* These functions are implemented by the engine */
  85 G_GNUC_INTERNAL
  86 const GVariantType *    dconf_engine_call_handle_get_expected_type      (DConfEngineCallHandle   *handle);
  87 G_GNUC_INTERNAL
  88 void                    dconf_engine_call_handle_reply                  (DConfEngineCallHandle   *handle,
  89                                                                          GVariant                *parameters,
  90                                                                          const GError            *error);
  91
  92 G_GNUC_INTERNAL
  93 void                    dconf_engine_handle_dbus_signal                 (GBusType                 bus_type,
  94                                                                          const gchar             *bus_name,
  95                                                                          const gchar             *object_path,
  96                                                                          const gchar             *signal_name,
  97                                                                          GVariant                *parameters);
  98
  99 G_GNUC_INTERNAL
 100 DConfEngine *           dconf_engine_new                                (const gchar             *profile,
 101                                                                          gpointer                 user_data,
 102                                                                          GDestroyNotify           free_func);
 103
 104 G_GNUC_INTERNAL
 105 void                    dconf_engine_unref                              (DConfEngine             *engine);
 106
 107 G_GNUC_INTERNAL
 108 void                    dconf_engine_set_watching                       (DConfEngine             *engine,
 109                                                                          const gchar             *path,
 110                                                                          const gboolean           is_watching,
 111                                                                          const gboolean           is_established);
 112
 113 G_GNUC_INTERNAL
 114 gboolean                dconf_engine_is_watching                        (DConfEngine             *engine,
 115                                                                          const gchar             *path,
 116                                                                          const gboolean           only_established);
 117
 118 /* Read API: always handled immediately */
 119 G_GNUC_INTERNAL
 120 guint64                 dconf_engine_get_state                          (DConfEngine             *engine);
 121
 122 G_GNUC_INTERNAL
 123 gboolean                dconf_engine_is_writable                        (DConfEngine             *engine,
 124                                                                          const gchar             *key);
 125
 126 G_GNUC_INTERNAL
 127 gchar **                dconf_engine_list_locks                         (DConfEngine             *engine,
 128                                                                          const gchar             *path,
 129                                                                          gint                    *length);
 130
 131 G_GNUC_INTERNAL
 132 GVariant *              dconf_engine_read                               (DConfEngine             *engine,
 133                                                                          DConfReadFlags           flags,
 134                                                                          const GQueue            *read_through,
 135                                                                          const gchar             *key);
 136
 137 G_GNUC_INTERNAL
 138 gchar **                dconf_engine_list                               (DConfEngine             *engine,
 139                                                                          const gchar             *dir,
 140                                                                          gint                    *length);
 141
 142 /* "Fast" API: all calls return immediately and look like they succeeded (from a local viewpoint) */
 143 G_GNUC_INTERNAL
 144 void                    dconf_engine_watch_fast                         (DConfEngine             *engine,
 145                                                                          const gchar             *path);
 146
 147 G_GNUC_INTERNAL
 148 void                    dconf_engine_unwatch_fast                       (DConfEngine             *engine,
 149                                                                          const gchar             *path);
 150
 151 G_GNUC_INTERNAL
 152 gboolean                dconf_engine_change_fast                        (DConfEngine             *engine,
 153                                                                          DConfChangeset          *changeset,
 154                                                                          gpointer                 origin_tag,
 155                                                                          GError                 **error);
 156
 157 /* Synchronous API: all calls block until completed */
 158 G_GNUC_INTERNAL
 159 void                    dconf_engine_watch_sync                         (DConfEngine             *engine,
 160                                                                          const gchar             *path);
 161
 162 G_GNUC_INTERNAL
 163 void                    dconf_engine_unwatch_sync                       (DConfEngine             *engine,
 164                                                                          const gchar             *path);
 165
 166 G_GNUC_INTERNAL
 167 gboolean                dconf_engine_change_sync                        (DConfEngine             *engine,
 168                                                                          DConfChangeset          *changeset,
 169                                                                          gchar                  **tag,
 170                                                                          GError                 **error);
 171 G_GNUC_INTERNAL
 172 gboolean                dconf_engine_has_outstanding                    (DConfEngine             *engine);
 173 G_GNUC_INTERNAL
 174 void                    dconf_engine_sync                               (DConfEngine             *engine);
 175
 176 /* Asynchronous API: not implemented yet (and maybe never?) */
 177
 178 #endif /* __dconf_engine_h__ */