* check for a valid foldername
[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 #include "modest-defs.h"
35
36 G_BEGIN_DECLS
37
38 /* convenience macros */
39 #define MODEST_TYPE_CONF             (modest_conf_get_type())
40 #define MODEST_CONF(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),MODEST_TYPE_CONF,ModestConf))
41 #define MODEST_CONF_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),MODEST_TYPE_CONF,GObject))
42 #define MODEST_IS_CONF(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),MODEST_TYPE_CONF))
43 #define MODEST_IS_CONF_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),MODEST_TYPE_CONF))
44 #define MODEST_CONF_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj),MODEST_TYPE_CONF,ModestConfClass))
45
46 typedef struct _ModestConf        ModestConf;
47 typedef struct _ModestConfClass   ModestConfClass;
48
49 typedef guint ModestConfNotificationId; 
50
51 typedef enum {
52         MODEST_CONF_VALUE_INT,
53         MODEST_CONF_VALUE_BOOL,
54         MODEST_CONF_VALUE_FLOAT,
55         MODEST_CONF_VALUE_STRING
56 } ModestConfValueType;
57
58 typedef enum {
59         MODEST_CONF_EVENT_KEY_CHANGED,
60         MODEST_CONF_EVENT_KEY_UNSET
61 } ModestConfEvent;
62
63 struct _ModestConf {
64          GObject parent;
65 };
66
67 struct _ModestConfClass {
68         GObjectClass parent_class;      
69         void (* key_changed) (ModestConf* self, 
70                               const gchar *key, 
71                               ModestConfEvent event,
72                               ModestConfNotificationId id);
73 };
74
75 /**
76  * modest_conf_get_type:
77  * 
78  * get the #GType for #ModestConf
79  *  
80  * Returns: the #GType
81  */
82 GType        modest_conf_get_type    (void) G_GNUC_CONST;
83
84
85 /**
86  * modest_conf_new:
87  * 
88  * create a new modest #ModestConf object. 
89  * 
90  * Returns: a new #ModestConf instance, or NULL in case
91  * of any error
92  */
93 ModestConf*     modest_conf_new         (void);
94
95
96 /**
97  * modest_conf_get_string:
98  * @self: a ModestConf instance
99  * @key: the key of the value to retrieve
100  * @err: a GError ptr, or NULL to ignore.
101  * 
102  * get a string from the configuration system
103  *
104  * Returns: a newly allocated string with the value for the key,
105  * or NULL in case of error. @err gives details in case of error
106  */
107 gchar*       modest_conf_get_string  (ModestConf* self, const gchar* key, GError **err);
108
109
110 /** 
111  * modest_conf_get_int:
112  * @self: a ModestConf instance
113  * @key: the key of the value to retrieve
114  * @err: a GError ptr, or NULL to ignore.
115  * 
116  * get an integer from the configuration system
117  *  
118  * Returns: an integer with the value for the key, or -1 in case of error
119  * (of course, -1 can also be returned in non-error cases).
120  * @err gives details in case of error
121  */
122 gint         modest_conf_get_int     (ModestConf* self, const gchar* key, GError **err);
123
124
125 /** 
126  * modest_conf_get_bool:
127  * @self: a ModestConf instance
128  * @key: the key of the value to retrieve
129  * @err: a GError ptr, or NULL to ignore.
130  * 
131  * get a boolean value from the configuration system
132  *  
133  * Returns: a boolean value with the value for the key, or FALSE in case of error
134  * (of course, FALSE can also be returned in non-error cases).
135  * @err gives details in case of error
136  */
137 gboolean     modest_conf_get_bool    (ModestConf* self, const gchar* key, GError **err);
138
139
140 /** 
141  * modest_conf_get_list:
142  * @self: a ModestConf instance
143  * @key: the key of the value to retrieve
144  * @list_type: the type of the elements of the list
145  * @err: a GError ptr, or NULL to ignore.
146  * 
147  * get a list of values from the configuration system
148  *  
149  * Returns: a list with the values for the key, or NULL in case of error
150  * @err gives details in case of error
151  */
152 GSList*     modest_conf_get_list    (ModestConf* self, const gchar* key, 
153                                       ModestConfValueType list_type, GError **err);
154
155 /**
156  * modest_conf_set_string:
157  * @self: a ModestConf instance
158  * @key: the key of the value to set
159  * @val: the value to set
160  * @err: a GError ptr, or NULL if not interested.
161  *
162  * store a string value in the configuration system
163  * 
164  * Returns: TRUE if succeeded or FALSE in case of error.
165  * @err gives details in case of error
166  */
167 gboolean     modest_conf_set_string (ModestConf* self, const gchar* key, const gchar *val,
168                                      GError **err);
169
170 /**
171  * modest_conf_set_int:
172  * @self: a ModestConf instance
173  * @key: the key of the value to set
174  * @val: the value to set
175  * @err: a GError ptr, or NULL if not interested.
176  *
177  * store an integer value in the configuration system
178  * 
179  * Returns: TRUE if succeeded or FALSE in case of error.
180  * @err gives details in case of error
181  */
182 gboolean     modest_conf_set_int    (ModestConf* self, const gchar* key, int val,
183                                      GError **err);
184
185 /**
186  * modest_conf_set_bool:
187  * @self: a ModestConf instance
188  * @key: the key of the value to set
189  * @val: the value to set
190  * @err: a GError ptr, or NULL if not interested.
191  *
192  * store a boolean value in the configuration system
193  * 
194  * Returns: TRUE if succeeded or FALSE in case of error.
195  * @err gives details in case of error
196  */
197 gboolean     modest_conf_set_bool    (ModestConf* self, const gchar* key, gboolean val,
198                                       GError **err);
199
200
201 /** 
202  * modest_conf_set_list:
203  * @self: a ModestConf instance
204  * @key: the key of the value to retrieve
205  * @val: the list with the values to set
206  * @list_type: the type of the elements of the list
207  * @err: a GError ptr, or NULL to ignore.
208  * 
209  * set a list of values in the configuration system
210  *
211  * Returns: TRUE if succeeded or FALSE in case of error.
212  * @err gives details in case of error
213  */
214 gboolean     modest_conf_set_list    (ModestConf* self, const gchar* key, 
215                                       GSList *val, ModestConfValueType list_type, 
216                                       GError **err);
217
218
219 /**
220  * modest_conf_list_subkeys:
221  * @self: a ModestConf instance
222  * @key: the key whose subkeys will be listed
223  * @err: a GError ptr, or NULL if not interested.
224  *
225  * list all the subkeys for a given key
226  * 
227  * Returns: a newly allocated list or NULL in case of error
228  * the returned GSList must be freed by the caller
229  * @err might give details in case of error
230  */
231 GSList*     modest_conf_list_subkeys    (ModestConf* self, const gchar* key,
232                                         GError **err);
233
234
235 /**
236  * modest_conf_remove_key:
237  * @self: a ModestConf instance
238  * @key: the key to remove
239  * @err: a GError ptr, or NULL if not interested.
240  *
241  * attempts to remove @key and all its subkeys
242  * 
243  * Returns: TRUE if succeeded or FALSE in case of error.
244  * @err might give details in case of error
245  */
246 gboolean   modest_conf_remove_key    (ModestConf* self, const gchar* key, GError **err);
247
248
249 /**
250  * modest_conf_key_exists:
251  * @self: a ModestConf instance
252  * @key: the key to remove
253  * @err: a GError ptr, or NULL if not interested.
254  *
255  * checks if the given key exists in the configuration system
256  * 
257  * Returns: TRUE if it exists, FALSE otherwise.
258  * @err gives details in case of error
259  */
260 gboolean   modest_conf_key_exists   (ModestConf* self, const gchar* key, GError **err);
261
262
263
264 /**
265  * modest_conf_key_valid:
266  * @str: some key
267  *
268  * check whether @str is a valid key in the config system
269  * This is a *class* function, and therefore does not require a ModestConf
270  * instance
271  * 
272  * Returns: TRUE if it is valid, FALSE otherwise
273  */
274 gboolean modest_conf_key_is_valid (const gchar* str);
275
276
277 /**
278  * modest_conf_key_escape:
279  * @str: a non-empty string to escape
280  *
281  * returns an escaped version of @str, ie. something suitable as a key
282  * This is a *class* function, and therefore does not require a ModestConf
283  * instance. Note: this for is invidual elements in a key
284  * 
285  * Returns: a newly allocated string with the escaped version
286  */
287 gchar* modest_conf_key_escape (const gchar* str);
288
289
290 /**
291  * modest_conf_key_escape:
292  * @str: a string to escape
293  *
294  * returns an unescaped version of @str. This is a *class* function, and
295  * therefore does not require a ModestConf instance
296  * Note: this for is invidual elements in a key
297  * 
298  * Returns: a newly allocated string with the unescaped version
299  */
300 gchar* modest_conf_key_unescape (const gchar* str);
301
302
303 ModestConfNotificationId modest_conf_listen_to_namespace (ModestConf *self,
304                                                           const gchar *namespace);
305
306 void modest_conf_forget_namespace (ModestConf *self,
307                                    const gchar *namespace,
308                                    ModestConfNotificationId id);
309
310 G_END_DECLS
311
312 #endif /* __MODEST_CONF_H__ */
313