src/api/sipe-backend.h

   1 /**
   2  * @file sipe-backend.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010-2016 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_chat_session;
  46 struct sipe_chat_session;
  47 struct sipe_core_public;
  48 struct sipe_transport_connection;
  49 struct sipe_file_transfer;
  50 struct sipe_media_call;
  51 struct sipe_media;
  52
  53 /** MISC. STUFF **************************************************************/
  54 /**
  55  * Get the version of the backend suitable for e.g. UserAgent
  56  *
  57  * @return backend version string. Will be g_free()'d.by the core.
  58  */
  59 gchar *sipe_backend_version(void);
  60
  61 /** DEBUGGING ****************************************************************/
  62
  63 typedef enum {
  64         SIPE_DEBUG_LEVEL_INFO,
  65         SIPE_DEBUG_LEVEL_WARNING,
  66         SIPE_DEBUG_LEVEL_ERROR,
  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
 100 /**
 101  * Check backend debugging status
 102  *
 103  * @return TRUE if debugging is enabled
 104  */
 105 gboolean sipe_backend_debug_enabled(void);
 106
 107 /** CHAT *********************************************************************/
 108
 109 void sipe_backend_chat_session_destroy(struct sipe_backend_chat_session *session);
 110 void sipe_backend_chat_add(struct sipe_backend_chat_session *backend_session,
 111                            const gchar *uri,
 112                            gboolean is_new);
 113 void sipe_backend_chat_close(struct sipe_backend_chat_session *backend_session);
 114
 115 /**
 116  * Joined a new chat
 117  */
 118 struct sipe_backend_chat_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
 119                                                            struct sipe_chat_session *session,
 120                                                            const gchar *title,
 121                                                            const gchar *nick);
 122 gboolean sipe_backend_chat_find(struct sipe_backend_chat_session *backend_session,
 123                                 const gchar *uri);
 124 gboolean sipe_backend_chat_is_operator(struct sipe_backend_chat_session *backend_session,
 125                                        const gchar *uri);
 126 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
 127                                struct sipe_backend_chat_session *backend_session,
 128                                const gchar *from,
 129                                time_t when,
 130                                const gchar *html);
 131 void sipe_backend_chat_operator(struct sipe_backend_chat_session *backend_session,
 132                                 const gchar *uri);
 133
 134 /**
 135  * Rejoin an existing chat window after connection re-establishment
 136  */
 137 void sipe_backend_chat_rejoin(struct sipe_core_public *sipe_public,
 138                               struct sipe_backend_chat_session *backend_session,
 139                               const gchar *nick,
 140                               const gchar *title);
 141
 142 /**
 143  * Core has completed connection re-establishment.
 144  * Should call sipe_core_chat_rejoin() for existing chats.
 145  */
 146 void sipe_backend_chat_rejoin_all(struct sipe_core_public *sipe_public);
 147 void sipe_backend_chat_remove(struct sipe_backend_chat_session *backend_session,
 148                               const gchar *uri);
 149
 150 /**
 151  * Move chat window to the front. Will be called when
 152  * a user tries to join an already joined chat again.
 153  */
 154 void sipe_backend_chat_show(struct sipe_backend_chat_session *backend_session);
 155 void sipe_backend_chat_topic(struct sipe_backend_chat_session *backend_session,
 156                              const gchar *topic);
 157
 158 /** CONNECTION ***************************************************************/
 159
 160 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
 161
 162 typedef enum {
 163   SIPE_CONNECTION_ERROR_NETWORK = 0,
 164   SIPE_CONNECTION_ERROR_INVALID_USERNAME,
 165   SIPE_CONNECTION_ERROR_INVALID_SETTINGS,
 166   SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED,
 167   SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE,
 168   SIPE_CONNECTION_ERROR_LAST
 169 } sipe_connection_error;
 170 void sipe_backend_connection_error(struct sipe_core_public *sipe_public,
 171                                    sipe_connection_error error,
 172                                    const gchar *msg);
 173
 174 gboolean sipe_backend_connection_is_disconnecting(struct sipe_core_public *sipe_public);
 175 gboolean sipe_backend_connection_is_valid(struct sipe_core_public *sipe_public);
 176
 177 /** DNS QUERY ****************************************************************/
 178
 179 typedef void (*sipe_dns_resolved_cb)(gpointer data, const gchar *hostname, guint port);
 180
 181 struct sipe_dns_query *sipe_backend_dns_query_srv(struct sipe_core_public *sipe_public,
 182                                                   const gchar *protocol,
 183                                                   const gchar *transport,
 184                                                   const gchar *domain,
 185                                                   sipe_dns_resolved_cb callback,
 186                                                   gpointer data);
 187
 188 struct sipe_dns_query *sipe_backend_dns_query_a(struct sipe_core_public *sipe_public,
 189                                                 const gchar *hostname,
 190                                                 guint port,
 191                                                 sipe_dns_resolved_cb callback,
 192                                                 gpointer data);
 193
 194 void sipe_backend_dns_query_cancel(struct sipe_dns_query *query);
 195
 196 /** FILE TRANSFER ************************************************************/
 197
 198 struct sipe_backend_fd;
 199
 200 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
 201                            const gchar *errmsg);
 202 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
 203 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
 204
 205 /**
 206  * Try to read up to @c size bytes from file transfer connection
 207  *
 208  * @param ft   file transfer data.
 209  * @param data buffer to read data into.
 210  * @param size buffer size in bytes.
 211  *
 212  * @return number of bytes read or negative on failure.
 213  *         EAGAIN should return 0 bytes read.
 214  */
 215 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
 216                             guchar *data,
 217                             gsize size);
 218
 219 /**
 220  * Try to write up to @c size bytes to file transfer connection
 221  *
 222  * @param ft   file transfer data.
 223  * @param data data to write
 224  * @param size buffer size in bytes.
 225  *
 226  * @return number of bytes read or negative on failure.
 227  *         EAGAIN should return 0 bytes written.
 228  */
 229 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
 230                              const guchar *data,
 231                              gsize size);
 232
 233 void sipe_backend_ft_set_completed(struct sipe_file_transfer *ft);
 234
 235 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
 236 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
 237
 238 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
 239                               struct sipe_file_transfer *ft,
 240                               const gchar *who,
 241                               const gchar *file_name,
 242                               gsize file_size);
 243 /**
 244  * Allocates and initializes backend file transfer structure for sending a file.
 245  *
 246  * @param sipe_public (in) the handle representing the protocol instance
 247  * @param ft (in) sipe core file transfer structure
 248  * @param who (in) SIP URI of the file recipient
 249  * @param file_name (in) filesystem path of the file being sent
 250  */
 251 void sipe_backend_ft_outgoing(struct sipe_core_public *sipe_public,
 252                               struct sipe_file_transfer *ft,
 253                               const gchar *who,
 254                               const gchar *file_name);
 255 /**
 256  * Begins file transfer with remote peer.
 257  *
 258  * You can provide either opened file descriptor to use for read/write operations
 259  * or ip address and port where the backend should connect.
 260  *
 261  * @param ft   file transfer data
 262  * @param fd   opaque file descriptor pointer or NULL if ip and port are used
 263  * @param ip   ip address to connect of NULL when file descriptor is used
 264  * @param port port to connect or 0 when file descriptor is used
 265  */
 266 void sipe_backend_ft_start(struct sipe_file_transfer *ft,
 267                            struct sipe_backend_fd *fd,
 268                            const char* ip, unsigned port);
 269
 270 /**
 271  * Check whether file transfer is incoming or outgoing
 272  *
 273  * @param ft file transfer data
 274  * @return @c TRUE if @c ft is incoming, otherwise @c FALSE
 275  */
 276 gboolean sipe_backend_ft_is_incoming(struct sipe_file_transfer *ft);
 277
 278 /** GROUP CHAT ***************************************************************/
 279
 280 #define SIPE_GROUPCHAT_ROOM_FILEPOST 0x00000001
 281 #define SIPE_GROUPCHAT_ROOM_INVITE   0x00000002
 282 #define SIPE_GROUPCHAT_ROOM_LOGGED   0x00000004
 283 #define SIPE_GROUPCHAT_ROOM_PRIVATE  0x00000008
 284
 285 /**
 286  * Add a room found through room query
 287  *
 288  * @param uri         room URI
 289  * @param name        human readable name for room
 290  * @param description room description
 291  * @param users       number of users in the room
 292  * @param flags       SIPE_GROUPCHAT_ROOM_* flags
 293  */
 294 void sipe_backend_groupchat_room_add(struct sipe_core_public *sipe_public,
 295                                      const gchar *uri,
 296                                      const gchar *name,
 297                                      const gchar *description,
 298                                      guint users,
 299                                      guint32 flags);
 300
 301 /**
 302  * Terminate room query
 303  */
 304 void sipe_backend_groupchat_room_terminate(struct sipe_core_public *sipe_public);
 305
 306 /** IM ***********************************************************************/
 307
 308 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
 309                              const gchar *from,
 310                              const gchar *html);
 311 void sipe_backend_im_topic(struct sipe_core_public *sipe_public,
 312                            const gchar *with,
 313                            const gchar *topic);
 314
 315 /** MARKUP *******************************************************************/
 316
 317 gchar *sipe_backend_markup_css_property(const gchar *style,
 318                                         const gchar *option);
 319 gchar *sipe_backend_markup_strip_html(const gchar *html);
 320
 321 /** MEDIA ********************************************************************/
 322
 323 typedef enum {
 324         /* This client is the one who invites other participant to the call. */
 325         SIPE_MEDIA_CALL_INITIATOR = 1,
 326         /* Don't show any user interface elements for the call. */
 327         SIPE_MEDIA_CALL_NO_UI = 2
 328 } SipeMediaCallFlags;
 329
 330 typedef enum {
 331         SIPE_ICE_NO_ICE,
 332         SIPE_ICE_DRAFT_6,
 333         SIPE_ICE_RFC_5245
 334 } SipeIceVersion;
 335
 336 typedef enum {
 337         SIPE_CANDIDATE_TYPE_ANY,
 338         SIPE_CANDIDATE_TYPE_HOST,
 339         SIPE_CANDIDATE_TYPE_RELAY,
 340         SIPE_CANDIDATE_TYPE_SRFLX,
 341         SIPE_CANDIDATE_TYPE_PRFLX
 342 } SipeCandidateType;
 343
 344 typedef enum {
 345         SIPE_COMPONENT_NONE = 0,
 346         SIPE_COMPONENT_RTP  = 1,
 347         SIPE_COMPONENT_RTCP = 2
 348 } SipeComponentType;
 349
 350 typedef enum {
 351         SIPE_MEDIA_AUDIO,
 352         SIPE_MEDIA_VIDEO,
 353         SIPE_MEDIA_APPLICATION
 354 } SipeMediaType;
 355
 356 typedef enum {
 357         SIPE_NETWORK_PROTOCOL_UDP,
 358         SIPE_NETWORK_PROTOCOL_TCP_ACTIVE,
 359         SIPE_NETWORK_PROTOCOL_TCP_PASSIVE,
 360         SIPE_NETWORK_PROTOCOL_TCP_SO,
 361 } SipeNetworkProtocol;
 362
 363 typedef enum {
 364         SIPE_ENCRYPTION_POLICY_REJECTED,
 365         SIPE_ENCRYPTION_POLICY_OPTIONAL,
 366         SIPE_ENCRYPTION_POLICY_REQUIRED,
 367         SIPE_ENCRYPTION_POLICY_OBEY_SERVER
 368 } SipeEncryptionPolicy;
 369
 370 struct sipe_media_call;
 371 struct sipe_backend_media;
 372 struct sipe_backend_codec;
 373 struct sipe_backend_candidate;
 374 struct sipe_backend_media_stream;
 375 struct sipe_backend_media_relays;
 376
 377 struct sipe_media_stream {
 378         struct sipe_backend_media_stream *backend_private;
 379
 380         struct sipe_media_call *call;
 381         gchar *id;
 382
 383         void (*candidate_pairs_established_cb)(struct sipe_media_stream *);
 384         void (*read_cb)(struct sipe_media_stream *);
 385         void (*writable_cb)(struct sipe_media_stream *);
 386         void (*mute_cb)(struct sipe_media_stream *, gboolean is_muted);
 387 };
 388
 389 struct sipe_media_call {
 390         struct sipe_backend_media *backend_private;
 391
 392         gchar *with;
 393
 394         void (*stream_initialized_cb)(struct sipe_media_call *,
 395                                       struct sipe_media_stream *);
 396         void (*stream_end_cb)(struct sipe_media_call *,
 397                               struct sipe_media_stream *);
 398         void (*media_end_cb)(struct sipe_media_call *);
 399         void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
 400         void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
 401         void (*call_hold_cb)  (struct sipe_media_call *, gboolean local,
 402                                gboolean state);
 403         void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
 404         void (*error_cb)(struct sipe_media_call *, gchar *message);
 405 };
 406
 407 struct sipe_media_relay {
 408         gchar                 *hostname;
 409         guint                  udp_port;
 410         guint                  tcp_port;
 411         struct sipe_dns_query *dns_query;
 412 };
 413
 414 /* Media handling */
 415 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
 416                                                   struct sipe_media_call *call,
 417                                                   const gchar *participant,
 418                                                   SipeMediaCallFlags flags);
 419 void sipe_backend_media_free(struct sipe_backend_media *media);
 420
 421 void sipe_backend_media_set_cname(struct sipe_backend_media *media, gchar *cname);
 422
 423 struct sipe_backend_media_relays * sipe_backend_media_relays_convert(GSList *media_relays,
 424                                                                      gchar *username,
 425                                                                      gchar *password);
 426 void sipe_backend_media_relays_free(struct sipe_backend_media_relays *media_relays);
 427
 428 struct sipe_backend_media_stream *sipe_backend_media_add_stream(struct sipe_media_call *media,
 429                                                           const gchar *id,
 430                                                           const gchar *participant,
 431                                                           SipeMediaType type,
 432                                                           SipeIceVersion ice_version,
 433                                                           gboolean initiator,
 434                                                           struct sipe_backend_media_relays *media_relays);
 435 void sipe_backend_media_add_remote_candidates(struct sipe_media_call *media,
 436                                               struct sipe_media_stream *stream,
 437                                               GList *candidates);
 438 gboolean sipe_backend_media_is_initiator(struct sipe_media_call *media,
 439                                          struct sipe_media_stream *stream);
 440 gboolean sipe_backend_media_accepted(struct sipe_backend_media *media);
 441 gboolean sipe_backend_stream_initialized(struct sipe_media_call *media,
 442                                          struct sipe_media_stream *stream);
 443 void sipe_backend_media_set_encryption_keys(struct sipe_media_call *media,
 444                                             struct sipe_media_stream *stream,
 445                                             const guchar *encryption_key,
 446                                             const guchar *decryption_key);
 447
 448 /* Stream handling */
 449 void sipe_backend_stream_hold(struct sipe_media_call *media,
 450                               struct sipe_media_stream *stream,
 451                               gboolean local);
 452 void sipe_backend_stream_unhold(struct sipe_media_call *media,
 453                                 struct sipe_media_stream *stream,
 454                                 gboolean local);
 455 gboolean sipe_backend_stream_is_held(struct sipe_media_stream *stream);
 456
 457 GList *sipe_backend_media_stream_get_active_local_candidates(struct sipe_media_stream *stream);
 458 GList *sipe_backend_media_stream_get_active_remote_candidates(struct sipe_media_stream *stream);
 459
 460 gssize sipe_backend_media_stream_read(struct sipe_media_stream *stream,
 461                                      guint8 *buffer, gsize len);
 462 gssize sipe_backend_media_stream_write(struct sipe_media_stream *stream,
 463                                        guint8 *buffer, gsize len);
 464
 465 void sipe_backend_media_stream_end(struct sipe_media_call *media,
 466                                    struct sipe_media_stream *stream);
 467 void sipe_backend_media_stream_free(struct sipe_backend_media_stream *stream);
 468
 469 /* Codec handling */
 470 struct sipe_backend_codec *sipe_backend_codec_new(int id,
 471                                                   const char *name,
 472                                                   SipeMediaType type, guint clock_rate);
 473 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
 474 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
 475 /**
 476  * @return codec name. Will be g_free'd() by the core.
 477  */
 478 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
 479 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
 480 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
 481                                                const gchar *name,
 482                                                const gchar *value);
 483 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
 484 gboolean sipe_backend_set_remote_codecs(struct sipe_media_call *media,
 485                                         struct sipe_media_stream *stream,
 486                                         GList *codecs);
 487 GList* sipe_backend_get_local_codecs(struct sipe_media_call *media,
 488                                      struct sipe_media_stream *stream);
 489
 490 /* Candidate handling */
 491 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
 492                                                            SipeComponentType component,
 493                                                            SipeCandidateType type,
 494                                                            SipeNetworkProtocol proto,
 495                                                            const gchar *ip, guint port,
 496                                                            const gchar *username,
 497                                                            const gchar *password);
 498 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
 499 /**
 500  * @return user name. Will be g_free'd() by the core.
 501  */
 502 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
 503 /**
 504  * @return password. Will be g_free'd() by the core.
 505  */
 506 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
 507 /**
 508  * @return foundation. Will be g_free'd() by the core.
 509  */
 510 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
 511 /**
 512  * @return IP address string. Will be g_free'd() by the core.
 513  */
 514 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
 515 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
 516 /**
 517  * @return IP address string. Will be g_free'd() by the core.
 518  */
 519 gchar *sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate *candidate);
 520 guint sipe_backend_candidate_get_base_port(struct sipe_backend_candidate *candidate);
 521 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
 522 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
 523 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
 524 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
 525 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
 526 GList* sipe_backend_get_local_candidates(struct sipe_media_call *media,
 527                                          struct sipe_media_stream *stream);
 528 void sipe_backend_media_accept(struct sipe_backend_media *media, gboolean local);
 529 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
 530 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
 531
 532 /** NETWORK ******************************************************************/
 533
 534 const gchar *sipe_backend_network_ip_address(struct sipe_core_public *sipe_public);
 535
 536 struct sipe_backend_listendata;
 537
 538 typedef void (*sipe_listen_start_cb)(unsigned short port, gpointer data);
 539 typedef void (*sipe_client_connected_cb)(struct sipe_backend_fd *fd, gpointer data);
 540
 541 struct sipe_backend_listendata *
 542 sipe_backend_network_listen_range(unsigned short port_min,
 543                                   unsigned short port_max,
 544                                   sipe_listen_start_cb listen_cb,
 545                                   sipe_client_connected_cb connect_cb,
 546                                   gpointer data);
 547 void sipe_backend_network_listen_cancel(struct sipe_backend_listendata *ldata);
 548
 549 struct sipe_backend_fd * sipe_backend_fd_from_int(int fd);
 550 gboolean sipe_backend_fd_is_valid(struct sipe_backend_fd *fd);
 551 void sipe_backend_fd_free(struct sipe_backend_fd *fd);
 552
 553 /** NOTIFICATIONS *************************************************************/
 554
 555 void sipe_backend_notify_message_error(struct sipe_core_public *sipe_public,
 556                                        struct sipe_backend_chat_session *backend_session,
 557                                        const gchar *who,
 558                                        const gchar *message);
 559 void sipe_backend_notify_message_info(struct sipe_core_public *sipe_public,
 560                                       struct sipe_backend_chat_session *backend_session,
 561                                       const gchar *who,
 562                                       const gchar *message);
 563
 564 /**
 565  * @param msg  error message. Maybe @NULL
 566  */
 567 void sipe_backend_notify_error(struct sipe_core_public *sipe_public,
 568                                const gchar *title,
 569                                const gchar *msg);
 570
 571 /** SCHEDULE *****************************************************************/
 572
 573 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
 574                                        guint timeout,
 575                                        gpointer data);
 576 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
 577                                         guint timeout,
 578                                         gpointer data);
 579 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
 580                                   gpointer data);
 581
 582 /** SEARCH *******************************************************************/
 583
 584 struct sipe_backend_search_results;
 585 struct sipe_backend_search_token;
 586
 587 void sipe_backend_search_failed(struct sipe_core_public *sipe_public,
 588                                 struct sipe_backend_search_token *token,
 589                                 const gchar *msg);
 590 struct sipe_backend_search_results *sipe_backend_search_results_start(struct sipe_core_public *sipe_public,
 591                                                                       struct sipe_backend_search_token *token);
 592 void sipe_backend_search_results_add(struct sipe_core_public *sipe_public,
 593                                      struct sipe_backend_search_results *results,
 594                                      const gchar *uri,
 595                                      const gchar *name,
 596                                      const gchar *company,
 597                                      const gchar *country,
 598                                      const gchar *email);
 599 void sipe_backend_search_results_finalize(struct sipe_core_public *sipe_public,
 600                                           struct sipe_backend_search_results *results,
 601                                           const gchar *description,
 602                                           gboolean more);
 603
 604 /** SETTINGS *****************************************************************/
 605
 606 typedef enum {
 607   SIPE_SETTING_EMAIL_URL = 0,
 608   SIPE_SETTING_EMAIL_LOGIN,
 609   SIPE_SETTING_EMAIL_PASSWORD,
 610   SIPE_SETTING_GROUPCHAT_USER,
 611   SIPE_SETTING_USER_AGENT,
 612   SIPE_SETTING_LAST
 613 } sipe_setting;
 614 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
 615                                   sipe_setting type);
 616
 617 /** STATUS *******************************************************************/
 618
 619 guint sipe_backend_status(struct sipe_core_public *sipe_public);
 620 gboolean sipe_backend_status_changed(struct sipe_core_public *sipe_public,
 621                                      guint activity,
 622                                      const gchar *message);
 623
 624 /**
 625  * Update user client with new status and note received from server
 626  *
 627  * NOTE: this must *NOT* trigger a call to @c sipe_core_status_set()!
 628  *
 629  * @param sipe_public   The handle representing the protocol instance
 630  * @param activity      New activity
 631  * @param message       New note text
 632  */
 633 void sipe_backend_status_and_note(struct sipe_core_public *sipe_public,
 634                                   guint activity,
 635                                   const gchar *message);
 636
 637 /** TRANSPORT ****************************************************************/
 638
 639 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
 640 typedef void transport_input_cb(struct sipe_transport_connection *conn);
 641 typedef void transport_error_cb(struct sipe_transport_connection *conn,
 642                                 const gchar *msg);
 643
 644 typedef struct {
 645         guint type;
 646         const gchar *server_name;
 647         guint server_port;
 648         gpointer user_data;
 649         transport_connected_cb *connected;
 650         transport_input_cb *input;
 651         transport_error_cb *error;
 652 } sipe_connect_setup;
 653 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
 654                                                                  const sipe_connect_setup *setup);
 655 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
 656 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
 657                                     const gchar *buffer);
 658 void sipe_backend_transport_flush(struct sipe_transport_connection *conn);
 659
 660 /** USER *********************************************************************/
 661
 662 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
 663                                        const gchar *from);
 664 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
 665                                             const gchar *from);
 666
 667 /**
 668  * Present a query that is to be accepted or declined by the user
 669  *
 670  * @param sipe_public   The handle representing the protocol instance
 671  * @param message       Text of the query to be shown to user
 672  * @param accept_label  Label to be displayed on UI control that accepts query
 673  * @param decline_label Label to be displayed on UI control that declines query
 674  * @param key           Opaque handle uniquely identifying the query. Backend
 675  *                      should store it for the case SIPE core requests the
 676  *                      query to be closed prematurely.
 677  */
 678 void sipe_backend_user_ask(struct sipe_core_public *sipe_public,
 679                            const gchar *message,
 680                            const gchar *accept_label,
 681                            const gchar *decline_label,
 682                            gpointer key);
 683
 684 /**
 685  * Closes the pending user query
 686  *
 687  * @param key Opaque handle uniquely identifying the query.
 688  */
 689 void sipe_backend_user_close_ask(gpointer key);
 690
 691 /** BUDDIES ******************************************************************/
 692
 693 /*
 694  * sipe_backend_buddy_get/set_string(): properties a buddy can have
 695  * sipe_backend_buddy_info_add():       mapped, e.g. to a string label
 696  */
 697 typedef enum
 698 {
 699         SIPE_BUDDY_INFO_DISPLAY_NAME = 0,
 700         SIPE_BUDDY_INFO_JOB_TITLE,
 701         SIPE_BUDDY_INFO_CITY,
 702         SIPE_BUDDY_INFO_STATE,
 703         SIPE_BUDDY_INFO_OFFICE,
 704         SIPE_BUDDY_INFO_DEPARTMENT,
 705         SIPE_BUDDY_INFO_COUNTRY,
 706         SIPE_BUDDY_INFO_WORK_PHONE,
 707         SIPE_BUDDY_INFO_WORK_PHONE_DISPLAY,
 708         SIPE_BUDDY_INFO_COMPANY,
 709         SIPE_BUDDY_INFO_EMAIL,
 710         SIPE_BUDDY_INFO_SITE,
 711         SIPE_BUDDY_INFO_ZIPCODE,
 712         SIPE_BUDDY_INFO_STREET,
 713         SIPE_BUDDY_INFO_MOBILE_PHONE,
 714         SIPE_BUDDY_INFO_MOBILE_PHONE_DISPLAY,
 715         SIPE_BUDDY_INFO_HOME_PHONE,
 716         SIPE_BUDDY_INFO_HOME_PHONE_DISPLAY,
 717         SIPE_BUDDY_INFO_OTHER_PHONE,
 718         SIPE_BUDDY_INFO_OTHER_PHONE_DISPLAY,
 719         SIPE_BUDDY_INFO_CUSTOM1_PHONE,
 720         SIPE_BUDDY_INFO_CUSTOM1_PHONE_DISPLAY,
 721         SIPE_BUDDY_INFO_ALIAS,  /* only for sipe_backend_buddy_info_add() */
 722         SIPE_BUDDY_INFO_DEVICE, /* only for sipe_backend_buddy_info_add() */
 723 } sipe_buddy_info_fields;
 724
 725 /* Opaque token */
 726 typedef void* sipe_backend_buddy;
 727
 728 /**
 729  * Find a buddy in the given group of the buddy list, or anywhere on the
 730  * list if @group_name is empty
 731  *
 732  * @param sipe_public The handle representing the protocol instance making the call
 733  * @param buddy_name The name of the buddy
 734  * @param group_name The name of the group to look in, or NULL for any group
 735  * @return opaque handle to the buddy, or NULL if no buddy found
 736  */
 737 sipe_backend_buddy sipe_backend_buddy_find(struct sipe_core_public *sipe_public,
 738                                            const gchar *buddy_name,
 739                                            const gchar *group_name);
 740
 741 /*
 742  * Find all named buddies in the given group of the buddy list, or anywhere on the
 743  * list if @group_name is empty; or all buddies if @name is empty
 744  *
 745  * @param sipe_public The handle representing the protocol instance making the call
 746  * @param name The name of the buddy
 747  * @param group_name The name of the group to look in, or NULL for any group
 748  * @return GSList of opaque handles to the buddies
 749  */
 750 GSList* sipe_backend_buddy_find_all(struct sipe_core_public *sipe_public,
 751                                     const gchar *buddy_name,
 752                                     const gchar *group_name);
 753
 754 /**
 755  * Gets the name of a contact.
 756  *
 757  * @param sipe_public The handle representing the protocol instance making the call
 758  * @param who The opaque handle to the contact as found by find_buddy
 759  * @return The name. Must be freed.
 760  */
 761 gchar* sipe_backend_buddy_get_name(struct sipe_core_public *sipe_public,
 762                                    const sipe_backend_buddy who);
 763
 764 /**
 765  * Gets the alias for a contact.
 766  *
 767  * @param sipe_public The handle representing the protocol instance making the call
 768  * @param who The opaque handle to the contact as found by find_buddy
 769  * @return The alias. Must be gfree'd.
 770  */
 771 gchar* sipe_backend_buddy_get_alias(struct sipe_core_public *sipe_public,
 772                                     const sipe_backend_buddy who);
 773
 774 /**
 775  * Gets the server alias for a contact.
 776  *
 777  * @param sipe_public The handle representing the protocol instance making the call
 778  * @param who The opaque handle to the contact as found by find_buddy
 779  * @return The alias. Must be freed.
 780  */
 781 gchar* sipe_backend_buddy_get_server_alias(struct sipe_core_public *sipe_public,
 782                                            const sipe_backend_buddy who);
 783
 784 /**
 785  * Gets the local alias for a contact
 786  *
 787  * @param sipe_public The handle representing the protocol instance making the call
 788  * @param uri         the budyy name
 789  *
 790  * @return the alias. Must be @g_free()'d.
 791  */
 792 gchar *sipe_backend_buddy_get_local_alias(struct sipe_core_public *sipe_public,
 793                                           const sipe_backend_buddy who);
 794
 795 /**
 796  * Gets the name of the group a contact belongs to.
 797  *
 798  * @param sipe_public The handle representing the protocol instance making the call
 799  * @param who The opaque handle to the contact as found by find_buddy
 800  * @return The name. Must be freed.
 801  */
 802 gchar* sipe_backend_buddy_get_group_name(struct sipe_core_public *sipe_public,
 803                                          const sipe_backend_buddy who);
 804
 805 /**
 806  * Called to retrieve a buddy-specific setting.
 807  *
 808  * @param sipe_public The handle representing the protocol instance making the call
 809  * @param buddy The handle representing the buddy
 810  * @param key The name of the setting
 811  * @return The value of the setting. Must be freed.
 812  */
 813 gchar* sipe_backend_buddy_get_string(struct sipe_core_public *sipe_public,
 814                                      sipe_backend_buddy buddy,
 815                                      const sipe_buddy_info_fields key);
 816
 817 /**
 818  * Called to set a buddy-specific setting.
 819  *
 820  * @param sipe_public The handle representing the protocol instance making the call
 821  * @param buddy The handle representing the buddy
 822  * @param key The name of the setting
 823  * @param val The value to set
 824  */
 825 void sipe_backend_buddy_set_string(struct sipe_core_public *sipe_public,
 826                                    sipe_backend_buddy buddy,
 827                                    const sipe_buddy_info_fields key,
 828                                    const gchar *val);
 829
 830 /**
 831  * Called after one ore more buddy-specific settings have been updated.
 832  *
 833  * Can be used by the backend to trigger an UI update event
 834  *
 835  * @param sipe_public The handle representing the protocol instance making the call
 836  * @param uri         SIP URI of the contact
 837  */
 838 void sipe_backend_buddy_refresh_properties(struct sipe_core_public *sipe_public,
 839                                            const gchar *uri);
 840
 841 /**
 842  * Get the status token for a contact
 843  *
 844  * @param sipe_public The handle representing the protocol instance making the call
 845  * @param uri         SIP URI of the contact
 846  *
 847  * @return activity
 848  */
 849 guint sipe_backend_buddy_get_status(struct sipe_core_public *sipe_public,
 850                                     const gchar *uri);
 851
 852 /**
 853  * Sets the alias for a contact.
 854  *
 855  * @param sipe_public The handle representing the protocol instance making the call
 856  * @param who The opaque handle to the contact as found by find_buddy
 857  * @param alias The location where the alias will be put
 858  * case. FALSE if the buddy was not found. The value of alias will not be changed.
 859  */
 860 void sipe_backend_buddy_set_alias(struct sipe_core_public *sipe_public,
 861                                   const sipe_backend_buddy who,
 862                                   const gchar *alias);
 863
 864 /**
 865  * Sets the server alias for a contact.
 866  *
 867  * @param sipe_public The handle representing the protocol instance making the call
 868  * @param who The opaque handle to the contact as found by find_buddy
 869  * @param alias The server alias of the contact
 870  */
 871 void sipe_backend_buddy_set_server_alias(struct sipe_core_public *sipe_public,
 872                                          const sipe_backend_buddy who,
 873                                          const gchar *alias);
 874
 875 /**
 876  * Start processing buddy list
 877  *
 878  * Will be called every time we receive a buddy list in roaming contacts
 879  *
 880  * @param sipe_public The handle representing the protocol instance making the call
 881  */
 882 void sipe_backend_buddy_list_processing_start(struct sipe_core_public *sipe_public);
 883
 884 /**
 885  * Finished processing buddy list
 886  *
 887  * Will be called every time we receive a buddy list in roaming contacts
 888  *
 889  * @param sipe_public The handle representing the protocol instance making the call
 890  */
 891 void sipe_backend_buddy_list_processing_finish(struct sipe_core_public *sipe_public);
 892
 893 /**
 894  * Add a contact to the buddy list
 895  *
 896  * @param sipe_public The handle representing the protocol instance making the call
 897  * @param name The name of the contact
 898  * @param alias The alias of the contact
 899  * @param groupname The name of the group to add this contact to
 900  * @return A handle to the newly created buddy
 901  */
 902 sipe_backend_buddy sipe_backend_buddy_add(struct sipe_core_public *sipe_public,
 903                                           const gchar *name,
 904                                           const gchar *alias,
 905                                           const gchar *groupname);
 906
 907 /**
 908  * Remove a contact from the buddy list
 909  *
 910  * @param sipe_public The handle representing the protocol instance making the call
 911  * @param who The opaque handle to the contact as found by find_buddy
 912  */
 913 void sipe_backend_buddy_remove(struct sipe_core_public *sipe_public,
 914                                const sipe_backend_buddy who);
 915
 916 /**
 917  * Notifies the user that a remote user has wants to add the local user to his
 918  * or her buddy list and requires authorization to do so.
 919  *
 920  * @param sipe_public The handle representing the protocol instance making the call
 921  * @param who The name of the user that added this account
 922  * @param alias The optional alias of the remote user
 923  * @param on_list True if the user is already in our list
 924  * @param auth_cb The callback called when the local user accepts
 925  * @param deny_cb The callback called when the local user rejects
 926  * @param data Data to be passed back to the above callbacks
 927  */
 928 typedef void (*sipe_backend_buddy_request_authorization_cb)(void *);
 929
 930 void sipe_backend_buddy_request_add(struct sipe_core_public *sipe_public,
 931                                     const gchar *who,
 932                                     const gchar *alias);
 933
 934 void sipe_backend_buddy_request_authorization(struct sipe_core_public *sipe_public,
 935                                               const gchar *who,
 936                                               const gchar *alias,
 937                                               gboolean on_list,
 938                                               sipe_backend_buddy_request_authorization_cb auth_cb,
 939                                               sipe_backend_buddy_request_authorization_cb deny_cb,
 940                                               gpointer data);
 941
 942 gboolean sipe_backend_buddy_is_blocked(struct sipe_core_public *sipe_public,
 943                                        const gchar *who);
 944
 945 void sipe_backend_buddy_set_blocked_status(struct sipe_core_public *sipe_public,
 946                                            const gchar *who,
 947                                            gboolean blocked);
 948
 949 void sipe_backend_buddy_set_status(struct sipe_core_public *sipe_public,
 950                                    const gchar *who,
 951                                    guint activity);
 952
 953 /**
 954  * Checks whether backend has a capability to use buddy photos. If this function
 955  * returns @c FALSE, SIPE core will not attempt to download the photos from
 956  * server to save bandwidth.
 957  *
 958  * @return @c TRUE if backend is photo capable, otherwise @FALSE
 959  */
 960 gboolean sipe_backend_uses_photo(void);
 961
 962 /**
 963  * Gives backend a photo image associated with a SIP URI. Backend has ownership
 964  * of the data and must free it when not needed.
 965  *
 966  * @param sipe_public The handle representing the protocol instance making the call
 967  * @param who The name of the user whose photo is being set
 968  * @param image_data The photo image data, must be g_free()'d by backend
 969  * @param image_len Size of the image in Bytes
 970  * @param photo_hash A data checksum provided by the server
 971  */
 972 void sipe_backend_buddy_set_photo(struct sipe_core_public *sipe_public,
 973                                   const gchar *who,
 974                                   gpointer image_data,
 975                                   gsize image_len,
 976                                   const gchar *photo_hash);
 977
 978 /**
 979  * Retrieves a photo hash stored together with image data by
 980  * @c sipe_backend_buddy_set_photo. Value is used by the core to detect photo
 981  * file changes on server.
 982  *
 983  * @param sipe_public The handle representing the protocol instance making the call
 984  * @param who The name of the user whose photo hash to retrieve
 985  * @return a photo hash (may be NULL)
 986  */
 987 const gchar *sipe_backend_buddy_get_photo_hash(struct sipe_core_public *sipe_public,
 988                                                const gchar *who);
 989
 990 /**
 991  * Called when a new internal group is about to be added. If this returns FALSE,
 992  * the group will not be added.
 993  *
 994  * @param sipe_public The handle representing the protocol instance making the call
 995  * @param group_name  The group being added
 996  * @return TRUE if everything is ok, FALSE if the group should not be added
 997  */
 998 gboolean sipe_backend_buddy_group_add(struct sipe_core_public *sipe_public,
 999                                       const gchar *group_name);
