2 * e-source-authentication.c
4 * This program 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 License, or (at your option) version 3.
9 * This program 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.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with the program; if not, see <http://www.gnu.org/licenses/>
20 * SECTION: e-source-authentication
21 * @include: libedataserver/libedataserver.h
22 * @short_description: #ESource extension for authentication settings
24 * The #ESourceAuthentication extension tracks authentication settings
25 * for a user account on a remote server.
27 * Access the extension as follows:
30 * #include <libedataserver/libedataserver.h>
32 * ESourceAuthentication *extension;
34 * extension = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION);
38 #include "e-source-authentication.h"
40 #include <libedataserver/e-data-server-util.h>
42 #define E_SOURCE_AUTHENTICATION_GET_PRIVATE(obj) \
43 (G_TYPE_INSTANCE_GET_PRIVATE \
44 ((obj), E_TYPE_SOURCE_AUTHENTICATION, ESourceAuthenticationPrivate))
46 struct _ESourceAuthenticationPrivate {
53 /* GNetworkAddress caches data internally, so we maintain the
54 * instance to preserve the cache as opposed to just creating
55 * a new GNetworkAddress instance each time it's requested. */
56 GSocketConnectable *connectable;
69 ESourceAuthentication,
70 e_source_authentication,
71 E_TYPE_SOURCE_EXTENSION)
74 source_authentication_update_connectable (ESourceAuthentication *extension)
79 /* This MUST be called with the property_lock acquired. */
81 g_clear_object (&extension->priv->connectable);
83 host = e_source_authentication_get_host (extension);
84 port = e_source_authentication_get_port (extension);
87 GSocketConnectable *connectable;
88 connectable = g_network_address_new (host, port);
89 extension->priv->connectable = connectable;
94 source_authentication_set_property (GObject *object,
99 switch (property_id) {
101 e_source_authentication_set_host (
102 E_SOURCE_AUTHENTICATION (object),
103 g_value_get_string (value));
107 e_source_authentication_set_method (
108 E_SOURCE_AUTHENTICATION (object),
109 g_value_get_string (value));
113 e_source_authentication_set_port (
114 E_SOURCE_AUTHENTICATION (object),
115 g_value_get_uint (value));
119 e_source_authentication_set_user (
120 E_SOURCE_AUTHENTICATION (object),
121 g_value_get_string (value));
125 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
129 source_authentication_get_property (GObject *object,
134 switch (property_id) {
135 case PROP_CONNECTABLE:
136 g_value_take_object (
138 e_source_authentication_ref_connectable (
139 E_SOURCE_AUTHENTICATION (object)));
143 g_value_take_string (
145 e_source_authentication_dup_host (
146 E_SOURCE_AUTHENTICATION (object)));
150 g_value_take_string (
152 e_source_authentication_dup_method (
153 E_SOURCE_AUTHENTICATION (object)));
159 e_source_authentication_get_port (
160 E_SOURCE_AUTHENTICATION (object)));
164 g_value_take_string (
166 e_source_authentication_dup_user (
167 E_SOURCE_AUTHENTICATION (object)));
171 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
175 source_authentication_dispose (GObject *object)
177 ESourceAuthenticationPrivate *priv;
179 priv = E_SOURCE_AUTHENTICATION_GET_PRIVATE (object);
181 g_clear_object (&priv->connectable);
183 /* Chain up to parent's dispose() method. */
184 G_OBJECT_CLASS (e_source_authentication_parent_class)->dispose (object);
188 source_authentication_finalize (GObject *object)
190 ESourceAuthenticationPrivate *priv;
192 priv = E_SOURCE_AUTHENTICATION_GET_PRIVATE (object);
194 g_mutex_clear (&priv->property_lock);
197 g_free (priv->method);
200 /* Chain up to parent's finalize() method. */
201 G_OBJECT_CLASS (e_source_authentication_parent_class)->finalize (object);
205 e_source_authentication_class_init (ESourceAuthenticationClass *class)
207 GObjectClass *object_class;
208 ESourceExtensionClass *extension_class;
210 g_type_class_add_private (class, sizeof (ESourceAuthenticationPrivate));
212 object_class = G_OBJECT_CLASS (class);
213 object_class->set_property = source_authentication_set_property;
214 object_class->get_property = source_authentication_get_property;
215 object_class->dispose = source_authentication_dispose;
216 object_class->finalize = source_authentication_finalize;
218 extension_class = E_SOURCE_EXTENSION_CLASS (class);
219 extension_class->name = E_SOURCE_EXTENSION_AUTHENTICATION;
221 g_object_class_install_property (
224 g_param_spec_object (
227 "A GSocketConnectable constructed "
228 "from the host and port properties",
229 G_TYPE_SOCKET_CONNECTABLE,
231 G_PARAM_STATIC_STRINGS));
233 g_object_class_install_property (
236 g_param_spec_string (
239 "Host name for the remote account",
243 G_PARAM_STATIC_STRINGS |
244 E_SOURCE_PARAM_SETTING));
246 g_object_class_install_property (
249 g_param_spec_string (
252 "Authentication method",
256 G_PARAM_STATIC_STRINGS |
257 E_SOURCE_PARAM_SETTING));
259 g_object_class_install_property (
265 "Port number for the remote account",
269 G_PARAM_STATIC_STRINGS |
270 E_SOURCE_PARAM_SETTING));
272 g_object_class_install_property (
275 g_param_spec_string (
278 "User name for the remote account",
282 G_PARAM_STATIC_STRINGS |
283 E_SOURCE_PARAM_SETTING));
287 e_source_authentication_init (ESourceAuthentication *extension)
289 extension->priv = E_SOURCE_AUTHENTICATION_GET_PRIVATE (extension);
290 g_mutex_init (&extension->priv->property_lock);
294 * e_source_authentication_required:
295 * @extension: an #ESourceAuthentication
297 * This is a convenience function which returns whether authentication
298 * is required at all, regardless of the method used. This relies on
299 * the convention of setting #ESourceAuthentication:method to "none"
300 * when authentication is <emphasis>not</emphasis> required.
302 * Returns: whether authentication is required at all
307 e_source_authentication_required (ESourceAuthentication *extension)
311 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), FALSE);
313 method = e_source_authentication_get_method (extension);
314 g_return_val_if_fail (method != NULL && *method != '\0', FALSE);
316 return (g_strcmp0 (method, "none") != 0);
320 * e_source_authentication_ref_connectable:
321 * @extension: an #ESourceAuthentication
323 * Returns a #GSocketConnectable instance constructed from @extension's
324 * #ESourceAuthentication:host and #ESourceAuthentication:port properties,
325 * or %NULL if the #ESourceAuthentication:host is not set.
327 * The returned #GSocketConnectable is referenced for thread-safety and must
328 * be unreferenced with g_object_unref() when finished with it.
330 * Returns: (transfer full): a #GSocketConnectable, or %NULL
335 e_source_authentication_ref_connectable (ESourceAuthentication *extension)
337 GSocketConnectable *connectable = NULL;
339 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
341 g_mutex_lock (&extension->priv->property_lock);
343 if (extension->priv->connectable != NULL)
344 connectable = g_object_ref (extension->priv->connectable);
346 g_mutex_unlock (&extension->priv->property_lock);
352 * e_source_authentication_get_host:
353 * @extension: an #ESourceAuthentication
355 * Returns the host name used to authenticate to a remote account.
357 * Returns: the host name of a remote account
362 e_source_authentication_get_host (ESourceAuthentication *extension)
364 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
366 return extension->priv->host;
370 * e_source_authentication_dup_host:
371 * @extension: an #ESourceAuthentication
373 * Thread-safe variation of e_source_authentication_get_host().
374 * Use this function when accessing @extension from multiple threads.
376 * The returned string should be freed with g_free() when no longer needed.
378 * Returns: a newly-allocated copy of #ESourceAuthentication:host
383 e_source_authentication_dup_host (ESourceAuthentication *extension)
385 const gchar *protected;
388 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
390 g_mutex_lock (&extension->priv->property_lock);
392 protected = e_source_authentication_get_host (extension);
393 duplicate = g_strdup (protected);
395 g_mutex_unlock (&extension->priv->property_lock);
401 * e_source_authentication_set_host:
402 * @extension: an #ESourceAuthentication
403 * @host: (allow-none): a host name, or %NULL
405 * Sets the host name used to authenticate to a remote account.
407 * The internal copy of @host is automatically stripped of leading and
408 * trailing whitespace. If the resulting string is empty, %NULL is set
414 e_source_authentication_set_host (ESourceAuthentication *extension,
417 g_return_if_fail (E_IS_SOURCE_AUTHENTICATION (extension));
419 g_mutex_lock (&extension->priv->property_lock);
421 if (g_strcmp0 (extension->priv->host, host) == 0) {
422 g_mutex_unlock (&extension->priv->property_lock);
426 g_free (extension->priv->host);
427 extension->priv->host = e_util_strdup_strip (host);
429 source_authentication_update_connectable (extension);
431 g_mutex_unlock (&extension->priv->property_lock);
433 g_object_notify (G_OBJECT (extension), "host");
435 /* Changing the host also changes the connectable. */
436 g_object_notify (G_OBJECT (extension), "connectable");
440 * e_source_authentication_get_method:
441 * @extension: an #ESourceAuthentication
443 * Returns the authentication method for a remote account. There are
444 * no pre-defined method names; backends are free to set this however
445 * they wish. If authentication is not required for a remote account,
446 * the convention is to set #ESourceAuthentication:method to "none".
448 * Returns: the authentication method for a remote account
453 e_source_authentication_get_method (ESourceAuthentication *extension)
455 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
457 return extension->priv->method;
461 * e_source_authentication_dup_method:
462 * @extension: an #ESourceAuthentication
464 * Thread-safe variation of e_source_authentication_get_method().
465 * Use this function when accessing @extension from multiple threads.
467 * The returned string should be freed with g_free() when no longer needed.
469 * Returns: a newly-allocated copy of #ESourceAuthentication:method
474 e_source_authentication_dup_method (ESourceAuthentication *extension)
476 const gchar *protected;
479 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
481 g_mutex_lock (&extension->priv->property_lock);
483 protected = e_source_authentication_get_method (extension);
484 duplicate = g_strdup (protected);
486 g_mutex_unlock (&extension->priv->property_lock);
492 * e_source_authentication_set_method:
493 * @extension: an #ESourceAuthentication
494 * @method: (allow-none): authentication method, or %NULL
496 * Sets the authentication method for a remote account. There are no
497 * pre-defined method names; backends are free to set this however they
498 * wish. If authentication is not required for a remote account, the
499 * convention is to set the method to "none". In keeping with that
500 * convention, #ESourceAuthentication:method will be set to "none" if
501 * @method is %NULL or an empty string.
506 e_source_authentication_set_method (ESourceAuthentication *extension,
509 g_return_if_fail (E_IS_SOURCE_AUTHENTICATION (extension));
511 g_mutex_lock (&extension->priv->property_lock);
513 if (g_strcmp0 (extension->priv->method, method) == 0) {
514 g_mutex_unlock (&extension->priv->property_lock);
518 g_free (extension->priv->method);
519 extension->priv->method = e_util_strdup_strip (method);
521 if (extension->priv->method == NULL)
522 extension->priv->method = g_strdup ("none");
524 g_mutex_unlock (&extension->priv->property_lock);
526 g_object_notify (G_OBJECT (extension), "method");
530 * e_source_authentication_get_port:
531 * @extension: an #ESourceAuthentication
533 * Returns the port number used to authenticate to a remote account.
535 * Returns: the port number of a remote account
540 e_source_authentication_get_port (ESourceAuthentication *extension)
542 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), 0);
544 return extension->priv->port;
548 * e_source_authentication_set_port:
549 * @extension: an #ESourceAuthentication
550 * @port: a port number
552 * Sets the port number used to authenticate to a remote account.
557 e_source_authentication_set_port (ESourceAuthentication *extension,
560 g_return_if_fail (E_SOURCE_AUTHENTICATION (extension));
562 g_mutex_lock (&extension->priv->property_lock);
564 if (extension->priv->port == port) {
565 g_mutex_unlock (&extension->priv->property_lock);
569 extension->priv->port = port;
571 source_authentication_update_connectable (extension);
573 g_mutex_unlock (&extension->priv->property_lock);
575 g_object_notify (G_OBJECT (extension), "port");
577 /* Changing the port also changes the connectable. */
578 g_object_notify (G_OBJECT (extension), "connectable");
582 * e_source_authentication_get_user:
583 * @extension: an #ESourceAuthentication
585 * Returns the user name used to authenticate to a remote account.
587 * Returns: the user name of a remote account
592 e_source_authentication_get_user (ESourceAuthentication *extension)
594 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
596 return extension->priv->user;
600 * e_source_authentication_dup_user:
601 * @extension: an #ESourceAuthentication
603 * Thread-safe variation of e_source_authentication_get_user().
604 * Use this function when accessing @extension from multiple threads.
606 * The returned string should be freed with g_free() when no longer needed.
608 * Returns: a newly-allocated copy of #ESourceAuthentication:user
613 e_source_authentication_dup_user (ESourceAuthentication *extension)
615 const gchar *protected;
618 g_return_val_if_fail (E_IS_SOURCE_AUTHENTICATION (extension), NULL);
620 g_mutex_lock (&extension->priv->property_lock);
622 protected = e_source_authentication_get_user (extension);
623 duplicate = g_strdup (protected);
625 g_mutex_unlock (&extension->priv->property_lock);
631 * e_source_authentication_set_user:
632 * @extension: an #ESourceAuthentication
633 * @user: (allow-none): a user name, or %NULL
635 * Sets the user name used to authenticate to a remote account.
637 * The internal copy of @user is automatically stripped of leading and
638 * trailing whitespace. If the resulting string is empty, %NULL is set
644 e_source_authentication_set_user (ESourceAuthentication *extension,
647 g_return_if_fail (E_IS_SOURCE_AUTHENTICATION (extension));
649 g_mutex_lock (&extension->priv->property_lock);
651 if (g_strcmp0 (extension->priv->user, user) == 0) {
652 g_mutex_unlock (&extension->priv->property_lock);
656 g_free (extension->priv->user);
657 extension->priv->user = e_util_strdup_strip (user);
659 g_mutex_unlock (&extension->priv->property_lock);
661 g_object_notify (G_OBJECT (extension), "user");