* Fixes NB#91689. fixes a wrong check for ASCII
[modest] / src / modest-conf.h
1 /* Copyright (c) 2006, Nokia Corporation
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  * * Redistributions of source code must retain the above copyright
9  *   notice, this list of conditions and the following disclaimer.
10  * * Redistributions in binary form must reproduce the above copyright
11  *   notice, this list of conditions and the following disclaimer in the
12  *   documentation and/or other materials provided with the distribution.
13  * * Neither the name of the Nokia Corporation nor the names of its
14  *   contributors may be used to endorse or promote products derived from
15  *   this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
18  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
20  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
21  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
24  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
25  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
26  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30 #ifndef __MODEST_CONF_H__
31 #define __MODEST_CONF_H__
32
33 #include <glib-object.h>
34
35 G_BEGIN_DECLS
36
37 /* convenience macros */
38 #define MODEST_TYPE_CONF             (modest_conf_get_type())
39 #define MODEST_CONF(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),MODEST_TYPE_CONF,ModestConf))
40 #define MODEST_CONF_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),MODEST_TYPE_CONF,GObject))
41 #define MODEST_IS_CONF(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),MODEST_TYPE_CONF))
42 #define MODEST_IS_CONF_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),MODEST_TYPE_CONF))
43 #define MODEST_CONF_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj),MODEST_TYPE_CONF,ModestConfClass))
44
45 typedef struct _ModestConf        ModestConf;
46 typedef struct _ModestConfClass   ModestConfClass;
47
48 typedef guint ModestConfNotificationId; 
49
50 typedef enum {
51         MODEST_CONF_VALUE_INT,
52         MODEST_CONF_VALUE_BOOL,
53         MODEST_CONF_VALUE_FLOAT,
54         MODEST_CONF_VALUE_STRING
55 } ModestConfValueType;
56
57 typedef enum {
58         MODEST_CONF_EVENT_KEY_CHANGED,
59         MODEST_CONF_EVENT_KEY_UNSET
60 } ModestConfEvent;
61
62 struct _ModestConf {
63          GObject parent;
64 };
65
66 struct _ModestConfClass {
67         GObjectClass parent_class;      
68         void (* key_changed) (ModestConf* self, 
69                               const gchar *key, 
70                               ModestConfEvent event,
71                               ModestConfNotificationId id);
72 };
73
74 /**
75  * modest_conf_get_type:
76  * 
77  * get the #GType for #ModestConf
78  *  
79  * Returns: the #GType
80  */
81 GType        modest_conf_get_type    (void) G_GNUC_CONST;
82
83
84 /**
85  * modest_conf_new:
86  * 
87  * create a new modest #ModestConf object. 
88  * 
89  * Returns: a new #ModestConf instance, or NULL in case
90  * of any error
91  */
92 ModestConf*     modest_conf_new         (void);
93
94
95 /**
96  * modest_conf_get_string:
97  * @self: a ModestConf instance
98  * @key: the key of the value to retrieve
99  * @err: a GError ptr, or NULL to ignore.
100  * 
101  * get a string from the configuration system
102  *
103  * Returns: a newly allocated string with the value for the key,
104  * or NULL in case of error. @err gives details in case of error
105  */
106 gchar*       modest_conf_get_string  (ModestConf* self, const gchar* key, GError **err);
107
108
109 /** 
110  * modest_conf_get_int:
111  * @self: a ModestConf instance
112  * @key: the key of the value to retrieve
113  * @err: a GError ptr, or NULL to ignore.
114  * 
115  * get an integer from the configuration system
116  *  
117  * Returns: an integer with the value for the key, or -1 in case of error
118  * (of course, -1 can also be returned in non-error cases).
119  * @err gives details in case of error
120  */
121 gint         modest_conf_get_int     (ModestConf* self, const gchar* key, GError **err);
122
123 /** 
124  * modest_conf_get_float:
125  * @self: a ModestConf instance
126  * @key: the key of the value to retrieve
127  * @err: a GError ptr, or NULL to ignore.
128  * 
129  * get an integer from the configuration system
130  *  
131  * Returns: an double with the value for the key, or -1 in case of
132  * error (of course, -1 can also be returned in non-error cases).
133  * @err gives details in case of error
134  */
135 gdouble      modest_conf_get_float   (ModestConf* self, const gchar* key, GError **err);
136
137 /** 
138  * modest_conf_get_bool:
139  * @self: a ModestConf instance
140  * @key: the key of the value to retrieve
141  * @err: a GError ptr, or NULL to ignore.
142  * 
143  * get a boolean value from the configuration system
144  *  
145  * Returns: a boolean value with the value for the key, or FALSE in case of error
146  * (of course, FALSE can also be returned in non-error cases).
147  * @err gives details in case of error
148  */
149 gboolean     modest_conf_get_bool    (ModestConf* self, const gchar* key, GError **err);
150
151
152 /** 
153  * modest_conf_get_list:
154  * @self: a ModestConf instance
155  * @key: the key of the value to retrieve
156  * @list_type: the type of the elements of the list
157  * @err: a GError ptr, or NULL to ignore.
158  * 
159  * get a list of values from the configuration system
160  *  
161  * Returns: a list with the values for the key, or NULL in case of error
162  * @err gives details in case of error
163  */
164 GSList*     modest_conf_get_list    (ModestConf* self, const gchar* key, 
165                                       ModestConfValueType list_type, GError **err);
166
167 /**
168  * modest_conf_set_string:
169  * @self: a ModestConf instance
170  * @key: the key of the value to set
171  * @val: the value to set
172  * @err: a GError ptr, or NULL if not interested.
173  *
174  * store a string value in the configuration system
175  * 
176  * Returns: TRUE if succeeded or FALSE in case of error.
177  * @err gives details in case of error
178  */
179 gboolean     modest_conf_set_string (ModestConf* self, const gchar* key, const gchar *val,
180                                      GError **err);
181
182 /**
183  * modest_conf_set_int:
184  * @self: a ModestConf instance
185  * @key: the key of the value to set
186  * @val: the value to set
187  * @err: a GError ptr, or NULL if not interested.
188  *
189  * store an integer value in the configuration system
190  * 
191  * Returns: TRUE if succeeded or FALSE in case of error.
192  * @err gives details in case of error
193  */
194 gboolean     modest_conf_set_int    (ModestConf* self, const gchar* key, int val,
195                                      GError **err);
196
197 /**
198  * modest_conf_set_float:
199  * @self: a ModestConf instance
200  * @key: the key of the value to set
201  * @val: the value to set
202  * @err: a GError ptr, or NULL if not interested.
203  *
204  * store an integer value in the configuration system
205  * 
206  * Returns: TRUE if succeeded or FALSE in case of error.
207  * @err gives details in case of error
208  */
209 gboolean     modest_conf_set_float  (ModestConf* self, 
210                                      const gchar* key, 
211                                      gdouble val,
212                                      GError **err);
213
214 /**
215  * modest_conf_set_bool:
216  * @self: a ModestConf instance
217  * @key: the key of the value to set
218  * @val: the value to set
219  * @err: a GError ptr, or NULL if not interested.
220  *
221  * store a boolean value in the configuration system
222  * 
223  * Returns: TRUE if succeeded or FALSE in case of error.
224  * @err gives details in case of error
225  */
226 gboolean     modest_conf_set_bool    (ModestConf* self, const gchar* key, gboolean val,
227                                       GError **err);
228
229
230 /** 
231  * modest_conf_set_list:
232  * @self: a ModestConf instance
233  * @key: the key of the value to retrieve
234  * @val: the list with the values to set
235  * @list_type: the type of the elements of the list
236  * @err: a GError ptr, or NULL to ignore.
237  * 
238  * set a list of values in the configuration system
239  *
240  * Returns: TRUE if succeeded or FALSE in case of error.
241  * @err gives details in case of error
242  */
243 gboolean     modest_conf_set_list    (ModestConf* self, const gchar* key, 
244                                       GSList *val, ModestConfValueType list_type, 
245                                       GError **err);
246
247
248 /**
249  * modest_conf_list_subkeys:
250  * @self: a ModestConf instance
251  * @key: the key whose subkeys will be listed
252  * @err: a GError ptr, or NULL if not interested.
253  *
254  * list all the subkeys for a given key
255  * 
256  * Returns: a newly allocated list or NULL in case of error
257  * the returned GSList must be freed by the caller
258  * @err might give details in case of error
259  */
260 GSList*     modest_conf_list_subkeys    (ModestConf* self, const gchar* key,
261                                         GError **err);
262
263
264 /**
265  * modest_conf_remove_key:
266  * @self: a ModestConf instance
267  * @key: the key to remove
268  * @err: a GError ptr, or NULL if not interested.
269  *
270  * attempts to remove @key and all its subkeys
271  * 
272  * Returns: TRUE if succeeded or FALSE in case of error.
273  * @err might give details in case of error
274  */
275 gboolean   modest_conf_remove_key    (ModestConf* self, const gchar* key, GError **err);
276
277
278 /**
279  * modest_conf_key_exists:
280  * @self: a ModestConf instance
281  * @key: the key to remove
282  * @err: a GError ptr, or NULL if not interested.
283  *
284  * checks if the given key exists in the configuration system
285  * 
286  * Returns: TRUE if it exists, FALSE otherwise.
287  * @err gives details in case of error
288  */
289 gboolean   modest_conf_key_exists   (ModestConf* self, const gchar* key, GError **err);
290
291
292
293 /**
294  * modest_conf_key_valid:
295  * @str: some key
296  *
297  * check whether @str is a valid key in the config system
298  * This is a *class* function, and therefore does not require a ModestConf
299  * instance
300  * 
301  * Returns: TRUE if it is valid, FALSE otherwise
302  */
303 gboolean modest_conf_key_is_valid (const gchar* str);
304
305
306 /**
307  * modest_conf_key_escape:
308  * @str: a non-empty string to escape
309  *
310  * returns an escaped version of @str, ie. something suitable as a key
311  * This is a *class* function, and therefore does not require a ModestConf
312  * instance. Note: this for is invidual elements in a key
313  * 
314  * Returns: a newly allocated string with the escaped version
315  */
316 gchar* modest_conf_key_escape (const gchar* str);
317
318
319 /**
320  * modest_conf_key_escape:
321  * @str: a string to escape
322  *
323  * returns an unescaped version of @str. This is a *class* function, and
324  * therefore does not require a ModestConf instance
325  * Note: this for is invidual elements in a key
326  * 
327  * Returns: a newly allocated string with the unescaped version
328  */
329 gchar* modest_conf_key_unescape (const gchar* str);
330
331
332 void modest_conf_listen_to_namespace (ModestConf *self,
333                                       const gchar *namespace);
334
335 void modest_conf_forget_namespace    (ModestConf *self,
336                                       const gchar *namespace);
337 G_END_DECLS
338
339 #endif /* __MODEST_CONF_H__ */
340