src/api/sipe-backend.h

   1 /**
   2  * @file sipe-backend.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010 SIPE Project <http://sipe.sourceforge.net/>
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  */
  22
  23 /**
  24  *
  25  * SIPE Core -> Backend API - functions called by SIPE core code
  26  *
  27  ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
  28  *
  29  *            The SIPE core assumes atomicity and is *NOT* thread-safe.
  30  *
  31  * It *does not* protect any of its data structures or code paths with locks!
  32  *
  33  * In no circumstances it must be possible that a sipe_core_xxx() function can
  34  * be entered through another thread while the first thread has entered the
  35  * backend specific code through a sipe_backend_xxx() function.
  36  *
  37  ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
  38  */
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /* Forward declarations */
  45 struct sipe_backend_session;
  46 struct sipe_core_public;
  47 struct sipe_transport_connection;
  48 struct sipe_file_transfer;
  49 struct sipe_media_call;
  50 struct sipe_media;
  51
  52 /** MISC. STUFF **************************************************************/
  53 /**
  54  * Get the version of the backend suitable for e.g. UserAgent
  55  *
  56  * @return backend version string. Will be g_free()'d.by the core.
  57  */
  58 gchar *sipe_backend_version(void);
  59
  60 /** DEBUGGING ****************************************************************/
  61
  62 typedef enum {
  63         SIPE_DEBUG_LEVEL_INFO,
  64         SIPE_DEBUG_LEVEL_WARNING,
  65         SIPE_DEBUG_LEVEL_ERROR,
  66         SIPE_DEBUG_LEVEL_FATAL,
  67 }  sipe_debug_level;
  68
  69 /**
  70  * Output debug information
  71  *
  72  * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
  73  *
  74  * @param level  debug level
  75  * @param format format string. "\n" will be automatically appended.
  76  */
  77 void sipe_backend_debug(sipe_debug_level level,
  78                         const gchar *format,
  79                         ...) G_GNUC_PRINTF(2, 3);
  80
  81 /* Convenience macros */
  82 #define SIPE_DEBUG_INFO(fmt, ...)        sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO,    fmt, __VA_ARGS__)
  83 #define SIPE_DEBUG_INFO_NOFORMAT(msg)    sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO,    msg)
  84 #define SIPE_DEBUG_WARNING(fmt, ...)     sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
  85 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, msg)
  86 #define SIPE_DEBUG_ERROR(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR,   fmt, __VA_ARGS__)
  87 #define SIPE_DEBUG_ERROR_NOFORMAT(msg)   sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR,   msg)
  88 #define SIPE_DEBUG_FATAL(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL,   fmt, __VA_ARGS__)
  89 #define SIPE_DEBUG_FATAL_NOFORMAT(msg)   sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL,   msg)
  90
  91 /** CHAT *********************************************************************/
  92
  93 //void sipe_backend_chat_(struct sipe_backend_session *backend_session, );
  94 void sipe_backend_chat_add(struct sipe_backend_session *backend_session,
  95                            const gchar *uri,
  96                            gboolean is_new);
  97 void sipe_backend_chat_close(struct sipe_backend_session *backend_session);
  98 struct sipe_backend_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
  99                                                       int id,
 100                                                       const gchar *title,
 101                                                       const gchar *nick,
 102                                                       gboolean rejoin);
 103 gboolean sipe_backend_chat_find(struct sipe_backend_session *backend_session,
 104                                 const gchar *uri);
 105 gboolean sipe_backend_chat_is_operator(struct sipe_backend_session *backend_session,
 106                                        const gchar *uri);
 107 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
 108                                int id,
 109                                const gchar *from,
 110                                const gchar *html);
 111 void sipe_backend_chat_operator(struct sipe_backend_session *backend_session,
 112                                 const gchar *uri);
 113 void sipe_backend_chat_rejoin_all(struct sipe_core_public *sipe_public);
 114 void sipe_backend_chat_remove(struct sipe_backend_session *backend_session,
 115                               const gchar *uri);
 116 void sipe_backend_chat_topic(struct sipe_backend_session *backend_session,
 117                               const gchar *topic);
 118
 119 /** CONNECTION ***************************************************************/
 120
 121 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
 122
 123 typedef enum {
 124   SIPE_CONNECTION_ERROR_NETWORK = 0,
 125   SIPE_CONNECTION_ERROR_INVALID_USERNAME,
 126   SIPE_CONNECTION_ERROR_INVALID_SETTINGS,
 127   SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED,
 128   SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE,
 129   SIPE_CONNECTION_ERROR_LAST
 130 } sipe_connection_error;
 131 void sipe_backend_connection_error(struct sipe_core_public *sipe_public,
 132                                    sipe_connection_error error,
 133                                    const gchar *msg);
 134
 135 gboolean sipe_backend_connection_is_disconnecting(struct sipe_core_public *sipe_public);
 136
 137 /** DNS QUERY ****************************************************************/
 138
 139 void sipe_backend_dns_query(struct sipe_core_public *sipe_public,
 140                             const gchar *protocol,
 141                             const gchar *transport,
 142                             const gchar *domain);
 143
 144 /** FILE TRANSFER ************************************************************/
 145 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
 146                            const gchar *errmsg);
 147 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
 148 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
 149
 150 /**
 151  * Try to read up to @c size bytes from file transfer connection
 152  *
 153  * @param backend_ft backend private file transfer data.
 154  * @param data       buffer to read data into.
 155  * @param size       buffer size in bytes.
 156  *
 157  * @return number of bytes read or negative on failure.
 158  *         EAGAIN should return 0 bytes read.
 159  */
 160 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
 161                             guchar *data,
 162                             gsize size);
 163
 164 /**
 165  * Try to write up to @c size bytes to file transfer connection
 166  *
 167  * @param backend_ft backend private file transfer data.
 168  * @param data       data to write
 169  * @param size       buffer size in bytes.
 170  *
 171  * @return number of bytes read or negative on failure.
 172  *         EAGAIN should return 0 bytes written.
 173  */
 174 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
 175                              const guchar *data,
 176                              gsize size);
 177
 178
 179 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
 180 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
 181
 182 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
 183                               struct sipe_file_transfer *ft,
 184                               const gchar *who,
 185                               const gchar *file_name,
 186                               gsize file_size);
 187 gboolean sipe_backend_ft_incoming_accept(struct sipe_file_transfer *ft,
 188                                          const gchar *ip,
 189                                          unsigned short port_min,
 190                                          unsigned short port_max);
 191
 192 /** IM ***********************************************************************/
 193
 194 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
 195                              const gchar *from,
 196                              const gchar *html);
 197
 198 /** MARKUP *******************************************************************/
 199
 200 gchar *sipe_backend_markup_css_property(const gchar *style,
 201                                         const gchar *option);
 202 gchar *sipe_backend_markup_strip_html(const gchar *html);
 203
 204 /** MEDIA ********************************************************************/
 205
 206 typedef enum {
 207         SIPE_CANDIDATE_TYPE_HOST,
 208         SIPE_CANDIDATE_TYPE_RELAY,
 209         SIPE_CANDIDATE_TYPE_SRFLX,
 210         SIPE_CANDIDATE_TYPE_PRFLX
 211 } SipeCandidateType;
 212
 213 typedef enum {
 214         SIPE_COMPONENT_NONE = 0,
 215         SIPE_COMPONENT_RTP  = 1,
 216         SIPE_COMPONENT_RTCP = 2
 217 } SipeComponentType;
 218
 219 typedef enum {
 220         SIPE_MEDIA_AUDIO,
 221         SIPE_MEDIA_VIDEO
 222 } SipeMediaType;
 223
 224 typedef enum {
 225         SIPE_NETWORK_PROTOCOL_TCP,
 226         SIPE_NETWORK_PROTOCOL_UDP
 227 } SipeNetworkProtocol;
 228
 229 struct sipe_media_call;
 230 struct sipe_backend_media;
 231 struct sipe_backend_codec;
 232 struct sipe_backend_candidate;
 233
 234 struct sipe_media_call {
 235         struct sipe_backend_media *backend_private;
 236
 237         void (*candidates_prepared_cb)(struct sipe_media_call *);
 238         void (*media_connected_cb)();
 239         void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
 240         void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
 241         void (*call_hold_cb)  (struct sipe_media_call *, gboolean local,
 242                                gboolean state);
 243         void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
 244
 245         GList *remote_codecs;
 246         gboolean local_on_hold;
 247         gboolean remote_on_hold;
 248 };
 249
 250 /* Media handling */
 251 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
 252                                                   struct sipe_media_call *call,
 253                                                   const gchar *participant,
 254                                                   gboolean initiator);
 255 gboolean sipe_backend_media_add_stream(struct sipe_backend_media *media,
 256                                        const gchar *participant,
 257                                        SipeMediaType type, gboolean use_nice,
 258                                        gboolean initiator);
 259 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media *media,
 260                                               gchar *participant,
 261                                               GList *candidates);
 262 gboolean sipe_backend_media_is_initiator(struct sipe_backend_media *media,
 263                                          gchar *participant);
 264 GList *sipe_backend_media_get_active_local_candidates(struct sipe_backend_media *media,
 265                                         gchar *participant);
 266 GList *sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media *media,
 267                                         gchar *participant);
 268
 269 /* Codec handling */
 270 struct sipe_backend_codec *sipe_backend_codec_new(int id,
 271                                    const char *name,
 272                                    SipeMediaType type, guint clock_rate);
 273 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
 274 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
 275 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
 276 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
 277 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
 278                                                const gchar *name,
 279                                                const gchar *value);
 280 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
 281 gboolean sipe_backend_set_remote_codecs(struct sipe_media_call *call, gchar *participant);
 282 GList* sipe_backend_get_local_codecs(struct sipe_media_call *call);
 283
 284 /* Candidate handling */
 285 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
 286                                             SipeComponentType component,
 287                                             SipeCandidateType type,
 288                                             SipeNetworkProtocol proto,
 289                                             const gchar *ip, guint port);
 290 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
 291 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
 292 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
 293 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
 294 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
 295 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
 296 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
 297 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
 298 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
 299 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
 300 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
 301 void sipe_backend_candidate_set_username_and_pwd(struct sipe_backend_candidate *candidate,
 302                                                  const gchar *username,
 303                                                  const gchar *password);
 304 GList* sipe_backend_get_local_candidates(struct sipe_backend_media *media,
 305                                          gchar *participant);
 306 void sipe_backend_media_hold(struct sipe_backend_media *call, gboolean local);
 307 void sipe_backend_media_unhold(struct sipe_backend_media *call, gboolean local);
 308 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
 309 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
 310
 311 /** NETWORK ******************************************************************/
 312
 313 const gchar *sipe_backend_network_ip_address(void);
 314
 315 /** SCHEDULE *****************************************************************/
 316
 317 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
 318                                        guint timeout,
 319                                        gpointer data);
 320 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
 321                                         guint timeout,
 322                                         gpointer data);
 323 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
 324                                   gpointer data);
 325
 326 /** SETTINGS *****************************************************************/
 327
 328 typedef enum {
 329   SIPE_SETTING_EMAIL_URL = 0,
 330   SIPE_SETTING_EMAIL_LOGIN,
 331   SIPE_SETTING_EMAIL_PASSWORD,
 332   SIPE_SETTING_USER_AGENT,
 333   SIPE_SETTING_LAST
 334 } sipe_setting;
 335 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
 336                                   sipe_setting type);
 337
 338 /** TRANSPORT ****************************************************************/
 339
 340 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
 341 typedef void transport_input_cb(struct sipe_transport_connection *conn);
 342 typedef void transport_error_cb(struct sipe_transport_connection *conn,
 343                                 const gchar *msg);
 344
 345 typedef struct {
 346         guint type;
 347         const gchar *server_name;
 348         guint server_port;
 349         gpointer user_data;
 350         transport_connected_cb *connected;
 351         transport_input_cb *input;
 352         transport_error_cb *error;
 353 } sipe_connect_setup;
 354 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
 355                                                                  const sipe_connect_setup *setup);
 356 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
 357 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
 358                                     const gchar *buffer);
 359
 360 /** USER *********************************************************************/
 361
 362 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
 363                                        const gchar *from);
 364 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
 365                                             const gchar *from);
 366
 367 #ifdef __cplusplus
 368 }
 369 #endif
 370
 371 /*
 372   Local Variables:
 373   mode: c
 374   c-file-style: "bsd"
 375   indent-tabs-mode: t
 376   tab-width: 8
 377   End:
 378 */