src/libedataserver/e-credentials.h

   1 /*
   2  * e-credentials.h
   3  *
   4  * Copyright (C) 2011 Red Hat, Inc. (www.redhat.com)
   5  *
   6  * This library is free software: you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation.
   9  *
  10  * This library is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  13  * for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public License
  16  * along with this library. If not, see <http://www.gnu.org/licenses/>.
  17  *
  18  */
  19
  20 #if !defined (__LIBEDATASERVER_H_INSIDE__) && !defined (LIBEDATASERVER_COMPILATION)
  21 #error "Only <libedataserver/libedataserver.h> should be included directly."
  22 #endif
  23
  24 #ifndef EDS_DISABLE_DEPRECATED
  25
  26 /* Do not generate bindings. */
  27 #ifndef __GI_SCANNER__
  28
  29 #ifndef E_CREDENTIALS_H
  30 #define E_CREDENTIALS_H
  31
  32 #include <glib.h>
  33
  34 G_BEGIN_DECLS
  35
  36 typedef struct _ECredentials ECredentials;
  37 typedef struct _ECredentialsPrivate ECredentialsPrivate;
  38
  39 /**
  40  * ECredentials:
  41  *
  42  * Contains only private data that should be read and manipulated using the
  43  * functions below.
  44  *
  45  * Since: 3.2
  46  **/
  47 struct _ECredentials {
  48         /*< private >*/
  49         ECredentialsPrivate *priv;
  50 };
  51
  52 /**
  53  * E_CREDENTIALS_KEY_USERNAME:
  54  *
  55  * FIXME Docment me.
  56  *
  57  * Since: 3.2
  58  **/
  59 #define E_CREDENTIALS_KEY_USERNAME      "username"
  60
  61 /**
  62  * E_CREDENTIALS_KEY_PASSWORD:
  63  *
  64  * FIXME Document me.
  65  *
  66  * Since: 3.2
  67  **/
  68 #define E_CREDENTIALS_KEY_PASSWORD      "password"
  69
  70 /**
  71  * E_CREDENTIALS_KEY_AUTH_METHOD:
  72  *
  73  * FIXME Document me.
  74  *
  75  * Since: 3.2
  76  **/
  77 #define E_CREDENTIALS_KEY_AUTH_METHOD   "auth-method"
  78
  79 /**
  80  * E_CREDENTIALS_KEY_PROMPT_TITLE:
  81  *
  82  * FIXME Document me.
  83  *
  84  * Since: 3.2
  85  **/
  86 #define E_CREDENTIALS_KEY_PROMPT_TITLE  "prompt-title"
  87
  88 /**
  89  * E_CREDENTIALS_KEY_PROMPT_TEXT:
  90  *
  91  * FIXME: Document me.
  92  *
  93  * Since: 3.2
  94  **/
  95 #define E_CREDENTIALS_KEY_PROMPT_TEXT   "prompt-text"
  96
  97 /**
  98  * E_CREDENTIALS_KEY_PROMPT_REASON:
  99  *
 100  * FIXME: Document me.
 101  *
 102  * Since: 3.2
 103  **/
 104 #define E_CREDENTIALS_KEY_PROMPT_REASON "prompt-reason"
 105
 106 /**
 107  * E_CREDENTIALS_KEY_PROMPT_KEY:
 108  *
 109  * FIXME: Document me.
 110  *
 111  * Since: 3.2
 112  **/
 113 #define E_CREDENTIALS_KEY_PROMPT_KEY    "prompt-key"
 114
 115 /**
 116  * E_CREDENTIALS_KEY_PROMPT_FLAGS:
 117  *
 118  * FIXME Document me.
 119  *
 120  * Since: 3.2
 121  **/
 122 #define E_CREDENTIALS_KEY_PROMPT_FLAGS  "prompt-flags"
 123
 124 /**
 125  * E_CREDENTIALS_KEY_FOREIGN_REQUEST:
 126  *
 127  * Set to "1" when the ECredentials is used to authenticate
 128  * other than current EClient.
 129  *
 130  * Since: 3.4
 131  **/
 132 #define E_CREDENTIALS_KEY_FOREIGN_REQUEST "foreign-request"
 133
 134 /**
 135  * ECredentialsPromptFlags:
 136  * @E_CREDENTIALS_PROMPT_FLAG_REMEMBER_NEVER: never remember the credentials
 137  * @E_CREDENTIALS_PROMPT_FLAG_REMEMBER_SESSION: remember the credentials only for the current session
 138  * @E_CREDENTIALS_PROMPT_FLAG_REMEMBER_FOREVER: remember the credentials forever
 139  * @E_CREDENTIALS_PROMPT_FLAG_REMEMBER_MASK: a bit-mask of the 'remember' flags
 140  * @E_CREDENTIALS_PROMPT_FLAG_SECRET: whether hide password letters in the UI
 141  * @E_CREDENTIALS_PROMPT_FLAG_REPROMPT: whether this is a re-prompt
 142  * @E_CREDENTIALS_PROMPT_FLAG_ONLINE: only ask if we're online
 143  * @E_CREDENTIALS_PROMPT_FLAG_DISABLE_REMEMBER: disable the 'remember password' checkbox
 144  * @E_CREDENTIALS_PROMPT_FLAG_PASSPHRASE: we are asking a passphrase
 145  *
 146  * Flags for a credentials prompt.
 147  *
 148  * Since: 3.2
 149  **/
 150 /* this is 1:1 with EPasswordsRememberType */
 151 typedef enum {
 152         E_CREDENTIALS_PROMPT_FLAG_REMEMBER_NEVER,
 153         E_CREDENTIALS_PROMPT_FLAG_REMEMBER_SESSION,
 154         E_CREDENTIALS_PROMPT_FLAG_REMEMBER_FOREVER,
 155         E_CREDENTIALS_PROMPT_FLAG_REMEMBER_MASK = 0xf,
 156
 157         E_CREDENTIALS_PROMPT_FLAG_SECRET = 1 << 8, /* whether hide password letters in the UI */
 158         E_CREDENTIALS_PROMPT_FLAG_REPROMPT = 1 << 9, /* automatically set when username and password is provided */
 159         E_CREDENTIALS_PROMPT_FLAG_ONLINE = 1 << 10, /* only ask if we're online */
 160         E_CREDENTIALS_PROMPT_FLAG_DISABLE_REMEMBER = 1 << 11, /* disable the 'remember password' checkbox */
 161         E_CREDENTIALS_PROMPT_FLAG_PASSPHRASE = 1 << 12 /* We are asking a passphrase */
 162 } ECredentialsPromptFlags;
 163
 164 ECredentials *  e_credentials_new       (void);
 165 ECredentials *  e_credentials_new_strv  (const gchar * const *strv);
 166 ECredentials *  e_credentials_new_args  (const gchar *key, ...) G_GNUC_NULL_TERMINATED;
 167 ECredentials *  e_credentials_new_clone (const ECredentials *credentials);
 168 void            e_credentials_free      (      ECredentials *credentials);
 169 gchar **        e_credentials_to_strv   (const ECredentials *credentials);
 170 void            e_credentials_set       (      ECredentials *credentials, const gchar *key, const gchar *value);
 171 gchar *         e_credentials_get       (const ECredentials *credentials, const gchar *key);
 172 const gchar *   e_credentials_peek      (      ECredentials *credentials, const gchar *key);
 173 gboolean        e_credentials_equal     (const ECredentials *credentials1, const ECredentials *credentials2);
 174 gboolean        e_credentials_equal_keys (const ECredentials *credentials1, const ECredentials *credentials2, const gchar *key1, ...) G_GNUC_NULL_TERMINATED;
 175 gboolean        e_credentials_has_key   (const ECredentials *credentials, const gchar *key);
 176 guint           e_credentials_keys_size (const ECredentials *credentials);
 177 GSList *        e_credentials_list_keys (const ECredentials *credentials);
 178 void            e_credentials_clear     (      ECredentials *credentials);
 179 void            e_credentials_clear_peek (      ECredentials *credentials);
 180
 181 void            e_credentials_util_safe_free_string (gchar *str);
 182 gchar *         e_credentials_util_prompt_flags_to_string (guint prompt_flags); /* bit-or of ECredentialsPromptFlags */
 183 guint           e_credentials_util_string_to_prompt_flags (const gchar *prompt_flags_string); /* bit-or of ECredentialsPromptFlags */
 184
 185 G_END_DECLS
 186
 187 #endif /* E_CREDENTIALS_H */
 188
 189 #endif /* __GI_SCANNER__ */
 190
 191 #endif /* EDS_DISABLE_DEPRECATED */