libpurple/e2ee.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  20  */
  21
  22 #ifndef _PURPLE_E2EE_H_
  23 #define _PURPLE_E2EE_H_
  24 /**
  25  * SECTION:e2ee
  26  * @section_id: libpurple-e2ee
  27  * @short_description: <filename>e2ee.h</filename>
  28  * @title: End-to-end Encryption API
  29  */
  30
  31 typedef struct _PurpleE2eeState PurpleE2eeState;
  32
  33 typedef struct _PurpleE2eeProvider PurpleE2eeProvider;
  34
  35 #include <glib.h>
  36 #include "conversation.h"
  37
  38 typedef GList * (*PurpleE2eeConvMenuCallback)(PurpleConversation *conv);
  39
  40 G_BEGIN_DECLS
  41
  42 /**************************************************************************/
  43 /* Encryption states for conversations.                                   */
  44 /**************************************************************************/
  45
  46 /**
  47  * purple_e2ee_state_new:
  48  * @provider: The E2EE provider that created this state.
  49  *
  50  * Creates new E2EE state.
  51  *
  52  * State objects are global (shared between multiple conversations).
  53  *
  54  * Returns: New E2EE state.
  55  */
  56 PurpleE2eeState *
  57 purple_e2ee_state_new(PurpleE2eeProvider *provider);
  58
  59 /**
  60  * purple_e2ee_state_ref:
  61  * @state: The E2EE state.
  62  *
  63  * Increment the reference count.
  64  */
  65 void
  66 purple_e2ee_state_ref(PurpleE2eeState *state);
  67
  68 /**
  69  * purple_e2ee_state_unref:
  70  * @state: The E2EE state.
  71  *
  72  * Decrement the reference count.
  73  *
  74  * If the reference count reaches zero, the state will be freed.
  75  *
  76  * Returns: @state or %NULL if the reference count reached zero.
  77  */
  78 PurpleE2eeState *
  79 purple_e2ee_state_unref(PurpleE2eeState *state);
  80
  81 /**
  82  * purple_e2ee_state_get_provider:
  83  * @state: The E2EE state.
  84  *
  85  * Gets the provider of specified E2EE state.
  86  *
  87  * Returns: The provider for this state.
  88  */
  89 PurpleE2eeProvider *
  90 purple_e2ee_state_get_provider(PurpleE2eeState *state);
  91
  92 /**
  93  * purple_e2ee_state_set_name:
  94  * @state: The E2EE state.
  95  * @name:  The localized name.
  96  *
  97  * Sets the name for the E2EE state.
  98  */
  99 void
 100 purple_e2ee_state_set_name(PurpleE2eeState *state, const gchar *name);
 101
 102 /**
 103  * purple_e2ee_state_get_name:
 104  * @state: The E2EE state.
 105  *
 106  * Gets the name of the E2EE state.
 107  *
 108  * Returns: The localized name.
 109  */
 110 const gchar *
 111 purple_e2ee_state_get_name(PurpleE2eeState *state);
 112
 113 /**
 114  * purple_e2ee_state_set_stock_icon:
 115  * @state:      The E2EE state.
 116  * @stock_icon: The stock icon identifier.
 117  *
 118  * Sets the icon for the E2EE state.
 119  */
 120 void
 121 purple_e2ee_state_set_stock_icon(PurpleE2eeState *state,
 122         const gchar *stock_icon);
 123
 124 /**
 125  * purple_e2ee_state_get_stock_icon:
 126  * @state: The E2EE state.
 127  *
 128  * Gets the icon of the E2EE state.
 129  *
 130  * Returns: The stock icon identifier.
 131  */
 132 const gchar *
 133 purple_e2ee_state_get_stock_icon(PurpleE2eeState *state);
 134
 135
 136 /**************************************************************************/
 137 /* Encryption providers API.                                              */
 138 /**************************************************************************/
 139
 140 /**
 141  * purple_e2ee_provider_new:
 142  *
 143  * Creates new E2EE provider.
 144  *
 145  * Returns: New E2EE provider.
 146  */
 147 PurpleE2eeProvider *
 148 purple_e2ee_provider_new(void);
 149
 150 /**
 151  * purple_e2ee_provider_free:
 152  * @provider: The provider.
 153  *
 154  * Destroys the E2EE provider.
 155  *
 156  * The provider have to be unregistered prior.
 157  */
 158 void
 159 purple_e2ee_provider_free(PurpleE2eeProvider *provider);
 160
 161 /**
 162  * purple_e2ee_provider_register:
 163  * @provider: The E2EE provider.
 164  *
 165  * Registers the E2EE provider.
 166  *
 167  * Currently, there is no support for multiple E2EE providers - only the first
 168  * one is registered.
 169  *
 170  * Returns: %TRUE, if the provider was successfully registered,
 171  *         %FALSE otherwise.
 172  */
 173 gboolean
 174 purple_e2ee_provider_register(PurpleE2eeProvider *provider);
 175
 176 /**
 177  * purple_e2ee_provider_unregister:
 178  * @provider: The E2EE provider.
 179  *
 180  * Unregisters the E2EE provider.
 181  */
 182 void
 183 purple_e2ee_provider_unregister(PurpleE2eeProvider *provider);
 184
 185 /**
 186  * purple_e2ee_provider_get_main:
 187  *
 188  * Gets main E2EE provider.
 189  *
 190  * Returns: The main E2EE provider.
 191  */
 192 PurpleE2eeProvider *
 193 purple_e2ee_provider_get_main(void);
 194
 195 /**
 196  * purple_e2ee_provider_set_name:
 197  * @provider: The E2EE provider.
 198  * @name:     The localized name.
 199  *
 200  * Sets the name for the E2EE provider.
 201  */
 202 void
 203 purple_e2ee_provider_set_name(PurpleE2eeProvider *provider, const gchar *name);
 204
 205 /**
 206  * purple_e2ee_provider_get_name:
 207  * @provider: The E2EE provider.
 208  *
 209  * Gets the name of the E2EE provider.
 210  *
 211  * Returns: The localized name of specified E2EE provider.
 212  */
 213 const gchar *
 214 purple_e2ee_provider_get_name(PurpleE2eeProvider *provider);
 215
 216 /**
 217  * purple_e2ee_provider_set_conv_menu_cb:
 218  * @provider:     The E2EE provider.
 219  * @conv_menu_cb: (scope call): The callback.
 220  *
 221  * Sets the conversation menu callback for the E2EE provider.
 222  *
 223  * The function is called, when user extends the E2EE menu for the conversation
 224  * specified in its parameter.
 225  *
 226  * Function should return the GList of PurpleMenuAction objects.
 227  */
 228 void
 229 purple_e2ee_provider_set_conv_menu_cb(PurpleE2eeProvider *provider,
 230         PurpleE2eeConvMenuCallback conv_menu_cb);
 231
 232 /**
 233  * purple_e2ee_provider_get_conv_menu_cb:
 234  * @provider: The E2EE provider.
 235  *
 236  * Gets the conversation menu callback of the E2EE provider.
 237  *
 238  * Returns: The callback.
 239  */
 240 PurpleE2eeConvMenuCallback
 241 purple_e2ee_provider_get_conv_menu_cb(PurpleE2eeProvider *provider);
 242
 243 /**
 244  * purple_e2ee_provider_get_conv_menu_actions:
 245  * @provider: The E2EE provider.
 246  * @conv: The conversation.
 247  *
 248  * Returns: (element-type PurpleMenuAction) (transfer full): The list of
 249  *          actions for an E2EE menu.
 250  */
 251 GList *
 252 purple_e2ee_provider_get_conv_menu_actions(PurpleE2eeProvider *provider,
 253         PurpleConversation *conv);
 254
 255 G_END_DECLS
 256
 257 #endif /* _PURPLE_E2EE_H_ */