src/common/gsignond-session-data.c

   1 /* vi: set et sw=4 ts=4 cino=t0,(0: */
   2 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   3 /*
   4  * This file is part of gsignond
   5  *
   6  * Copyright (C) 2012-2013 Intel Corporation.
   7  *
   8  * Contact: Alexander Kanavin <alex.kanavin@gmail.com>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2.1 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  23  * 02110-1301 USA
  24  */
  25
  26 #include "gsignond/gsignond-session-data.h"
  27 #include "gsignond/gsignond-utils.h"
  28
  29
  30 /**
  31  * SECTION:gsignond-session-data
  32  * @short_description: definitions for authentication session parameters
  33  * @title: GSignondSessionData
  34  * @include: gsignond/gsignond-session-data.h
  35  *
  36  * This file provides commonly used parameters for authentication sessions.
  37  * For each of those a getter and setter is defined, on #GSignondSessionData
  38  * container. The plugins may not use all of these parameters, and they commonly
  39  * require additional, custom parameters which are set using #GSignondDictionary
  40  * setters with explicit key string.
  41  */
  42
  43
  44 /**
  45  * GSignondSessionData:
  46  *
  47  * #GSignondSessionData is simply a typedef for #GSignondDictionary, which
  48  * means the developers may also freely use methods associated with that structure,
  49  * in particular for creating a #GSignondSessionData object with
  50  * gsignond_dictionary_new().
  51  */
  52
  53 /**
  54  * GSignondUiPolicy:
  55  * @GSIGNOND_UI_POLICY_DEFAULT: use a default user interaction scenario
  56  * @GSIGNOND_UI_POLICY_REQUEST_PASSWORD: force an authorization request from the user;
  57  * any cached access tokens should be discarded by the plugin.
  58  * @GSIGNOND_UI_POLICY_NO_USER_INTERACTION: force no interaction with the user
  59  * @GSIGNOND_UI_POLICY_VALIDATION: interaction with the user is only allowed
  60  * for validation captchas and similar security measures
  61  *
  62  * Policy setting to define how plugins should handle interaction with the user.
  63  */
  64
  65 /**
  66  * gsignond_session_data_get_username:
  67  * @data: a #GSignondDictionary structure
  68  *
  69  * A getter for a username associated with the authentication session.
  70  *
  71  * Returns: (transfer none)
  72  */
  73 const gchar *
  74 gsignond_session_data_get_username (GSignondSessionData *data)
  75 {
  76     return gsignond_dictionary_get_string (data, "UserName");
  77 }
  78
  79 /**
  80  * gsignond_session_data_set_username:
  81  * @data: a #GSignondDictionary structure
  82  * @username: username to set
  83  *
  84  * A setter for a username associated with the authentication session.
  85  */
  86 void
  87 gsignond_session_data_set_username (GSignondSessionData *data,
  88                                     const gchar *username)
  89 {
  90     gsignond_dictionary_set_string (data, "UserName", username);
  91 }
  92
  93 /**
  94  * gsignond_session_data_get_secret:
  95  * @data: a #GSignondDictionary structure
  96  *
  97  * A getter for a secret (e.g. a password) associated with the authentication session.
  98  *
  99  * Returns: (transfer none)
 100  */
 101 const gchar *
 102 gsignond_session_data_get_secret (GSignondSessionData *data)
 103 {
 104     return gsignond_dictionary_get_string (data, "Secret");
 105 }
 106
 107 /**
 108  * gsignond_session_data_set_secret:
 109  * @data: a #GSignondDictionary structure
 110  * @secret: a secret to set
 111  *
 112  * A setter for a secret (e.g. a password) associated with the authentication session.
 113  */
 114 void
 115 gsignond_session_data_set_secret (GSignondSessionData *data,
 116                                   const gchar *secret)
 117 {
 118     gsignond_dictionary_set_string (data, "Secret", secret);
 119 }
 120
 121 /**
 122  * gsignond_session_data_get_realm:
 123  * @data: a #GSignondDictionary structure
 124  *
 125  * A getter for a realm associated with the authentication session.
 126  *
 127  * Returns: (transfer none)
 128  */
 129 const gchar *
 130 gsignond_session_data_get_realm (GSignondSessionData *data)
 131 {
 132     return gsignond_dictionary_get_string (data, "Realm");
 133 }
 134
 135 /**
 136  * gsignond_session_data_set_allowed_realms:
 137  * @data: a #GSignondDictionary structure
 138  * @realms: a #GSequence if allowed realms
 139  *
 140  * A setter for a list of realms allowed for the identity use.
 141  */
 142 void
 143 gsignond_session_data_set_allowed_realms (GSignondSessionData *data,
 144                                           GSequence *realms)
 145 {
 146     gsignond_dictionary_set (data, "AllowedRealms",
 147                              gsignond_sequence_to_variant (realms));
 148 }
 149
 150 /**
 151  * gsignond_session_data_get_allowed_realms:
 152  * @data: a #GSignondDictionary structure
 153  *
 154  * A getter for a list of realms allowed for the identity use.
 155  *
 156  * Returns: (transfer full): #GSequence of allowed realms
 157  */
 158 GSequence *
 159 gsignond_session_data_get_allowed_realms (GSignondSessionData *data)
 160 {
 161     return gsignond_variant_to_sequence (gsignond_dictionary_get (data,
 162                                                                   "AllowedRealms"));
 163 }
 164
 165 /**
 166  * gsignond_session_data_set_realm:
 167  * @data: a #GSignondDictionary structure
 168  * @realm: a realm to set
 169  *
 170  * A setter for a realm associated with the authentication session.
 171  */
 172 void
 173 gsignond_session_data_set_realm (GSignondSessionData *data,
 174                                  const gchar *realm)
 175 {
 176     gsignond_dictionary_set_string (data, "Realm", realm);
 177 }
 178
 179 /**
 180  * gsignond_session_data_get_caption:
 181  * @data: a #GSignondDictionary structure
 182  *
 183  * A getter for a caption associated with the authentication session.
 184  * Caption tells the user which application/credentials/provider is requestion
 185  * authentication.
 186  *
 187  * Returns: (transfer none)
 188  */
 189 const gchar *
 190 gsignond_session_data_get_caption (GSignondSessionData *data)
 191 {
 192     return gsignond_dictionary_get_string (data, "Caption");
 193 }
 194
 195 /**
 196  * gsignond_session_data_set_caption:
 197  * @data: a #GSignondDictionary structure
 198  * @caption: a caption to set
 199  *
 200  * A setter for a caption associated with the authentication session.
 201  * Caption tells the user which application/credentials/provider is requestion
 202  * authentication.
 203  */
 204 void
 205 gsignond_session_data_set_caption (GSignondSessionData *data,
 206                                    const gchar *caption)
 207 {
 208     gsignond_dictionary_set_string (data, "Caption", caption);
 209 }
 210
 211 /**
 212  * gsignond_session_data_get_renew_token:
 213  * @data: a #GSignondDictionary structure
 214  * @renew_token: the value for the parameter is written here
 215  *
 216  * A getter for a renew token property associated with the authentication session.
 217  * This property tells the plugin to discard any cached tokens and start
 218  * the authentication process anew.
 219  *
 220  * Returns: whether the key-value pair exists in the @data dictionary or not.
 221  */
 222 gboolean
 223 gsignond_session_data_get_renew_token (GSignondSessionData *data,
 224                                        gboolean *renew_token)
 225 {
 226     return gsignond_dictionary_get_boolean (data, "RenewToken", renew_token);
 227 }
 228
 229 /**
 230  * gsignond_session_data_set_renew_token:
 231  * @data: a #GSignondDictionary structure
 232  * @renew_token: whether to renew the token set
 233  *
 234  * A setter for a renew token property associated with the authentication session.
 235  * This property tells the plugin to discard any cached tokens and start
 236  * the authentication process anew.
 237  */
 238 void
 239 gsignond_session_data_set_renew_token (GSignondSessionData *data,
 240                                        gboolean renew_token)
 241 {
 242     gsignond_dictionary_set_boolean (data, "RenewToken", renew_token);
 243 }
 244
 245 /**
 246  * gsignond_session_data_get_ui_policy:
 247  * @data: a #GSignondDictionary structure
 248  * @ui_policy: the value for the parameter is written here
 249  *
 250  * A getter for UI policy setting associated with the authentication session.
 251  * The UI policy indicates how the authentication plugin should interact with the user.
 252  *
 253  * Returns: whether the key-value pair exists in the @data dictionary or not.
 254  */
 255 gboolean
 256 gsignond_session_data_get_ui_policy (GSignondSessionData *data,
 257                                      GSignondUiPolicy *ui_policy)
 258 {
 259     return gsignond_dictionary_get_uint32 (data, "UiPolicy", ui_policy);
 260 }
 261
 262 /**
 263  * gsignond_session_data_set_ui_policy:
 264  * @data: a #GSignondDictionary structure
 265  * @ui_policy: ui policy to set
 266  *
 267  * A getter for UI policy setting associated with the authentication session.
 268  * The UI policy indicates how the authentication plugin should interact with the user.
 269  */
 270 void
 271 gsignond_session_data_set_ui_policy (GSignondSessionData *data,
 272                                      GSignondUiPolicy ui_policy)
 273 {
 274     gsignond_dictionary_set_uint32 (data, "UiPolicy", ui_policy);
 275 }
 276
 277 /**
 278  * gsignond_session_data_get_network_proxy:
 279  * @data: a #GSignondDictionary structure
 280  *
 281  * A getter for a network proxy setting associated with the authentication session.
 282  * If this property is not set, the default system proxy settings should be used.
 283  *
 284  * Returns: (transfer none)
 285  */
 286 const gchar *
 287 gsignond_session_data_get_network_proxy (GSignondSessionData *data)
 288 {
 289     return gsignond_dictionary_get_string (data, "NetworkProxy");
 290 }
 291
 292 /**
 293  * gsignond_session_data_set_network_proxy:
 294  * @data: a #GSignondDictionary structure
 295  * @network_proxy: network proxy to use
 296  *
 297  * A setter for a network proxy setting associated with the authentication session.
 298  * If this property is not set, the default system proxy settings should be used.
 299  */
 300 void
 301 gsignond_session_data_set_network_proxy (GSignondSessionData *data,
 302                                          const gchar *network_proxy)
 303 {
 304     gsignond_dictionary_set_string (data, "NetworkProxy", network_proxy);
 305 }
 306
 307 /**
 308  * gsignond_session_data_get_network_timeout:
 309  * @data: a #GSignondDictionary structure
 310  * @network_timeout: the value for the parameter is written here
 311  *
 312  * A getter for a network timeout setting associated with the authentication session.
 313  * This can be used to change the default timeout in case of unresponsive servers.
 314  *
 315  * Returns: whether the key-value pair exists in the @data dictionary or not.
 316  */
 317 gboolean
 318 gsignond_session_data_get_network_timeout (GSignondSessionData *data,
 319                                            guint32 *network_timeout)
 320 {
 321     return gsignond_dictionary_get_uint32 (data, "NetworkTimeout",
 322                                            network_timeout);
 323 }
 324
 325 /**
 326  * gsignond_session_data_set_network_timeout:
 327  * @data: a #GSignondDictionary structure
 328  * @network_timeout: network timeout to use
 329  *
 330  * A setter for a network timeout setting associated with the authentication session.
 331  * This can be used to change the default timeout in case of unresponsive servers.
 332  */
 333 void
 334 gsignond_session_data_set_network_timeout (GSignondSessionData *data,
 335                                            guint32 network_timeout)
 336 {
 337     gsignond_dictionary_set_uint32 (data, "NetworkTimeout",
 338                                     network_timeout);
 339 }
 340
 341 /**
 342  * gsignond_session_data_get_window_id:
 343  * @data: a #GSignondDictionary structure
 344  * @window_id: the value for the parameter is written here
 345  *
 346  * A getter for a window id setting associated with the authentication session.
 347  * This can be used to embed the user interaction window produced by the authentication
 348  * session into an application window.
 349  *
 350  * Returns: whether the key-value pair exists in the @data dictionary or not.
 351  */
 352 gboolean
 353 gsignond_session_data_get_window_id (GSignondSessionData *data,
 354                                      guint32 *window_id)
 355 {
 356     return gsignond_dictionary_get_uint32 (data, "WindowId", window_id);
 357 }
 358
 359 /**
 360  * gsignond_session_data_set_window_id:
 361  * @data: a #GSignondDictionary structure
 362  * @window_id: window id to use
 363  *
 364  * A setter for a window id setting associated with the authentication session.
 365  * This can be used to embed the user interaction window produced by the authentication
 366  * session into an application window.
 367  */
 368 void
 369 gsignond_session_data_set_window_id (GSignondSessionData *data,
 370                                      guint32 window_id)
 371 {
 372     gsignond_dictionary_set_uint32 (data, "WindowId", window_id);
 373 }
 374