d71b67d7a3758b65edf31cf5a00996961b04a4fe
[modest] / src / maemo / easysetup / modest-presets.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_PRESETS_H__
31 #define __MODEST_PRESETS_H__
32
33 #include <glib.h>
34
35 struct _ModestPresets {
36 /* private data: don't touch */
37         GKeyFile *keyfile;
38 };
39 typedef struct _ModestPresets ModestPresets;
40
41 typedef enum _ModestPresetsServerType {
42         MODEST_PRESETS_SERVER_TYPE_NONE,                      
43         MODEST_PRESETS_SERVER_TYPE_IMAP,
44         MODEST_PRESETS_SERVER_TYPE_POP,
45         MODEST_PRESETS_SERVER_TYPE_SMTP
46 } ModestPresetsServerType;
47
48 /** These are flags, which should be ORed.
49  */
50 typedef enum _ModestPresetsSecurity {
51         MODEST_PRESETS_SECURITY_NONE                           = 0,                           
52         MODEST_PRESETS_SECURITY_APOP                           = 1 << 0,
53         MODEST_PRESETS_SECURITY_SECURE_SMTP                    = 1 << 1, /* if set, port will be 465
54                                                                           * instead of 25 */
55         MODEST_PRESETS_SECURITY_SECURE_INCOMING                = 1 << 2,
56         MODEST_PRESETS_SECURITY_SECURE_INCOMING_ALTERNATE_PORT = 1 << 3, /* POP3S=>995, IMAPS=>993 */
57 } ModestPresetsSecurity;
58
59 /* typedef enum _ModestPresetsInfo ModestPresetsInfo; */
60
61
62 /**
63  * modest_presets_new:
64  * @presetfile: the full path to the file with presets (in GKeyFile format)
65  * 
66  * make a new ModestPresets instance
67  *
68  * Returns: a new ModestPresets instance, or NULL in case of error.
69  */
70 ModestPresets*            modest_presets_new             (const gchar *presetfile);
71
72
73 /**
74  * modest_presets_get_providers:
75  * @self: a valid ModestPresets instance
76  * @mcc: limit the search to providers with this mcc (Mobile Country Code),
77  *       or 0  to get all
78  * @include_globals: include (global) providers without MCC (such as GMail, Yahoo)
79  * @provider_ids: Output parameter, which will be set to a newly allocated array of strings, or NULL in case of error.
80  * 
81  * get a list of providers matching certian criteria
82  *
83  * Returns: The provider names, as a newly allocated array of strings, or NULL in case of error
84  * should be freed with g_strfreev
85  * 
86  **/
87 gchar **         modest_presets_get_providers   (ModestPresets *self, guint mcc, 
88                                                  gboolean include_globals, gchar ***provider_ids);
89
90 /**
91  * modest_presets_get_server:
92  * @self: a valid ModestPresets instance
93  * @provider_id: ID of the provider 
94  * @incoming_server: get the incoming mailserver if TRUE, get the
95  * outgoing server otherwise
96  *
97  * get the name of a incoming or outgoing mailserver
98  * 
99  * Returns: a newly allocated string with the servername, or NULL in case
100  * of error, or server not found. (FIXME). Note that if the (incoming) server uses a
101  * non-standard port, the port number is appended to the name, eg. pop.foo.fi:995
102  */
103 gchar *                   modest_presets_get_server      (ModestPresets *self,
104                                                           const gchar *provider_id,
105                                                           gboolean incoming_server);
106                                                           
107 /**
108  * modest_presets_get_domain:
109  * @self: a valid ModestPresets instance
110  * @provider_id: ID of the provider 
111  *
112  * Get the name of the most-used domain for theis provider. For instance. hotmail.com
113  * 
114  * Returns: a newly allocated string with the domain name, or NULL in case
115  * of error.
116  */
117 gchar *                   modest_presets_get_domain      (ModestPresets *self,
118                                                           const gchar *provider_id);
119
120 /**
121  * modest_presets_get_info_server_type:
122  * @self: a valid ModestPresets instance
123  * @provider_id: ID of the provider 
124  * @incoming_server: get the incoming mailserver if TRUE, get the
125  * outgoing server otherwise
126  *
127  * get information about some incoming or outgoing mailserver
128  *
129  * Returns: a ModestPresetsServerType with the required information
130  */
131 ModestPresetsServerType          modest_presets_get_info_server_type (ModestPresets *self,
132                                                                       const gchar *provider_id,
133                                                                       gboolean incoming_server);
134
135 /**
136  * modest_presets_get_info_server_security:
137  * @self: a valid ModestPresets instance
138  * @provider_id: ID of the provider 
139  * @incoming_server: get the incoming mailserver if TRUE, get the
140  * outgoing server otherwise
141  *
142  * get information about some incoming or outgoing mailserver
143  *
144  * Returns: ModestPresetsSecurity ORable flags with the required information
145  */                                         
146 ModestPresetsSecurity          modest_presets_get_info_server_security (ModestPresets *self,
147                                                                         const gchar *provider_id,
148                                                                         gboolean incoming_server);
149
150
151 /**
152  * modest_presets_get_port:
153  * @self: a valid ModestPresets instance
154  * @provider_id: ID of the provider 
155  * @incoming_server: get port# for the incoming mailserver if TRUE, for the outgoing server otherwise
156  *
157  * Returns: the specific port number for some provider
158  * function return 0 if the normal port number is valid
159  *
160  */
161 guint modest_presets_get_port (ModestPresets *self, const gchar* provider_id,
162                                gboolean incoming_server);
163
164
165 /**
166  * modest_presets_destroy:
167  * @self: a valid ModestPresets instance (ie. must not be NULL)
168  *
169  * destroy ModestPresets instance; this is required after you're done with it.
170  */
171 void                      modest_presets_destroy         (ModestPresets *self);
172
173
174 #endif /*__MODEST_PRESETS__*/
175
176