git.maemo.org Git - yandexfotkisp/blob - src/libsharing/sharing-plugin-interface.h

   1 /*
   2  * This file is part of Sharing Application Library
   3  *
   4  * Copyright (C) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
   5  *
   6  * Contact: Alexander Bokovoy <alexander.bokovoy@nokia.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public License
  10  * version 2.1 as published by the Free Software Foundation.
  11  *
  12  * This library is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  20  * 02110-1301 USA
  21  *
  22  */
  23
  24 /**
  25  * SECTION:sharing-plugin-interface
  26  * @short_description: Sharing plugin interface defines the plugin gmodule
  27  * interface.
  28  *
  29  * #SharingPluginInterface defines the interface that Sharing framework uses
  30  * when calling the plugin.
  31  */
  32
  33 #ifndef _SHARING_PLUGIN_INTERFACE_H_
  34 #define _SHARING_PLUGIN_INTERFACE_H_
  35
  36 #include <gtk/gtk.h>
  37 #include <libosso.h>
  38 #include <conicconnection.h>
  39 #include "sharing-account.h"
  40 #include "sharing-transfer.h"
  41
  42 G_BEGIN_DECLS
  43
  44 /**
  45  * SharingTransferStatus:
  46  * @SHARING_SEND_SUCCESS: Send succesfully done.
  47  * @SHARING_SEND_ERROR_UNKNOWN: Cannot proceed.
  48  * @SHARING_SEND_ERROR_AUTH: Authentication failed. Account has to be edited.
  49  * @SHARING_SEND_ERROR_CONNECTION: Connection (wifi/bt/etc.) lacking.
  50  * @SHARING_SEND_CANCELLED: Task cancel noticed and returned.
  51  * @SHARING_SEND_ERROR_FILE_FORMAT: File format not supported by service.
  52  * @SHARING_SEND_ERROR_UPLOAD_LIMIT: Service upload limit exceeded.
  53  * @SHARING_SEND_ERROR_ACCOUNT_NOT_FOUND: Account not found.
  54  * @SHARING_SEND_ERROR_TIMEOUT: HTTP timeouts etc.
  55  */
  56 typedef enum {
  57     SHARING_SEND_SUCCESS = 0,
  58     SHARING_SEND_ERROR_UNKNOWN = 1,
  59     SHARING_SEND_ERROR_AUTH = 2,
  60     SHARING_SEND_ERROR_CONNECTION = 3,
  61     SHARING_SEND_CANCELLED = 4,
  62     SHARING_SEND_ERROR_FILE_FORMAT = 5,
  63     SHARING_SEND_ERROR_UPLOAD_LIMIT = 6,
  64     SHARING_SEND_ERROR_ACCOUNT_NOT_FOUND = 7,
  65     SHARING_SEND_ERROR_TIMEOUT = 8
  66 } SharingPluginInterfaceSendResult;
  67
  68 /**
  69  * SharingPluginInterfaceAccountSetupResult:
  70  * @SHARING_ACCOUNT_SETUP_SUCCESS: Setup flow succesfully done.
  71  * @SHARING_ACCOUNT_SETUP_ERROR_UNKNOWN: General failure.
  72  * @SHARING_ACCOUNT_SETUP_ERROR_CONNECTION: Connection & connection timeout
  73  * error.
  74  */
  75 typedef enum {
  76     SHARING_ACCOUNT_SETUP_SUCCESS = 0,
  77     SHARING_ACCOUNT_SETUP_ERROR_UNKNOWN = 1,
  78     SHARING_ACCOUNT_SETUP_ERROR_CONNECTION = 2
  79 } SharingPluginInterfaceAccountSetupResult;
  80
  81 /**
  82  * SharingPluginInterfaceAccountValidateResult:
  83  * @SHARING_ACCOUNT_VALIDATE_SUCCESS: Setup flow succesfully done.
  84  * @SHARING_ACCOUNT_VALIDATE_ACCOUNT_NOT_FOUND: Account data could not be
  85  * loaded.
  86  * @SHARING_ACCOUNT_VALIDATE_FAILED: Account information invalid.
  87  * @SHARING_ACCOUNT_VALIDATE_ERROR_UNKNOWN: General error.
  88  * @SHARING_ACCOUNT_VALIDATE_ERROR_CONNECTION: Connection & connection timeout
  89  * @SHARING_ACCOUNT_VALIDATE_NOT_STARTED: Validation process not started.
  90  * @SHARING_ACCOUNT_VALIDATE_CANCELLED: Returned when dialog is validating
  91  * dialog is closed by user.
  92  */
  93 typedef enum {
  94     SHARING_ACCOUNT_VALIDATE_SUCCESS = 0,
  95     SHARING_ACCOUNT_VALIDATE_ACCOUNT_NOT_FOUND = 1,
  96     SHARING_ACCOUNT_VALIDATE_FAILED = 2,
  97     SHARING_ACCOUNT_VALIDATE_ERROR_UNKNOWN = 3,
  98     SHARING_ACCOUNT_VALIDATE_ERROR_CONNECTION = 4,
  99     SHARING_ACCOUNT_VALIDATE_NOT_STARTED = 5,
 100     SHARING_ACCOUNT_VALIDATE_CANCELLED = 6
 101 } SharingPluginInterfaceAccountValidateResult;
 102
 103 /**
 104  * SharingPluginInterfaceEditAccountResult:
 105  * @SHARING_EDIT_ACCOUNT_SUCCESS: Editing succesfully done.
 106  * @SHARING_EDIT_ACCOUNT_ERROR_UNKNOWN: General error.
 107  * @SHARING_EDIT_ACCOUNT_ERROR_CONNECTION: Connection & connection timeout.
 108  * @SHARING_EDIT_ACCOUNT_NOT_STARTED: Editing process not started.
 109  * @SHARING_EDIT_ACCOUNT_DELETE: Account is wanted to be deleted.
 110  * @SHARING_EDIT_ACCOUNT_CANCELLED: Editing cancelled.
 111  */
 112 typedef enum {
 113     SHARING_EDIT_ACCOUNT_SUCCESS = 0,
 114     SHARING_EDIT_ACCOUNT_ERROR_UNKNOWN = 1,
 115     SHARING_EDIT_ACCOUNT_ERROR_CONNECTION = 2,
 116     SHARING_EDIT_ACCOUNT_NOT_STARTED = 3,
 117     SHARING_EDIT_ACCOUNT_DELETE = 4,
 118     SHARING_EDIT_ACCOUNT_CANCELLED = 5
 119 } SharingPluginInterfaceEditAccountResult;
 120
 121 /**
 122  * SharingPluginInterfaceUpdateOptionsResult:
 123  * @SHARING_UPDATE_OPTIONS_SUCCESS: Updating succesfully done.
 124  * @SHARING_UPDATE_OPTIONS_ERROR_UNKNOWN: General error.
 125  * @SHARING_UPDATE_OPTIONS_CANCELLED: Updating cancelled.
 126  * @SHARING_UPDATE_OPTIONS_NO_UPDATE_FUNCTIONALITY: Does not support update.
 127  * @SHARING_UPDATE_OPTIONS_ERROR_PARAMETERS: Parameters invalid.
 128  */
 129 typedef enum {
 130     SHARING_UPDATE_OPTIONS_SUCCESS = 0,
 131     SHARING_UPDATE_OPTIONS_ERROR_UNKNOWN = 1,
 132     SHARING_UPDATE_OPTIONS_CANCELLED = 2,
 133     SHARING_UPDATE_OPTIONS_NO_UPDATE_FUNCTIONALITY = 3,
 134     SHARING_UPDATE_OPTIONS_ERROR_PARAMETERS = 4
 135 } SharingPluginInterfaceUpdateOptionsResult;
 136
 137 /**
 138  * Plugin interface function binary API.
 139  */
 140 #define SHARING_PLUGIN_INTERFACE_INIT \
 141     "sharing_plugin_interface_init"
 142 #define SHARING_PLUGIN_INTERFACE_UNINIT \
 143     "sharing_plugin_interface_uninit"
 144 #define SHARING_PLUGIN_INTERFACE_SEND \
 145     "sharing_plugin_interface_send"
 146 #define SHARING_PLUGIN_INTERFACE_ACCOUNT_SETUP \
 147     "sharing_plugin_interface_account_setup"
 148 #define SHARING_PLUGIN_INTERFACE_ACCOUNT_VALIDATE \
 149     "sharing_plugin_interface_account_validate"
 150 #define SHARING_PLUGIN_INTERFACE_EDIT_ACCOUNT \
 151     "sharing_plugin_interface_edit_account"
 152 #define SHARING_PLUGIN_INTERFACE_UPDATE_OPTIONS \
 153     "sharing_plugin_interface_update_options"
 154
 155 /**
 156  * SharingPluginInterfaceInit:
 157  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 158  * at least every 30 seconds.
 159  *
 160  * Sharing Service Plugin Interface function for plugin init. This
 161  * function must be implemented in Sharing Plugins. Function
 162  * is called straight after plugin is loaded.
 163  *
 164  * Returns: Plugin should return 0 if initialization was successful else 1.
 165  */
 166 typedef guint (*SharingPluginInterfaceInit)(
 167     gboolean* dead_mans_switch);
 168
 169 /**
 170  * SharingPluginInterfaceUninit:
 171  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 172  * at least every 30 seconds.
 173  *
 174  * Sharing Service Plugin Interface function for SharingEntry sending. This
 175  * function must be implemented in Sharing Plugins. Function
 176  * is called before plugin is unloaded.
 177  *
 178  * Returns: Plugin should return 0 if uninitialization was successful else 1.
 179  */
 180 typedef guint (*SharingPluginInterfaceUninit)(
 181     gboolean* dead_mans_switch);
 182
 183 /**
 184  * SharingPluginInterfaceSend:
 185  * @SharingTransfer: Transfer to be send.
 186  * @con: ConIc connection.
 187  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 188  * as many times as possible. Do NOT use any GTK idle / timeout function
 189  * or any other separate to do this!
 190  *
 191  * Sharing Service Plugin Interface function for #SharingTransfer sending. This
 192  * function must be implemented in Sharing Plugins.
 193  *
 194  * Returns: Plugin should return most fitting
 195  *     #SharingPluginInterfaceSendResult value.
 196  */
 197 typedef SharingPluginInterfaceSendResult (*SharingPluginInterfaceSend)(
 198     SharingTransfer* transfer, ConIcConnection* con,
 199     gboolean* dead_mans_switch);
 200
 201 /**
 202  * SharingPluginInterfaceAccountSetup:
 203  * @parent: Parent window.
 204  * @service: Service information.
 205  * @worked_on: If account is already created in account manager flow
 206  *         it is given as parameter here. Otherwise %NULL value given.
 207  * @osso: osso_context_t to be used for the Dialog.
 208  *
 209  * Sharing Service Plugin Interface function for #SharingAccount
 210  * setup.
 211  *
 212  * Returns: Plugin should return most fitting
 213  *     #SharingPluginInterfaceAccountSetupResult value.
 214  */
 215 typedef SharingPluginInterfaceAccountSetupResult (*SharingPluginInterfaceAccountSetup)(
 216     GtkWindow* parent, SharingService* service,
 217     SharingAccount** worked_on, osso_context_t* osso);
 218
 219 /**
 220  * SharingPluginInterfaceAccountValidate:
 221  * @account: Account to be validated.
 222  * @con: ConIc connection.
 223  * @cont: %TRUE in common. %FALSE if validation dialog is cancelled, end your
 224  *     validation flow in this case.
 225  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 226  * at least every 30 seconds.
 227  *
 228  * Sharing Service Plugin Interface function for validating #SharingAccount.
 229  * This function must be implemented in Sharing Plugins.
 230  *
 231  * Returns: Plugin should return most fitting
 232  *     #SharingPluginInterfaceAccountValidateResult value.
 233  */
 234 typedef SharingPluginInterfaceAccountValidateResult (*SharingPluginInterfaceAccountValidate)(
 235     SharingAccount* account, ConIcConnection* con,
 236     gboolean *cont, gboolean* dead_mans_switch);
 237
 238 /**
 239  * SharingPluginInterfaceEditAccount:
 240  * @parent: Parent window.
 241  * @account: Account to be edited.
 242  * @con: ConIc connection.
 243  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 244  * at least every 30 seconds.
 245  *
 246  * Sharing Service Plugin Interface function to edit #SharingAccount. This
 247  * function must be implemented in Sharing Plugins.
 248  *
 249  * Returns: Plugin should return most fitting
 250  *     #SharingPluginInterfaceEditAccountResult value.
 251  */
 252 typedef SharingPluginInterfaceEditAccountResult (*SharingPluginInterfaceEditAccount)(
 253     GtkWindow* parent, SharingAccount* account,
 254     ConIcConnection* con, gboolean* dead_mans_switch);
 255
 256 /**
 257  * UpdateOptionsCallback:
 258  * @result: Result of plug-in's flow.
 259  * @cb_data: Callback function data got before.
 260  *
 261  * Update options flow done callback at SharingPluginInterfaceUpdateOptions
 262  * as parameter.
 263  */
 264 typedef void (*UpdateOptionsCallback) (
 265     SharingPluginInterfaceUpdateOptionsResult result, gpointer cb_data);
 266
 267 /**
 268  * SharingPluginInterfaceUpdateOptions:
 269  * @account: #SharingAccount that will have the updated options.
 270  * @con: ConIcConnection* con.
 271  * @dead_mans_switch: While in function this switch should be turned to %FALSE
 272  * at least every 30 seconds.
 273  * @cb_func: Callback function called when update flow ends.
 274  * @cb_data: Callback function cb_data.
 275  *
 276  * Updates options (albums) set to account.
 277  *
 278  * Returns: #TRUE if start was OK, #FALSE otherwise. Callback is be called
 279  * in #TRUE case only!
 280  */
 281 typedef gboolean (*SharingPluginInterfaceUpdateOptions)(
 282         SharingAccount* account, ConIcConnection* con, gboolean* cont,
 283         gboolean* dead_mans_switch, UpdateOptionsCallback cb_func,
 284         gpointer cb_data);
 285
 286 G_END_DECLS
 287
 288 #endif /* _SHARING_PLUGIN_INTERFACE_H_ */