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
  28
  29 /**
  30  * SECTION:gsignond-session-data
  31  * @short_description: definitions for authentication session parameters
  32  * @title: GSignondSessionData
  33  * @include: gsignond/gsignond-session-data.h
  34  *
  35  * This file provides commonly used parameters for authentication sessions.
  36  * For each of those a getter and setter is defined, on #GSignondSessionData
  37  * container. The plugins may not use all of these parameters, and they commonly
  38  * require additional, custom parameters which are set using #GSignondDictionary
  39  * setters with explicit key string.
  40  */
  41
  42
  43 /**
  44  * GSignondSessionData:
  45  *
  46  * #GSignondSessionData is simply a typedef for #GSignondDictionary, which
  47  * means the developers may also freely use methods associated with that structure,
  48  * in particular for creating a #GSignondSessionData object with
  49  * gsignond_dictionary_new().
  50  */
  51
  52 /**
  53  * GSignondUiPolicy:
  54  * @GSIGNOND_UI_POLICY_DEFAULT: use a default user interaction scenario
  55  * @GSIGNOND_UI_POLICY_REQUEST_PASSWORD: force an authorization request from the user;
  56  * any cached access tokens should be discarded by the plugin.
  57  * @GSIGNOND_UI_POLICY_NO_USER_INTERACTION: force no interaction with the user
  58  * @GSIGNOND_UI_POLICY_VALIDATION: interaction with the user is only allowed
  59  * for validation captchas and similar security measures
  60  *
  61  * Policy setting to define how plugins should handle interaction with the user.
  62  */
  63
  64 /**
  65  * gsignond_session_data_get_username:
  66  * @data: a #GSignondDictionary structure
  67  *
  68  * A getter for a username associated with the authentication session.
  69  *
  70  * Returns: (transfer none)
  71  */
  72 const gchar *
  73 gsignond_session_data_get_username (GSignondSessionData *data)
  74 {
  75     return gsignond_dictionary_get_string (data, "UserName");
  76 }
  77
  78 /**
  79  * gsignond_session_data_set_username:
  80  * @data: a #GSignondDictionary structure
  81  * @username: username to set
  82  *
  83  * A setter for a username associated with the authentication session.
  84  */
  85 void
  86 gsignond_session_data_set_username (GSignondSessionData *data,
  87                                     const gchar *username)
  88 {
  89     gsignond_dictionary_set_string (data, "UserName", username);
  90 }
  91
  92 /**
  93  * gsignond_session_data_get_secret:
  94  * @data: a #GSignondDictionary structure
  95  *
  96  * A getter for a secret (e.g. a password) associated with the authentication session.
  97  *
  98  * Returns: (transfer none)
  99  */
 100 const gchar *
 101 gsignond_session_data_get_secret (GSignondSessionData *data)
 102 {
 103     return gsignond_dictionary_get_string (data, "Secret");
 104 }
 105
 106 /**
 107  * gsignond_session_data_set_secret:
 108  * @data: a #GSignondDictionary structure
 109  * @secret: a secret to set
 110  *
 111  * A setter for a secret (e.g. a password) associated with the authentication session.
 112  */
 113 void
 114 gsignond_session_data_set_secret (GSignondSessionData *data,
 115                                   const gchar *secret)
 116 {
 117     gsignond_dictionary_set_string (data, "Secret", secret);
 118 }
 119
 120 /**
 121  * gsignond_session_data_get_realm:
 122  * @data: a #GSignondDictionary structure
 123  *
 124  * A getter for a realm associated with the authentication session.
 125  *
 126  * Returns: (transfer none)
 127  */
 128 const gchar *
 129 gsignond_session_data_get_realm (GSignondSessionData *data)
 130 {
 131     return gsignond_dictionary_get_string (data, "Realm");
 132 }
 133
 134 /**
 135  * gsignond_session_data_set_realm:
 136  * @data: a #GSignondDictionary structure
 137  * @realm: a realm to set
 138  *
 139  * A setter for a realm associated with the authentication session.
 140  */
 141 void
 142 gsignond_session_data_set_realm (GSignondSessionData *data,
 143                                  const gchar *realm)
 144 {
 145     gsignond_dictionary_set_string (data, "Realm", realm);
 146 }
 147
 148 /**
 149  * gsignond_session_data_get_caption:
 150  * @data: a #GSignondDictionary structure
 151  *
 152  * A getter for a caption associated with the authentication session.
 153  * Caption tells the user which application/credentials/provider is requestion
 154  * authentication.
 155  *
 156  * Returns: (transfer none)
 157  */
 158 const gchar *
 159 gsignond_session_data_get_caption (GSignondSessionData *data)
 160 {
 161     return gsignond_dictionary_get_string (data, "Caption");
 162 }
 163
 164 /**
 165  * gsignond_session_data_set_caption:
 166  * @data: a #GSignondDictionary structure
 167  * @caption: a caption to set
 168  *
 169  * A setter for a caption associated with the authentication session.
 170  * Caption tells the user which application/credentials/provider is requestion
 171  * authentication.
 172  */
 173 void
 174 gsignond_session_data_set_caption (GSignondSessionData *data,
 175                                    const gchar *caption)
 176 {
 177     gsignond_dictionary_set_string (data, "Caption", caption);
 178 }
 179
 180 /**
 181  * gsignond_session_data_get_renew_token:
 182  * @data: a #GSignondDictionary structure
 183  * @renew_token: the value for the parameter is written here
 184  *
 185  * A getter for a renew token property associated with the authentication session.
 186  * This property tells the plugin to discard any cached tokens and start
 187  * the authentication process anew.
 188  *
 189  * Returns: whether the key-value pair exists in the @data dictionary or not.
 190  */
 191 gboolean
 192 gsignond_session_data_get_renew_token (GSignondSessionData *data,
 193                                        gboolean *renew_token)
 194 {
 195     return gsignond_dictionary_get_boolean (data, "RenewToken", renew_token);
 196 }
 197
 198 /**
 199  * gsignond_session_data_set_renew_token:
 200  * @data: a #GSignondDictionary structure
 201  * @renew_token: whether to renew the token set
 202  *
 203  * A setter for a renew token property associated with the authentication session.
 204  * This property tells the plugin to discard any cached tokens and start
 205  * the authentication process anew.
 206  */
 207 void
 208 gsignond_session_data_set_renew_token (GSignondSessionData *data,
 209                                        gboolean renew_token)
 210 {
 211     gsignond_dictionary_set_boolean (data, "RenewToken", renew_token);
 212 }
 213
 214 /**
 215  * gsignond_session_data_get_ui_policy:
 216  * @data: a #GSignondDictionary structure
 217  * @ui_policy: the value for the parameter is written here
 218  *
 219  * A getter for UI policy setting associated with the authentication session.
 220  * The UI policy indicates how the authentication plugin should interact with the user.
 221  *
 222  * Returns: whether the key-value pair exists in the @data dictionary or not.
 223  */
 224 gboolean
 225 gsignond_session_data_get_ui_policy (GSignondSessionData *data,
 226                                      GSignondUiPolicy *ui_policy)
 227 {
 228     return gsignond_dictionary_get_uint32 (data, "UiPolicy", ui_policy);
 229 }
 230
 231 /**
 232  * gsignond_session_data_set_ui_policy:
 233  * @data: a #GSignondDictionary structure
 234  * @ui_policy: ui policy to set
 235  *
 236  * A getter for UI policy setting associated with the authentication session.
 237  * The UI policy indicates how the authentication plugin should interact with the user.
 238  */
 239 void
 240 gsignond_session_data_set_ui_policy (GSignondSessionData *data,
 241                                      GSignondUiPolicy ui_policy)
 242 {
 243     gsignond_dictionary_set_uint32 (data, "UiPolicy", ui_policy);
 244 }
 245
 246 /**
 247  * gsignond_session_data_get_network_proxy:
 248  * @data: a #GSignondDictionary structure
 249  *
 250  * A getter for a network proxy setting associated with the authentication session.
 251  * If this property is not set, the default system proxy settings should be used.
 252  *
 253  * Returns: (transfer none)
 254  */
 255 const gchar *
 256 gsignond_session_data_get_network_proxy (GSignondSessionData *data)
 257 {
 258     return gsignond_dictionary_get_string (data, "NetworkProxy");
 259 }
 260
 261 /**
 262  * gsignond_session_data_set_network_proxy:
 263  * @data: a #GSignondDictionary structure
 264  * @network_proxy: network proxy to use
 265  *
 266  * A setter for a network proxy setting associated with the authentication session.
 267  * If this property is not set, the default system proxy settings should be used.
 268  */
 269 void
 270 gsignond_session_data_set_network_proxy (GSignondSessionData *data,
 271                                          const gchar *network_proxy)
 272 {
 273     gsignond_dictionary_set_string (data, "NetworkProxy", network_proxy);
 274 }
 275
 276 /**
 277  * gsignond_session_data_get_network_timeout:
 278  * @data: a #GSignondDictionary structure
 279  * @network_timeout: the value for the parameter is written here
 280  *
 281  * A getter for a network timeout setting associated with the authentication session.
 282  * This can be used to change the default timeout in case of unresponsive servers.
 283  *
 284  * Returns: whether the key-value pair exists in the @data dictionary or not.
 285  */
 286 gboolean
 287 gsignond_session_data_get_network_timeout (GSignondSessionData *data,
 288                                            guint32 *network_timeout)
 289 {
 290     return gsignond_dictionary_get_uint32 (data, "NetworkTimeout",
 291                                            network_timeout);
 292 }
 293
 294 /**
 295  * gsignond_session_data_set_network_timeout:
 296  * @data: a #GSignondDictionary structure
 297  * @network_timeout: network timeout to use
 298  *
 299  * A setter for a network timeout setting associated with the authentication session.
 300  * This can be used to change the default timeout in case of unresponsive servers.
 301  */
 302 void
 303 gsignond_session_data_set_network_timeout (GSignondSessionData *data,
 304                                            guint32 network_timeout)
 305 {
 306     gsignond_dictionary_set_uint32 (data, "NetworkTimeout",
 307                                     network_timeout);
 308 }
 309
 310 /**
 311  * gsignond_session_data_get_window_id:
 312  * @data: a #GSignondDictionary structure
 313  * @window_id: the value for the parameter is written here
 314  *
 315  * A getter for a window id setting associated with the authentication session.
 316  * This can be used to embed the user interaction window produced by the authentication
 317  * session into an application window.
 318  *
 319  * Returns: whether the key-value pair exists in the @data dictionary or not.
 320  */
 321 gboolean
 322 gsignond_session_data_get_window_id (GSignondSessionData *data,
 323                                      guint32 *window_id)
 324 {
 325     return gsignond_dictionary_get_uint32 (data, "WindowId", window_id);
 326 }
 327
 328 /**
 329  * gsignond_session_data_set_window_id:
 330  * @data: a #GSignondDictionary structure
 331  * @window_id: window id to use
 332  *
 333  * A setter for a window id setting associated with the authentication session.
 334  * This can be used to embed the user interaction window produced by the authentication
 335  * session into an application window.
 336  */
 337 void
 338 gsignond_session_data_set_window_id (GSignondSessionData *data,
 339                                      guint32 window_id)
 340 {
 341     gsignond_dictionary_set_uint32 (data, "WindowId", window_id);
 342 }
 343