1000
1001 /**
1002  * Called when a new internal group has been renamed
1003  *
1004  * @param sipe_public The handle representing the protocol instance making the call
1005  * @param old_name old name of the group
1006  * @param new_name new name of the group
1007  * @return TRUE if the group was found and renamed
1008  */
1009 gboolean sipe_backend_buddy_group_rename(struct sipe_core_public *sipe_public,
1010                                          const gchar *old_name,
1011                                          const gchar *new_name);
1012
1013 /**
1014  * Called when a new internal group should be deleted
1015  *
1016  * NOTE: this will only be called on empty groups.
1017  *
1018  * @param sipe_public The handle representing the protocol instance making the call
1019  * @param group_name  The group that should be removed
1020  */
1021 void sipe_backend_buddy_group_remove(struct sipe_core_public *sipe_public,
1022                                      const gchar *group_name);
1023
1024 /**
1025  * Present requested buddy information to the user
1026  */
1027 struct sipe_backend_buddy_info;
1028 struct sipe_backend_buddy_info *sipe_backend_buddy_info_start(struct sipe_core_public *sipe_public);
1029 void sipe_backend_buddy_info_add(struct sipe_core_public *sipe_public,
1030                                  struct sipe_backend_buddy_info *info,
1031                                  sipe_buddy_info_fields key,
1032                                  const gchar *value);
1033 void sipe_backend_buddy_info_break(struct sipe_core_public *sipe_public,
1034                                    struct sipe_backend_buddy_info *info);
1035 void sipe_backend_buddy_info_finalize(struct sipe_core_public *sipe_public,
1036                                       struct sipe_backend_buddy_info *info,
1037                                       const gchar *uri);
1038
1039 struct sipe_backend_buddy_tooltip;
1040 void sipe_backend_buddy_tooltip_add(struct sipe_core_public *sipe_public,
1041                                     struct sipe_backend_buddy_tooltip *tooltip,
1042                                     const gchar *description,
1043                                     const gchar *value);
1044
1045 /**
1046  * Buddy menu creation
1047  */
1048 enum sipe_buddy_menu_type {
1049         SIPE_BUDDY_MENU_MAKE_CHAT_LEADER = 0,
1050         SIPE_BUDDY_MENU_REMOVE_FROM_CHAT,
1051         SIPE_BUDDY_MENU_INVITE_TO_CHAT,
1052         SIPE_BUDDY_MENU_NEW_CHAT,
1053         SIPE_BUDDY_MENU_MAKE_CALL,
1054         SIPE_BUDDY_MENU_SEND_EMAIL,
1055         SIPE_BUDDY_MENU_ACCESS_LEVEL_HELP,
1056         SIPE_BUDDY_MENU_CHANGE_ACCESS_LEVEL,
1057         SIPE_BUDDY_MENU_ADD_NEW_DOMAIN,
1058         SIPE_BUDDY_MENU_TYPES
1059 };
1060
1061 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_start(struct sipe_core_public *sipe_public);
1062 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_add(struct sipe_core_public *sipe_public,
1063                                                             struct sipe_backend_buddy_menu *menu,
1064                                                             const gchar *label,
1065                                                             enum sipe_buddy_menu_type type,
1066                                                             gpointer parameter);
1067 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_separator(struct sipe_core_public *sipe_public,
1068                                                                   struct sipe_backend_buddy_menu *menu,
1069                                                                   const gchar *label);
1070 struct sipe_backend_buddy_menu *sipe_backend_buddy_sub_menu_add(struct sipe_core_public *sipe_public,
1071                                                                 struct sipe_backend_buddy_menu *menu,
1072                                                                 const gchar *label,
1073                                                                 struct sipe_backend_buddy_menu *sub);
1074
1075 SipeEncryptionPolicy sipe_backend_media_get_encryption_policy(struct sipe_core_public *sipe_public);
1076
1077 #ifdef __cplusplus
1078 }
1079 #endif
1080
1081 /*
1082   Local Variables:
1083   mode: c
1084   c-file-style: "bsd"
1085   indent-tabs-mode: t
1086   tab-width: 8
1087   End:
1088 */