src/api/sipe-backend.h

   1 /**
   2  * @file sipe-backend.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010-11 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_FATAL,
  68 }  sipe_debug_level;
  69
  70 /**
  71  * Output debug information without formatting
  72  *
  73  * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
  74  *
  75  * @param level  debug level
  76  * @param msg    debug message "\n" will be automatically appended.
  77  */
  78 void sipe_backend_debug_literal(sipe_debug_level level,
  79                                 const gchar *msg);
  80
  81 /**
  82  * Output debug information
  83  *
  84  * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
  85  *
  86  * @param level  debug level
  87  * @param format format string. "\n" will be automatically appended.
  88  */
  89 void sipe_backend_debug(sipe_debug_level level,
  90                         const gchar *format,
  91                         ...) G_GNUC_PRINTF(2, 3);
  92
  93 /* Convenience macros */
  94 #define SIPE_DEBUG_INFO(fmt, ...)        sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO,    fmt, __VA_ARGS__)
  95 #define SIPE_DEBUG_INFO_NOFORMAT(msg)    sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_INFO,    msg)
  96 #define SIPE_DEBUG_WARNING(fmt, ...)     sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
  97 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_WARNING, msg)
  98 #define SIPE_DEBUG_ERROR(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR,   fmt, __VA_ARGS__)
  99 #define SIPE_DEBUG_ERROR_NOFORMAT(msg)   sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_ERROR,   msg)
 100 #define SIPE_DEBUG_FATAL(fmt, ...)       sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL,   fmt, __VA_ARGS__)
 101 #define SIPE_DEBUG_FATAL_NOFORMAT(msg)   sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_FATAL,   msg)
 102
 103 /**
 104  * Check backend debugging status
 105  *
 106  * @return TRUE if debugging is enabled
 107  */
 108 gboolean sipe_backend_debug_enabled(void);
 109
 110 /** CHAT *********************************************************************/
 111
 112 void sipe_backend_chat_session_destroy(struct sipe_backend_chat_session *session);
 113 void sipe_backend_chat_add(struct sipe_backend_chat_session *backend_session,
 114                            const gchar *uri,
 115                            gboolean is_new);
 116 void sipe_backend_chat_close(struct sipe_backend_chat_session *backend_session);
 117
 118 /**
 119  * Joined a new chat
 120  */
 121 struct sipe_backend_chat_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
 122                                                            struct sipe_chat_session *session,
 123                                                            const gchar *title,
 124                                                            const gchar *nick);
 125 gboolean sipe_backend_chat_find(struct sipe_backend_chat_session *backend_session,
 126                                 const gchar *uri);
 127 gboolean sipe_backend_chat_is_operator(struct sipe_backend_chat_session *backend_session,
 128                                        const gchar *uri);
 129 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
 130                                struct sipe_backend_chat_session *backend_session,
 131                                const gchar *from,
 132                                const gchar *html);
 133 void sipe_backend_chat_operator(struct sipe_backend_chat_session *backend_session,
 134                                 const gchar *uri);
 135
 136 /**
 137  * Rejoin an existing chat window after connection re-establishment
 138  */
 139 void sipe_backend_chat_rejoin(struct sipe_core_public *sipe_public,
 140                               struct sipe_backend_chat_session *backend_session,
 141                               const gchar *nick,
 142                               const gchar *title);
 143
 144 /**
 145  * Core has completed connection re-establishment.
 146  * Should call sipe_core_chat_rejoin() for existing chats.
 147  */
 148 void sipe_backend_chat_rejoin_all(struct sipe_core_public *sipe_public);
 149 void sipe_backend_chat_remove(struct sipe_backend_chat_session *backend_session,
 150                               const gchar *uri);
 151
 152 /**
 153  * Move chat window to the front. Will be called when
 154  * a user tries to join an already joined chat again.
 155  */
 156 void sipe_backend_chat_show(struct sipe_backend_chat_session *backend_session);
 157 void sipe_backend_chat_topic(struct sipe_backend_chat_session *backend_session,
 158                              const gchar *topic);
 159
 160 /** CONNECTION ***************************************************************/
 161
 162 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
 163
 164 typedef enum {
 165   SIPE_CONNECTION_ERROR_NETWORK = 0,
 166   SIPE_CONNECTION_ERROR_INVALID_USERNAME,
 167   SIPE_CONNECTION_ERROR_INVALID_SETTINGS,
 168   SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED,
 169   SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE,
 170   SIPE_CONNECTION_ERROR_LAST
 171 } sipe_connection_error;
 172 void sipe_backend_connection_error(struct sipe_core_public *sipe_public,
 173                                    sipe_connection_error error,
 174                                    const gchar *msg);
 175
 176 gboolean sipe_backend_connection_is_disconnecting(struct sipe_core_public *sipe_public);
 177 gboolean sipe_backend_connection_is_valid(struct sipe_core_public *sipe_public);
 178
 179 /** DNS QUERY ****************************************************************/
 180
 181 typedef void (*sipe_dns_resolved_cb)(gpointer data, const gchar *hostname, guint port);
 182
 183 struct sipe_dns_query *sipe_backend_dns_query_srv(struct sipe_core_public *sipe_public,
 184                                                   const gchar *protocol,
 185                                                   const gchar *transport,
 186                                                   const gchar *domain,
 187                                                   sipe_dns_resolved_cb callback,
 188                                                   gpointer data);
 189
 190 struct sipe_dns_query *sipe_backend_dns_query_a(struct sipe_core_public *sipe_public,
 191                                                 const gchar *hostname,
 192                                                 int port,
 193                                                 sipe_dns_resolved_cb callback,
 194                                                 gpointer data);
 195
 196 void sipe_backend_dns_query_cancel(struct sipe_dns_query *query);
 197
 198 /** FILE TRANSFER ************************************************************/
 199
 200 struct sipe_backend_fd;
 201
 202 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
 203                            const gchar *errmsg);
 204 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
 205 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
 206
 207 /**
 208  * Try to read up to @c size bytes from file transfer connection
 209  *
 210  * @param ft   file transfer data.
 211  * @param data buffer to read data into.
 212  * @param size buffer size in bytes.
 213  *
 214  * @return number of bytes read or negative on failure.
 215  *         EAGAIN should return 0 bytes read.
 216  */
 217 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
 218                             guchar *data,
 219                             gsize size);
 220
 221 /**
 222  * Try to write up to @c size bytes to file transfer connection
 223  *
 224  * @param ft   file transfer data.
 225  * @param data data to write
 226  * @param size buffer size in bytes.
 227  *
 228  * @return number of bytes read or negative on failure.
 229  *         EAGAIN should return 0 bytes written.
 230  */
 231 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
 232                              const guchar *data,
 233                              gsize size);
 234
 235
 236 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
 237 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
 238
 239 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
 240                               struct sipe_file_transfer *ft,
 241                               const gchar *who,
 242                               const gchar *file_name,
 243                               gsize file_size);
 244 /**
 245  * Begins file transfer with remote peer.
 246  *
 247  * You can provide either opened file descriptor to use for read/write operations
 248  * or ip address and port where the backend should connect.
 249  *
 250  * @param ft   file transfer data
 251  * @param fd   opaque file descriptor pointer or NULL if ip and port are used
 252  * @param ip   ip address to connect of NULL when file descriptor is used
 253  * @param port port to connect or 0 when file descriptor is used
 254  */
 255 void sipe_backend_ft_start(struct sipe_file_transfer *ft,
 256                            struct sipe_backend_fd *fd,
 257                            const char* ip, unsigned port);
 258
 259 /**
 260  * Check whether file transfer is incoming or outgoing
 261  *
 262  * @param ft file transfer data
 263  * @return @c TRUE if @c ft is incoming, otherwise @c FALSE
 264  */
 265 gboolean sipe_backend_ft_is_incoming(struct sipe_file_transfer *ft);
 266
 267 /** GROUP CHAT ***************************************************************/
 268
 269 #define SIPE_GROUPCHAT_ROOM_FILEPOST 0x00000001
 270 #define SIPE_GROUPCHAT_ROOM_INVITE   0x00000002
 271 #define SIPE_GROUPCHAT_ROOM_LOGGED   0x00000004
 272 #define SIPE_GROUPCHAT_ROOM_PRIVATE  0x00000008
 273
 274 /**
 275  * Add a room found through room query
 276  *
 277  * @param uri         room URI
 278  * @param name        human readable name for room
 279  * @param description room description
 280  * @param users       number of users in the room
 281  * @param flags       SIPE_GROUPCHAT_ROOM_* flags
 282  */
 283 void sipe_backend_groupchat_room_add(struct sipe_core_public *sipe_public,
 284                                      const gchar *uri,
 285                                      const gchar *name,
 286                                      const gchar *description,
 287                                      guint users,
 288                                      guint32 flags);
 289
 290 /**
 291  * Terminate room query
 292  */
 293 void sipe_backend_groupchat_room_terminate(struct sipe_core_public *sipe_public);
 294
 295 /** IM ***********************************************************************/
 296
 297 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
 298                              const gchar *from,
 299                              const gchar *html);
 300 void sipe_backend_im_topic(struct sipe_core_public *sipe_public,
 301                            const gchar *with,
 302                            const gchar *topic);
 303
 304 /** MARKUP *******************************************************************/
 305
 306 gchar *sipe_backend_markup_css_property(const gchar *style,
 307                                         const gchar *option);
 308 gchar *sipe_backend_markup_strip_html(const gchar *html);
 309
 310 /** MEDIA ********************************************************************/
 311
 312 typedef enum {
 313         SIPE_ICE_NO_ICE,
 314         SIPE_ICE_DRAFT_6,
 315         SIPE_ICE_RFC_5245
 316 } SipeIceVersion;
 317
 318 typedef enum {
 319         SIPE_CANDIDATE_TYPE_ANY,
 320         SIPE_CANDIDATE_TYPE_HOST,
 321         SIPE_CANDIDATE_TYPE_RELAY,
 322         SIPE_CANDIDATE_TYPE_SRFLX,
 323         SIPE_CANDIDATE_TYPE_PRFLX
 324 } SipeCandidateType;
 325
 326 typedef enum {
 327         SIPE_COMPONENT_NONE = 0,
 328         SIPE_COMPONENT_RTP  = 1,
 329         SIPE_COMPONENT_RTCP = 2
 330 } SipeComponentType;
 331
 332 typedef enum {
 333         SIPE_MEDIA_AUDIO,
 334         SIPE_MEDIA_VIDEO
 335 } SipeMediaType;
 336
 337 typedef enum {
 338         SIPE_NETWORK_PROTOCOL_TCP_ACTIVE,
 339         SIPE_NETWORK_PROTOCOL_TCP_PASSIVE,
 340         SIPE_NETWORK_PROTOCOL_UDP
 341 } SipeNetworkProtocol;
 342
 343 struct sipe_media_call;
 344 struct sipe_backend_media;
 345 struct sipe_backend_codec;
 346 struct sipe_backend_candidate;
 347 struct sipe_backend_stream;
 348 struct sipe_backend_media_relays;
 349
 350 struct sipe_media_call {
 351         struct sipe_backend_media *backend_private;
 352
 353         void (*candidates_prepared_cb)(struct sipe_media_call *,
 354                                        struct sipe_backend_stream *);
 355         void (*media_end_cb)(struct sipe_media_call *);
 356         void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
 357         void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
 358         void (*call_hold_cb)  (struct sipe_media_call *, gboolean local,
 359                                gboolean state);
 360         void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
 361         void (*error_cb)(struct sipe_media_call *, gchar *message);
 362 };
 363
 364 struct sipe_media_relay {
 365         gchar                 *hostname;
 366         guint                  udp_port;
 367         guint                  tcp_port;
 368         struct sipe_dns_query *dns_query;
 369 };
 370
 371 /* Media handling */
 372 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
 373                                                   struct sipe_media_call *call,
 374                                                   const gchar *participant,
 375                                                   gboolean initiator);
 376 void sipe_backend_media_free(struct sipe_backend_media *media);
 377
 378 void sipe_backend_media_set_cname(struct sipe_backend_media *media, gchar *cname);
 379
 380 struct sipe_backend_media_relays * sipe_backend_media_relays_convert(GSList *media_relays,
 381                                                                      gchar *username,
 382                                                                      gchar *password);
 383 void sipe_backend_media_relays_free(struct sipe_backend_media_relays *media_relays);
 384
 385 struct sipe_backend_stream *sipe_backend_media_add_stream(struct sipe_backend_media *media,
 386                                                           const gchar *id,
 387                                                           const gchar *participant,
 388                                                           SipeMediaType type,
 389                                                           SipeIceVersion ice_version,
 390                                                           gboolean initiator,
 391                                                           struct sipe_backend_media_relays *media_relays);
 392 void sipe_backend_media_remove_stream(struct sipe_backend_media *media,
 393                                       struct sipe_backend_stream *stream);
 394 GSList *sipe_backend_media_get_streams(struct sipe_backend_media *media);
 395 struct sipe_backend_stream *sipe_backend_media_get_stream_by_id(struct sipe_backend_media *media,
 396                                                                 const gchar *id);
 397 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media *media,
 398                                               struct sipe_backend_stream *stream,
 399                                               GList *candidates);
 400 gboolean sipe_backend_media_is_initiator(struct sipe_backend_media *media,
 401                                          struct sipe_backend_stream *stream);
 402 gboolean sipe_backend_media_accepted(struct sipe_backend_media *media);
 403 gboolean sipe_backend_candidates_prepared(struct sipe_backend_media *media);
 404 GList *sipe_backend_media_get_active_local_candidates(struct sipe_backend_media *media,
 405                                                       struct sipe_backend_stream *stream);
 406 GList *sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media *media,
 407                                                        struct sipe_backend_stream *stream);
 408
 409 /* Stream handling */
 410 gchar *sipe_backend_stream_get_id(struct sipe_backend_stream *stream);
 411 SipeMediaType sipe_backend_stream_get_type(struct sipe_backend_stream *stream);
 412 void sipe_backend_stream_hold(struct sipe_backend_media *media,
 413                               struct sipe_backend_stream *stream,
 414                               gboolean local);
 415 void sipe_backend_stream_unhold(struct sipe_backend_media *media,
 416                                 struct sipe_backend_stream *stream,
 417                                 gboolean local);
 418 gboolean sipe_backend_stream_is_held(struct sipe_backend_stream *stream);
 419
 420 /* Codec handling */
 421 struct sipe_backend_codec *sipe_backend_codec_new(int id,
 422                                                   const char *name,
 423                                                   SipeMediaType type, guint clock_rate);
 424 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
 425 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
 426 /**
 427  * @return codec name. Will be g_free'd() by the core.
 428  */
 429 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
 430 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
 431 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
 432                                                const gchar *name,
 433                                                const gchar *value);
 434 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
 435 gboolean sipe_backend_set_remote_codecs(struct sipe_backend_media *media,
 436                                         struct sipe_backend_stream *stream,
 437                                         GList *codecs);
 438 GList* sipe_backend_get_local_codecs(struct sipe_backend_media *media,
 439                                      struct sipe_backend_stream *stream);
 440
 441 /* Candidate handling */
 442 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
 443                                                            SipeComponentType component,
 444                                                            SipeCandidateType type,
 445                                                            SipeNetworkProtocol proto,
 446                                                            const gchar *ip, guint port,
 447                                                            const gchar *username,
 448                                                            const gchar *password);
 449 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
 450 /**
 451  * @return user name. Will be g_free'd() by the core.
 452  */
 453 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
 454 /**
 455  * @return password. Will be g_free'd() by the core.
 456  */
 457 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
 458 /**
 459  * @return foundation. Will be g_free'd() by the core.
 460  */
 461 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
 462 /**
 463  * @return IP address string. Will be g_free'd() by the core.
 464  */
 465 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
 466 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
 467 /**
 468  * @return IP address string. Will be g_free'd() by the core.
 469  */
 470 gchar *sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate *candidate);
 471 guint sipe_backend_candidate_get_base_port(struct sipe_backend_candidate *candidate);
 472 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
 473 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
 474 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
 475 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
 476 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
 477 GList* sipe_backend_get_local_candidates(struct sipe_backend_media *media,
 478                                          struct sipe_backend_stream *stream);
 479 void sipe_backend_media_accept(struct sipe_backend_media *media, gboolean local);
 480 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
 481 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
 482
 483 /** NETWORK ******************************************************************/
 484
 485 const gchar *sipe_backend_network_ip_address(void);
 486
 487 struct sipe_backend_listendata;
 488
 489 typedef void (*sipe_listen_start_cb)(unsigned short port, gpointer data);
 490 typedef void (*sipe_client_connected_cb)(struct sipe_backend_fd *fd, gpointer data);
 491
 492 struct sipe_backend_listendata *
 493 sipe_backend_network_listen_range(unsigned short port_min,
 494                                   unsigned short port_max,
 495                                   sipe_listen_start_cb listen_cb,
 496                                   sipe_client_connected_cb connect_cb,
 497                                   gpointer data);
 498 void sipe_backend_network_listen_cancel(struct sipe_backend_listendata *ldata);
 499
 500 gboolean sipe_backend_fd_is_valid(struct sipe_backend_fd *fd);
 501 void sipe_backend_fd_free(struct sipe_backend_fd *fd);
 502
 503 /** NOTIFICATIONS *************************************************************/
 504
 505 void sipe_backend_notify_message_error(struct sipe_core_public *sipe_public,
 506                                        struct sipe_backend_chat_session *backend_session,
 507                                        const gchar *who,
 508                                        const gchar *message);
 509 void sipe_backend_notify_message_info(struct sipe_core_public *sipe_public,
 510                                       struct sipe_backend_chat_session *backend_session,
 511                                       const gchar *who,
 512                                       const gchar *message);
 513
 514 /**
 515  * @param msg  error message. Maybe @NULL
 516  */
 517 void sipe_backend_notify_error(struct sipe_core_public *sipe_public,
 518                                const gchar *title,
 519                                const gchar *msg);
 520
 521 /** SCHEDULE *****************************************************************/
 522
 523 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
 524                                        guint timeout,
 525                                        gpointer data);
 526 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
 527                                         guint timeout,
 528                                         gpointer data);
 529 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
 530                                   gpointer data);
 531
 532 /** SEARCH *******************************************************************/
 533
 534 struct sipe_backend_search_results;
 535
 536 struct sipe_backend_search_results *sipe_backend_search_results_start(struct sipe_core_public *sipe_public);
 537 void sipe_backend_search_results_add(struct sipe_core_public *sipe_public,
 538                                      struct sipe_backend_search_results *results,
 539                                      const gchar *uri,
 540                                      const gchar *name,
 541                                      const gchar *company,
 542                                      const gchar *country,
 543                                      const gchar *email);
 544 void sipe_backend_search_results_finalize(struct sipe_core_public *sipe_public,
 545                                           struct sipe_backend_search_results *results,
 546                                           const gchar *description,
 547                                           gboolean more);
 548
 549 /** SETTINGS *****************************************************************/
 550
 551 typedef enum {
 552   SIPE_SETTING_EMAIL_URL = 0,
 553   SIPE_SETTING_EMAIL_LOGIN,
 554   SIPE_SETTING_EMAIL_PASSWORD,
 555   SIPE_SETTING_GROUPCHAT_USER,
 556   SIPE_SETTING_USER_AGENT,
 557   SIPE_SETTING_LAST
 558 } sipe_setting;
 559 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
 560                                   sipe_setting type);
 561
 562 /** STATUS *******************************************************************/
 563
 564 guint sipe_backend_status(struct sipe_core_public *sipe_public);
 565 gboolean sipe_backend_status_and_note(struct sipe_core_public *sipe_public,
 566                                       guint activity,
 567                                       const gchar *message);
 568
 569 /** TRANSPORT ****************************************************************/
 570
 571 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
 572 typedef void transport_input_cb(struct sipe_transport_connection *conn);
 573 typedef void transport_error_cb(struct sipe_transport_connection *conn,
 574                                 const gchar *msg);
 575
 576 typedef struct {
 577         guint type;
 578         const gchar *server_name;
 579         guint server_port;
 580         gpointer user_data;
 581         transport_connected_cb *connected;
 582         transport_input_cb *input;
 583         transport_error_cb *error;
 584 } sipe_connect_setup;
 585 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
 586                                                                  const sipe_connect_setup *setup);
 587 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
 588 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
 589                                     const gchar *buffer);
 590 void sipe_backend_transport_flush(struct sipe_transport_connection *conn);
 591
 592 /** USER *********************************************************************/
 593
 594 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
 595                                        const gchar *from);
 596 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
 597                                             const gchar *from);
 598
 599 /**
 600  * Present a query that is to be accepted or declined by the user
 601  *
 602  * @param sipe_public   The handle representing the protocol instance
 603  * @param message       Text of the query to be shown to user
 604  * @param accept_label  Label to be displayed on UI control that accepts query
 605  * @param decline_label Label to be displayed on UI control that declines query
 606  * @param key           Opaque handle uniquely identifying the query. Backend
 607  *                      should store it for the case SIPE core requests the
 608  *                      query to be closed prematurely.
 609  */
 610 void sipe_backend_user_ask(struct sipe_core_public *sipe_public,
 611                            const gchar *message,
 612                            const gchar *accept_label,
 613                            const gchar *decline_label,
 614                            gpointer key);
 615
 616 /**
 617  * Closes the pending user query
 618  *
 619  * @param key Opaque handle uniquely identifying the query.
 620  */
 621 void sipe_backend_user_close_ask(gpointer key);
 622
 623 /** BUDDIES ******************************************************************/
 624
 625 /*
 626  * sipe_backend_buddy_get/set_string(): properties a buddy can have
 627  * sipe_backend_buddy_info_add():       mapped, e.g. to a string label
 628  */
 629 typedef enum
 630 {
 631         SIPE_BUDDY_INFO_DISPLAY_NAME = 0,
 632         SIPE_BUDDY_INFO_JOB_TITLE,
 633         SIPE_BUDDY_INFO_CITY,
 634         SIPE_BUDDY_INFO_STATE,
 635         SIPE_BUDDY_INFO_OFFICE,
 636         SIPE_BUDDY_INFO_DEPARTMENT,
 637         SIPE_BUDDY_INFO_COUNTRY,
 638         SIPE_BUDDY_INFO_WORK_PHONE,
 639         SIPE_BUDDY_INFO_WORK_PHONE_DISPLAY,
 640         SIPE_BUDDY_INFO_COMPANY,
 641         SIPE_BUDDY_INFO_EMAIL,
 642         SIPE_BUDDY_INFO_SITE,
 643         SIPE_BUDDY_INFO_ZIPCODE,
 644         SIPE_BUDDY_INFO_STREET,
 645         SIPE_BUDDY_INFO_MOBILE_PHONE,
 646         SIPE_BUDDY_INFO_MOBILE_PHONE_DISPLAY,
 647         SIPE_BUDDY_INFO_HOME_PHONE,
 648         SIPE_BUDDY_INFO_HOME_PHONE_DISPLAY,
 649         SIPE_BUDDY_INFO_OTHER_PHONE,
 650         SIPE_BUDDY_INFO_OTHER_PHONE_DISPLAY,
 651         SIPE_BUDDY_INFO_CUSTOM1_PHONE,
 652         SIPE_BUDDY_INFO_CUSTOM1_PHONE_DISPLAY,
 653         SIPE_BUDDY_INFO_ALIAS,  /* only for sipe_backend_buddy_info_add() */
 654         SIPE_BUDDY_INFO_DEVICE, /* only for sipe_backend_buddy_info_add() */
 655 } sipe_buddy_info_fields;
 656
 657 /* Opaque token */
 658 typedef void* sipe_backend_buddy;
 659
 660 /**
 661  * Find a buddy in the given group of the buddy list, or anywhere on the
 662  * list if @group_name is empty
 663  *
 664  * @param sipe_public The handle representing the protocol instance making the call
 665  * @param buddy_name The name of the buddy
 666  * @param group_name The name of the group to look in, or NULL for any group
 667  * @return opaque handle to the buddy, or NULL if no buddy found
 668  */
 669 sipe_backend_buddy sipe_backend_buddy_find(struct sipe_core_public *sipe_public,
 670                                            const gchar *buddy_name,
 671                                            const gchar *group_name);
 672
 673 /*
 674  * Find all named buddies in the given group of the buddy list, or anywhere on the
 675  * list if @group_name is empty; or all buddies if @name is empty
 676  *
 677  * @param sipe_public The handle representing the protocol instance making the call
 678  * @param name The name of the buddy
 679  * @param group_name The name of the group to look in, or NULL for any group
 680  * @return GSList of opaque handles to the buddies
 681  */
 682 GSList* sipe_backend_buddy_find_all(struct sipe_core_public *sipe_public,
 683                                     const gchar *buddy_name,
 684                                     const gchar *group_name);
 685
 686 /**
 687  * Gets the name of a contact.
 688  *
 689  * @param sipe_public The handle representing the protocol instance making the call
 690  * @param who The opaque handle to the contact as found by find_buddy
 691  * @return The name. Must be freed.
 692  */
 693 gchar* sipe_backend_buddy_get_name(struct sipe_core_public *sipe_public,
 694                                    const sipe_backend_buddy who);
 695
 696 /**
 697  * Gets the alias for a contact.
 698  *
 699  * @param sipe_public The handle representing the protocol instance making the call
 700  * @param who The opaque handle to the contact as found by find_buddy
 701  * @return The alias. Must be gfree'd.
 702  */
 703 gchar* sipe_backend_buddy_get_alias(struct sipe_core_public *sipe_public,
 704                                     const sipe_backend_buddy who);
 705
 706 /**
 707  * Gets the server alias for a contact.
 708  *
 709  * @param sipe_public The handle representing the protocol instance making the call
 710  * @param who The opaque handle to the contact as found by find_buddy
 711  * @return The alias. Must be freed.
 712  */
 713 gchar* sipe_backend_buddy_get_server_alias(struct sipe_core_public *sipe_public,
 714                                            const sipe_backend_buddy who);
 715
 716 /**
 717  * Gets the local alias for a contact
 718  *
 719  * @param sipe_public The handle representing the protocol instance making the call
 720  * @param uri         the budyy name
 721  *
 722  * @return the alias. Must be @g_free()'d.
 723  */
 724 gchar *sipe_backend_buddy_get_local_alias(struct sipe_core_public *sipe_public,
 725                                           const sipe_backend_buddy who);
 726
 727 /**
 728  * Gets the name of the group a contact belongs to.
 729  *
 730  * @param sipe_public The handle representing the protocol instance making the call
 731  * @param who The opaque handle to the contact as found by find_buddy
 732  * @return The name. Must be freed.
 733  */
 734 gchar* sipe_backend_buddy_get_group_name(struct sipe_core_public *sipe_public,
 735                                          const sipe_backend_buddy who);
 736
 737 /**
 738  * Called to retrieve a buddy-specific setting.
 739  *
 740  * @param sipe_public The handle representing the protocol instance making the call
 741  * @param buddy The handle representing the buddy
 742  * @param key The name of the setting
 743  * @return The value of the setting. Must be freed.
 744  */
 745 gchar* sipe_backend_buddy_get_string(struct sipe_core_public *sipe_public,
 746                                      sipe_backend_buddy buddy,
 747                                      const sipe_buddy_info_fields key);
 748
 749 /**
 750  * Called to set a buddy-specific setting.
 751  *
 752  * @param sipe_public The handle representing the protocol instance making the call
 753  * @param buddy The handle representing the buddy
 754  * @param key The name of the setting
 755  * @param val The value to set
 756  */
 757 void sipe_backend_buddy_set_string(struct sipe_core_public *sipe_public,
 758                                    sipe_backend_buddy buddy,
 759                                    const sipe_buddy_info_fields key,
 760                                    const gchar *val);
 761
 762 /**
 763  * Get the status token for a contact
 764  *
 765  * @param sipe_public The handle representing the protocol instance making the call
 766  * @param uri         SIP URI of the contact
 767  *
 768  * @return activity
 769  */
 770 guint sipe_backend_buddy_get_status(struct sipe_core_public *sipe_public,
 771                                     const gchar *uri);
 772
 773 /**
 774  * Sets the alias for a contact.
 775  *
 776  * @param sipe_public The handle representing the protocol instance making the call
 777  * @param who The opaque handle to the contact as found by find_buddy
 778  * @param alias The location where the alias will be put
 779  * case. FALSE if the buddy was not found. The value of alias will not be changed.
 780  */
 781 void sipe_backend_buddy_set_alias(struct sipe_core_public *sipe_public,
 782                                   const sipe_backend_buddy who,
 783                                   const gchar *alias);
 784
 785 /**
 786  * Sets the server alias for a contact.
 787  *
 788  * @param sipe_public The handle representing the protocol instance making the call
 789  * @param who The opaque handle to the contact as found by find_buddy
 790  * @param alias The server alias of the contact
 791  */
 792 void sipe_backend_buddy_set_server_alias(struct sipe_core_public *sipe_public,
 793                                          const sipe_backend_buddy who,
 794                                          const gchar *alias);
 795
 796 /**
 797  * Add a contact to the buddy list
 798  *
 799  * @param sipe_public The handle representing the protocol instance making the call
 800  * @param name The name of the contact
 801  * @param alias The alias of the contact
 802  * @param groupname The name of the group to add this contact to
 803  * @return A handle to the newly created buddy
 804  */
 805 sipe_backend_buddy sipe_backend_buddy_add(struct sipe_core_public *sipe_public,
 806                                           const gchar *name,
 807                                           const gchar *alias,
 808                                           const gchar *groupname);
 809
 810 /**
 811  * Remove a contact from the buddy list
 812  *
 813  * @param sipe_public The handle representing the protocol instance making the call
 814  * @param who The opaque handle to the contact as found by find_buddy
 815  */
 816 void sipe_backend_buddy_remove(struct sipe_core_public *sipe_public,
 817                                const sipe_backend_buddy who);
 818
 819 /**
 820  * Notifies the user that a remote user has wants to add the local user to his
 821  * or her buddy list and requires authorization to do so.
 822  *
 823  * @param sipe_public The handle representing the protocol instance making the call
 824  * @param who The name of the user that added this account
 825  * @param alias The optional alias of the remote user
 826  * @param on_list True if the user is already in our list
 827  * @param auth_cb The callback called when the local user accepts
 828  * @param deny_cb The callback called when the local user rejects
 829  * @param data Data to be passed back to the above callbacks
 830  */
 831 typedef void (*sipe_backend_buddy_request_authorization_cb)(void *);
 832
 833 void sipe_backend_buddy_request_add(struct sipe_core_public *sipe_public,
 834                                     const gchar *who,
 835                                     const gchar *alias);
 836
 837 void sipe_backend_buddy_request_authorization(struct sipe_core_public *sipe_public,
 838                                               const gchar *who,
 839                                               const gchar *alias,
 840                                               gboolean on_list,
 841                                               sipe_backend_buddy_request_authorization_cb auth_cb,
 842                                               sipe_backend_buddy_request_authorization_cb deny_cb,
 843                                               gpointer data);
 844
 845 gboolean sipe_backend_buddy_is_blocked(struct sipe_core_public *sipe_public,
 846                                        const gchar *who);
 847
 848 void sipe_backend_buddy_set_blocked_status(struct sipe_core_public *sipe_public,
 849                                            const gchar *who,
 850                                            gboolean blocked);
 851
 852 void sipe_backend_buddy_set_status(struct sipe_core_public *sipe_public,
 853                                    const gchar *who,
 854                                    guint activity);
 855
 856 /**
 857  * Called when a new internal group is about to be added. If this returns FALSE,
 858  * the group will not be added.
 859  *
 860  * @param sipe_public The handle representing the protocol instance making the call
 861  * @param group The group being added
 862  * @return TRUE if everything is ok, FALSE if the group should not be added
 863  */
 864 gboolean sipe_backend_buddy_group_add(struct sipe_core_public *sipe_public,
 865                                       const gchar *group_name);
 866
 867 /**
 868  * Present requested buddy information to the user
 869  */
 870 struct sipe_backend_buddy_info;
 871 struct sipe_backend_buddy_info *sipe_backend_buddy_info_start(struct sipe_core_public *sipe_public);
 872 void sipe_backend_buddy_info_add(struct sipe_core_public *sipe_public,
 873                                  struct sipe_backend_buddy_info *info,
 874                                  sipe_buddy_info_fields key,
 875                                  const gchar *value);
 876 void sipe_backend_buddy_info_break(struct sipe_core_public *sipe_public,
 877                                    struct sipe_backend_buddy_info *info);
 878 void sipe_backend_buddy_info_finalize(struct sipe_core_public *sipe_public,
 879                                       struct sipe_backend_buddy_info *info,
 880                                       const gchar *uri);
 881
 882 struct sipe_backend_buddy_tooltip;
 883 void sipe_backend_buddy_tooltip_add(struct sipe_core_public *sipe_public,
 884                                     struct sipe_backend_buddy_tooltip *tooltip,
 885                                     const gchar *description,
 886                                     const gchar *value);
 887
 888 /**
 889  * Buddy menu creation
 890  */
 891 enum sipe_buddy_menu_type {
 892         SIPE_BUDDY_MENU_MAKE_CHAT_LEADER = 0,
 893         SIPE_BUDDY_MENU_REMOVE_FROM_CHAT,
 894         SIPE_BUDDY_MENU_INVITE_TO_CHAT,
 895         SIPE_BUDDY_MENU_NEW_CHAT,
 896         SIPE_BUDDY_MENU_MAKE_CALL,
 897         SIPE_BUDDY_MENU_SEND_EMAIL,
 898         SIPE_BUDDY_MENU_ACCESS_LEVEL_HELP,
 899         SIPE_BUDDY_MENU_CHANGE_ACCESS_LEVEL,
 900         SIPE_BUDDY_MENU_ADD_NEW_DOMAIN,
 901         SIPE_BUDDY_MENU_TYPES
 902 };
 903
 904 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_start(struct sipe_core_public *sipe_public);
 905 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_add(struct sipe_core_public *sipe_public,
 906                                                             struct sipe_backend_buddy_menu *menu,
 907                                                             const gchar *label,
 908                                                             enum sipe_buddy_menu_type type,
 909                                                             gpointer parameter);
 910 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_separator(struct sipe_core_public *sipe_public,
 911                                                                   struct sipe_backend_buddy_menu *menu,
 912                                                                   const gchar *label);
 913 struct sipe_backend_buddy_menu *sipe_backend_buddy_sub_menu_add(struct sipe_core_public *sipe_public,
 914                                                                 struct sipe_backend_buddy_menu *menu,
 915                                                                 const gchar *label,
 916                                                                 struct sipe_backend_buddy_menu *sub);
 917
 918 #ifdef __cplusplus
 919 }
 920 #endif
 921
 922 /*
 923   Local Variables:
 924   mode: c
 925   c-file-style: "bsd"
 926   indent-tabs-mode: t
 927   tab-width: 8
 928   End:
 929 */