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 without formatting
  71  *
  72  * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
  73  *
  74  * @param level  debug level
  75  * @param msg    debug message "\n" will be automatically appended.
  76  */
  77 void sipe_backend_debug_literal(sipe_debug_level level,
  78                                 const gchar *msg);
  79
  80 /**
  81  * Output debug information
  82  *
  83  * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
  84  *
  85  * @param level  debug level
  86  * @param format format string. "\n" will be automatically appended.
  87  */
  88 void sipe_backend_debug(sipe_debug_level level,
  89                         const gchar *format,
  90                         ...) G_GNUC_PRINTF(2, 3);
  91
  92 /* Convenience macros */
  93 #define SIPE_DEBUG_INFO(fmt, ...)        sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO,    fmt, __VA_ARGS__)
  94 #define SIPE_DEBUG_INFO_NOFORMAT(msg)    sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_INFO,    msg)
  95 #define SIPE_DEBUG_WARNING(fmt, ...)     sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
  96 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_WARNING, msg)
  97 #define SIPE_DEBUG_ERROR(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR,   fmt, __VA_ARGS__)
  98 #define SIPE_DEBUG_ERROR_NOFORMAT(msg)   sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_ERROR,   msg)
  99 #define SIPE_DEBUG_FATAL(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL,   fmt, __VA_ARGS__)
 100 #define SIPE_DEBUG_FATAL_NOFORMAT(msg)   sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_FATAL,   msg)
 101
 102 /**
 103  * Check backend debugging status
 104  *
 105  * @return TRUE if debugging is enabled
 106  */
 107 gboolean sipe_backend_debug_enabled(void);
 108
 109 /** CHAT *********************************************************************/
 110
 111 //void sipe_backend_chat_(struct sipe_backend_session *backend_session, );
 112 void sipe_backend_chat_add(struct sipe_backend_session *backend_session,
 113                            const gchar *uri,
 114                            gboolean is_new);
 115 void sipe_backend_chat_close(struct sipe_backend_session *backend_session);
 116 struct sipe_backend_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
 117                                                       int id,
 118                                                       const gchar *title,
 119                                                       const gchar *nick,
 120                                                       gboolean rejoin);
 121 gboolean sipe_backend_chat_find(struct sipe_backend_session *backend_session,
 122                                 const gchar *uri);
 123 gboolean sipe_backend_chat_is_operator(struct sipe_backend_session *backend_session,
 124                                        const gchar *uri);
 125 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
 126                                int id,
 127                                const gchar *from,
 128                                const gchar *html);
 129 void sipe_backend_chat_operator(struct sipe_backend_session *backend_session,
 130                                 const gchar *uri);
 131 void sipe_backend_chat_rejoin_all(struct sipe_core_public *sipe_public);
 132 void sipe_backend_chat_remove(struct sipe_backend_session *backend_session,
 133                               const gchar *uri);
 134 void sipe_backend_chat_topic(struct sipe_backend_session *backend_session,
 135                               const gchar *topic);
 136
 137 /** CONNECTION ***************************************************************/
 138
 139 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
 140
 141 typedef enum {
 142   SIPE_CONNECTION_ERROR_NETWORK = 0,
 143   SIPE_CONNECTION_ERROR_INVALID_USERNAME,
 144   SIPE_CONNECTION_ERROR_INVALID_SETTINGS,
 145   SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED,
 146   SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE,
 147   SIPE_CONNECTION_ERROR_LAST
 148 } sipe_connection_error;
 149 void sipe_backend_connection_error(struct sipe_core_public *sipe_public,
 150                                    sipe_connection_error error,
 151                                    const gchar *msg);
 152
 153 gboolean sipe_backend_connection_is_disconnecting(struct sipe_core_public *sipe_public);
 154 gboolean sipe_backend_connection_is_valid(struct sipe_core_public *sipe_public);
 155
 156 /** DNS QUERY ****************************************************************/
 157
 158 void sipe_backend_dns_query(struct sipe_core_public *sipe_public,
 159                             const gchar *protocol,
 160                             const gchar *transport,
 161                             const gchar *domain);
 162
 163 /** FILE TRANSFER ************************************************************/
 164 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
 165                            const gchar *errmsg);
 166 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
 167 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
 168
 169 /**
 170  * Try to read up to @c size bytes from file transfer connection
 171  *
 172  * @param backend_ft backend private file transfer data.
 173  * @param data       buffer to read data into.
 174  * @param size       buffer size in bytes.
 175  *
 176  * @return number of bytes read or negative on failure.
 177  *         EAGAIN should return 0 bytes read.
 178  */
 179 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
 180                             guchar *data,
 181                             gsize size);
 182
 183 /**
 184  * Try to write up to @c size bytes to file transfer connection
 185  *
 186  * @param backend_ft backend private file transfer data.
 187  * @param data       data to write
 188  * @param size       buffer size in bytes.
 189  *
 190  * @return number of bytes read or negative on failure.
 191  *         EAGAIN should return 0 bytes written.
 192  */
 193 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
 194                              const guchar *data,
 195                              gsize size);
 196
 197
 198 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
 199 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
 200
 201 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
 202                               struct sipe_file_transfer *ft,
 203                               const gchar *who,
 204                               const gchar *file_name,
 205                               gsize file_size);
 206 gboolean sipe_backend_ft_incoming_accept(struct sipe_file_transfer *ft,
 207                                          const gchar *ip,
 208                                          unsigned short port_min,
 209                                          unsigned short port_max);
 210
 211 /** IM ***********************************************************************/
 212
 213 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
 214                              const gchar *from,
 215                              const gchar *html);
 216
 217 /** MARKUP *******************************************************************/
 218
 219 gchar *sipe_backend_markup_css_property(const gchar *style,
 220                                         const gchar *option);
 221 gchar *sipe_backend_markup_strip_html(const gchar *html);
 222
 223 /** MEDIA ********************************************************************/
 224
 225 typedef enum {
 226         SIPE_CANDIDATE_TYPE_HOST,
 227         SIPE_CANDIDATE_TYPE_RELAY,
 228         SIPE_CANDIDATE_TYPE_SRFLX,
 229         SIPE_CANDIDATE_TYPE_PRFLX
 230 } SipeCandidateType;
 231
 232 typedef enum {
 233         SIPE_COMPONENT_NONE = 0,
 234         SIPE_COMPONENT_RTP  = 1,
 235         SIPE_COMPONENT_RTCP = 2
 236 } SipeComponentType;
 237
 238 typedef enum {
 239         SIPE_MEDIA_AUDIO,
 240         SIPE_MEDIA_VIDEO
 241 } SipeMediaType;
 242
 243 typedef enum {
 244         SIPE_NETWORK_PROTOCOL_TCP,
 245         SIPE_NETWORK_PROTOCOL_UDP
 246 } SipeNetworkProtocol;
 247
 248 struct sipe_media_call;
 249 struct sipe_backend_media;
 250 struct sipe_backend_codec;
 251 struct sipe_backend_candidate;
 252 struct sipe_backend_stream;
 253
 254 struct sipe_media_call {
 255         struct sipe_backend_media *backend_private;
 256
 257         void (*candidates_prepared_cb)(struct sipe_media_call *);
 258         void (*media_connected_cb)();
 259         void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
 260         void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
 261         void (*call_hold_cb)  (struct sipe_media_call *, gboolean local,
 262                                gboolean state);
 263         void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
 264
 265         GList *remote_codecs;
 266         gboolean local_on_hold;
 267         gboolean remote_on_hold;
 268 };
 269
 270 /* Media handling */
 271 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
 272                                                   struct sipe_media_call *call,
 273                                                   const gchar *participant,
 274                                                   gboolean initiator);
 275 void sipe_backend_media_free(struct sipe_backend_media *media);
 276 struct sipe_backend_stream *sipe_backend_media_add_stream(struct sipe_backend_media *media,
 277                                                           const gchar *participant,
 278                                                           SipeMediaType type, gboolean use_nice,
 279                                                           gboolean initiator);
 280 void sipe_backend_media_remove_stream(struct sipe_backend_media *media,
 281                                       struct sipe_backend_stream *stream);
 282 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media *media,
 283                                               struct sipe_backend_stream *stream,
 284                                               GList *candidates);
 285 gboolean sipe_backend_media_is_initiator(struct sipe_backend_media *media,
 286                                          struct sipe_backend_stream *stream);
 287 GList *sipe_backend_media_get_active_local_candidates(struct sipe_backend_media *media,
 288                                                       struct sipe_backend_stream *stream);
 289 GList *sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media *media,
 290                                                        struct sipe_backend_stream *stream);
 291
 292 /* Codec handling */
 293 struct sipe_backend_codec *sipe_backend_codec_new(int id,
 294                                                   const char *name,
 295                                                   SipeMediaType type, guint clock_rate);
 296 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
 297 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
 298 /**
 299  * @return codec name. Will be g_free'd() by the core.
 300  */
 301 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
 302 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
 303 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
 304                                                const gchar *name,
 305                                                const gchar *value);
 306 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
 307 gboolean sipe_backend_set_remote_codecs(struct sipe_media_call *call,
 308                                         struct sipe_backend_stream *stream);
 309 GList* sipe_backend_get_local_codecs(struct sipe_media_call *call,
 310                                      struct sipe_backend_stream *stream);
 311
 312 /* Candidate handling */
 313 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
 314                                                            SipeComponentType component,
 315                                                            SipeCandidateType type,
 316                                                            SipeNetworkProtocol proto,
 317                                                            const gchar *ip, guint port);
 318 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
 319 /**
 320  * @return user name. Will be g_free'd() by the core.
 321  */
 322 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
 323 /**
 324  * @return password. Will be g_free'd() by the core.
 325  */
 326 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
 327 /**
 328  * @return foundation. Will be g_free'd() by the core.
 329  */
 330 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
 331 /**
 332  * @return IP address string. Will be g_free'd() by the core.
 333  */
 334 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
 335 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
 336 /**
 337  * @return IP address string. Will be g_free'd() by the core.
 338  */
 339 gchar *sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate *candidate);
 340 guint sipe_backend_candidate_get_base_port(struct sipe_backend_candidate *candidate);
 341 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
 342 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
 343 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
 344 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
 345 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
 346 void sipe_backend_candidate_set_username_and_pwd(struct sipe_backend_candidate *candidate,
 347                                                  const gchar *username,
 348                                                  const gchar *password);
 349 GList* sipe_backend_get_local_candidates(struct sipe_backend_media *media,
 350                                          struct sipe_backend_stream *stream);
 351 void sipe_backend_media_hold(struct sipe_backend_media *media, gboolean local);
 352 void sipe_backend_media_unhold(struct sipe_backend_media *media, gboolean local);
 353 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
 354 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
 355
 356 /** NETWORK ******************************************************************/
 357
 358 const gchar *sipe_backend_network_ip_address(void);
 359
 360 /** SCHEDULE *****************************************************************/
 361
 362 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
 363                                        guint timeout,
 364                                        gpointer data);
 365 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
 366                                         guint timeout,
 367                                         gpointer data);
 368 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
 369                                   gpointer data);
 370
 371 /** SETTINGS *****************************************************************/
 372
 373 typedef enum {
 374   SIPE_SETTING_EMAIL_URL = 0,
 375   SIPE_SETTING_EMAIL_LOGIN,
 376   SIPE_SETTING_EMAIL_PASSWORD,
 377   SIPE_SETTING_USER_AGENT,
 378   SIPE_SETTING_LAST
 379 } sipe_setting;
 380 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
 381                                   sipe_setting type);
 382
 383 /** TRANSPORT ****************************************************************/
 384
 385 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
 386 typedef void transport_input_cb(struct sipe_transport_connection *conn);
 387 typedef void transport_error_cb(struct sipe_transport_connection *conn,
 388                                 const gchar *msg);
 389
 390 typedef struct {
 391         guint type;
 392         const gchar *server_name;
 393         guint server_port;
 394         gpointer user_data;
 395         transport_connected_cb *connected;
 396         transport_input_cb *input;
 397         transport_error_cb *error;
 398 } sipe_connect_setup;
 399 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
 400                                                                  const sipe_connect_setup *setup);
 401 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
 402 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
 403                                     const gchar *buffer);
 404 void sipe_backend_transport_flush(struct sipe_transport_connection *conn);
 405
 406 /** USER *********************************************************************/
 407
 408 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
 409                                        const gchar *from);
 410 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
 411                                             const gchar *from);
 412
 413 /** NOTIFICATIONS *************************************************************/
 414
 415 void sipe_backend_notify_error(const gchar *title, const gchar *msg);
 416
 417
 418 #ifdef __cplusplus
 419 }
 420 #endif
 421
 422 /*
 423   Local Variables:
 424   mode: c
 425   c-file-style: "bsd"
 426   indent-tabs-mode: t
 427   tab-width: 8
 428   End:
 429 */