src/api/sipe-core.h

   1 /**
   2  * @file sipe-core.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  * Backend -> SIPE Core API - functions called by backend 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 interrupted by another thread calling
  34  * sipe_core_xxx() while the first thread has entered the SIPE core through
  35  * a sipe_core_xxx() function.
  36  *
  37  ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
  38  */
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /**
  45  * Transport type
  46  */
  47 #define SIPE_TRANSPORT_AUTO 0
  48 #define SIPE_TRANSPORT_TLS  1
  49 #define SIPE_TRANSPORT_TCP  2
  50
  51 /**
  52  * Transport connection (public part)
  53  *
  54  * The receiver in the backend fills "buffer". The backend has to zero
  55  * terminate the buffer before calling the processing function in the core.
  56  *
  57  * The processing function in the core can remove content from the buffer.
  58  * It has to update buffer_used accordingly.
  59  *
  60  */
  61 struct sipe_transport_connection {
  62         gpointer user_data;
  63         gchar *buffer;
  64         gsize buffer_used;        /* 0 < buffer_used < buffer_length */
  65         gsize buffer_length;      /* read-only */
  66         guint type;               /* read-only */
  67         guint client_port;        /* read-only */
  68 };
  69
  70 /**
  71  * Opaque data type for chat session
  72  */
  73 struct sipe_chat_session;
  74
  75 /**
  76  * File transport (public part)
  77  */
  78 struct sipe_file_transfer {
  79         struct sipe_backend_file_transfer *backend_private;
  80
  81         void (* ft_init)(struct sipe_file_transfer *ft, const gchar *filename,
  82                          gsize size, const gchar *who);
  83         void (* ft_start)(struct sipe_file_transfer *ft, gsize total_size);
  84         gssize (* ft_read)(struct sipe_file_transfer *ft, guchar **buffer,
  85                            gsize bytes_remaining, gsize bytes_available);
  86         gssize (* ft_write)(struct sipe_file_transfer *ft, const guchar *buffer,
  87                             gsize size);
  88         gboolean (* ft_end)(struct sipe_file_transfer *ft);
  89         void (* ft_request_denied)(struct sipe_file_transfer *ft);
  90         void (* ft_cancelled)(struct sipe_file_transfer *ft);
  91 };
  92
  93 /**
  94  * Opaque data type for backend private data.
  95  * The backend is responsible to allocate and free it.
  96  */
  97 struct sipe_backend_private;
  98
  99 /**
 100  * SIP transport authentication scheme
 101  */
 102 #define SIPE_AUTHENTICATION_TYPE_UNSET     0
 103 #define SIPE_AUTHENTICATION_TYPE_BASIC     1 /* internal use only */
 104 #define SIPE_AUTHENTICATION_TYPE_NTLM      2
 105 #define SIPE_AUTHENTICATION_TYPE_KERBEROS  3
 106 #define SIPE_AUTHENTICATION_TYPE_NEGOTIATE 4 /* internal use only */
 107 #define SIPE_AUTHENTICATION_TYPE_TLS_DSK   5
 108 #define SIPE_AUTHENTICATION_TYPE_AUTOMATIC 6 /* always last */
 109
 110 /**
 111  * Flags
 112  */
 113 /* user disabled calendar information publishing */
 114 #define SIPE_CORE_FLAG_DONT_PUBLISH 0x00000001
 115
 116 #define SIPE_CORE_FLAG_IS(flag)    \
 117         ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
 118 #define SIPE_CORE_FLAG_SET(flag)   \
 119         (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
 120 #define SIPE_CORE_FLAG_UNSET(flag) \
 121         (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
 122
 123 /**
 124  * Byte length of cryptographic key for call encryption.
 125  */
 126 #define SIPE_SRTP_KEY_LEN 30
 127
 128 /**
 129  * Public part of the Sipe data structure
 130  *
 131  * This part contains the information needed by the core and the backend.
 132  */
 133 struct sipe_core_public {
 134         /**
 135          * This points to the private data for the backend.
 136          * The backend is responsible to allocate and free it.
 137          */
 138         struct sipe_backend_private *backend_private;
 139
 140         /* flags (see above) */
 141         guint32 flags;
 142
 143         /* user information */
 144         gchar *sip_name;
 145         gchar *sip_domain;
 146
 147         /* server information */
 148         /* currently nothing */
 149 };
 150
 151 /**
 152  * Initialize & destroy functions for the SIPE core
 153  * Should be called on loading and unloading of the plugin.
 154  */
 155 void sipe_core_init(const char *locale_dir);
 156 void sipe_core_destroy(void);
 157
 158 /** Utility functions exported by the core to backends ***********************/
 159 gboolean sipe_strequal(const gchar *left, const gchar *right);
 160
 161 GSList *
 162 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
 163
 164 const gchar *
 165 sipe_utils_nameval_find(const GSList *list, const gchar *name);
 166
 167 const gchar *
 168 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
 169
 170 void
 171 sipe_utils_nameval_free(GSList *list);
 172
 173 gchar *sip_uri_from_name(const gchar *name);
 174 gchar *sip_uri_if_valid(const gchar *string);
 175
 176 /*****************************************************************************/
 177
 178 /**
 179  * Other functions (need to be sorted once structure becomes clear.
 180  */
 181
 182 /* Get translated about string. Must be g_free'd(). */
 183 gchar *sipe_core_about(void);
 184
 185 /* Execute a scheduled action */
 186 void sipe_core_schedule_execute(gpointer data);
 187
 188 /* menu actions */
 189 void sipe_core_update_calendar(struct sipe_core_public *sipe_public);
 190 void sipe_core_reset_status(struct sipe_core_public *sipe_public);
 191
 192 /* access levels */
 193 void sipe_core_change_access_level_from_container(struct sipe_core_public *sipe_public,
 194                                                   gpointer parameter);
 195 void sipe_core_change_access_level_for_domain(struct sipe_core_public *sipe_public,
 196                                               const gchar *domain,
 197                                               guint index);
 198
 199 /**
 200  * Activity
 201  *   - core:    maps this to OCS protocol values
 202  *              maps this to translated descriptions
 203  *   - backend: maps this to backend status values
 204  *              backend token string can be used as "ID" in protocol
 205  *
 206  * This is passed back-and-forth and therefore defined as list, not as enum.
 207  * Can be used as array index
 208  */
 209 #define SIPE_ACTIVITY_UNSET        0
 210 #define SIPE_ACTIVITY_AVAILABLE    1
 211 #define SIPE_ACTIVITY_ONLINE       2
 212 #define SIPE_ACTIVITY_INACTIVE     3
 213 #define SIPE_ACTIVITY_BUSY         4
 214 #define SIPE_ACTIVITY_BUSYIDLE     5
 215 #define SIPE_ACTIVITY_DND          6
 216 #define SIPE_ACTIVITY_BRB          7
 217 #define SIPE_ACTIVITY_AWAY         8
 218 #define SIPE_ACTIVITY_LUNCH        9
 219 #define SIPE_ACTIVITY_INVISIBLE   10
 220 #define SIPE_ACTIVITY_OFFLINE     11
 221 #define SIPE_ACTIVITY_ON_PHONE    12
 222 #define SIPE_ACTIVITY_IN_CONF     13
 223 #define SIPE_ACTIVITY_IN_MEETING  14
 224 #define SIPE_ACTIVITY_OOF         15
 225 #define SIPE_ACTIVITY_URGENT_ONLY 16
 226 #define SIPE_ACTIVITY_NUM_TYPES   17 /* use to define array size */
 227
 228 const gchar *sipe_core_activity_description(guint type);
 229
 230 /* buddy actions */
 231 /**
 232  * Get status text for buddy.
 233  *
 234  * @param sipe_public Sipe core public data structure.
 235  * @param uri         SIP URI of the buddy
 236  * @param activity    activity value for buddy
 237  * @param status_text backend-specific buddy status text for activity.
 238  *
 239  * @return HTML status text for the buddy or NULL. Must be g_free()'d.
 240  */
 241 gchar *sipe_core_buddy_status(struct sipe_core_public *sipe_public,
 242                               const gchar *uri,
 243                               guint activity,
 244                               const gchar *status_text);
 245
 246 void sipe_core_buddy_got_status(struct sipe_core_public *sipe_public,
 247                                 const gchar *uri,
 248                                 guint activity);
 249
 250 /**
 251  * Trigger generation of buddy information label/text pairs
 252  *
 253  * @param sipe_public Sipe core public data structure.
 254  * @param uri         SIP URI of the buddy
 255  * @param status_text backend-specific buddy status text for ID.
 256  * @param is_online   backend considers buddy to be online.
 257  * @param tooltip     opaque backend identifier for tooltip info. This is the
 258  *                    parameter given to @c sipe_backend_buddy_tooltip_add()
 259  */
 260 struct sipe_backend_buddy_tooltip;
 261 void sipe_core_buddy_tooltip_info(struct sipe_core_public *sipe_public,
 262                                   const gchar *uri,
 263                                   const gchar *status_name,
 264                                   gboolean is_online,
 265                                   struct sipe_backend_buddy_tooltip *tooltip);
 266
 267 /**
 268  * Add a buddy
 269  *
 270  * @param sipe_public Sipe core public data structure
 271  * @param uri         SIP URI of the buddy
 272  * @param group_name  backend-specific group name
 273  */
 274 void sipe_core_buddy_add(struct sipe_core_public *sipe_public,
 275                          const gchar *uri,
 276                          const gchar *group_name);
 277
 278 /**
 279  * Remove a buddy
 280  *
 281  * @param sipe_public Sipe core public data structure
 282  * @param uri         SIP URI of the buddy
 283  * @param group_name  backend-specific group name
 284  */
 285 void sipe_core_buddy_remove(struct sipe_core_public *sipe_public,
 286                             const gchar *uri,
 287                             const gchar *group_name);
 288
 289 void sipe_core_contact_allow_deny(struct sipe_core_public *sipe_public,
 290                                   const gchar *who,
 291                                   gboolean allow);
 292 void sipe_core_group_set_alias(struct sipe_core_public *sipe_public,
 293                                const gchar *who,
 294                                const gchar *alias);
 295
 296 /**
 297  * Setup core data
 298  */
 299 struct sipe_core_public *sipe_core_allocate(const gchar *signin_name,
 300                                             gboolean sso,
 301                                             const gchar *login_account,
 302                                             const gchar *password,
 303                                             const gchar *email,
 304                                             const gchar *email_url,
 305                                             const gchar **errmsg);
 306 void sipe_core_deallocate(struct sipe_core_public *sipe_public);
 307
 308 /**
 309  * Check if SIP authentication scheme requires a password
 310  *
 311  * NOTE: this can be called *BEFORE* @c sipe_core_allocate()!
 312  *
 313  * @param authentication SIP transport authentication type
 314  * @param sso            TRUE if user selected Single-Sign On
 315  *
 316  * @return TRUE if password is required
 317  */
 318 gboolean sipe_core_transport_sip_requires_password(guint authentication,
 319                                                    gboolean sso);
 320
 321 /**
 322  * Connect to SIP server
 323  */
 324 void sipe_core_transport_sip_connect(struct sipe_core_public *sipe_public,
 325                                      guint transport,
 326                                      guint authentication,
 327                                      const gchar *server,
 328                                      const gchar *port);
 329
 330 /**
 331  * Get SIP server host name
 332  *
 333  * @param sipe_public Sipe core public data structure
 334  *
 335  * @return server host name (may be @c NULL if not fully connected yet)
 336  */
 337 const gchar *sipe_core_transport_sip_server_name(struct sipe_core_public *sipe_public);
 338
 339 /**
 340  * Get chat ID, f.ex. group chat URI
 341  */
 342 const gchar *sipe_core_chat_id(struct sipe_core_public *sipe_public,
 343                                struct sipe_chat_session *chat_session);
 344
 345 /**
 346  * Invite to chat
 347  */
 348 void sipe_core_chat_invite(struct sipe_core_public *sipe_public,
 349                            struct sipe_chat_session *chat_session,
 350                            const char *name);
 351
 352 /**
 353  * Rejoin a chat after connection re-establishment
 354  */
 355 void sipe_core_chat_rejoin(struct sipe_core_public *sipe_public,
 356                            struct sipe_chat_session *chat_session);
 357
 358 /**
 359  * Leave a chat
 360  */
 361 void sipe_core_chat_leave(struct sipe_core_public *sipe_public,
 362                           struct sipe_chat_session *chat_session);
 363
 364 /**
 365  * Send message to chat
 366  */
 367 void sipe_core_chat_send(struct sipe_core_public *sipe_public,
 368                          struct sipe_chat_session *chat_session,
 369                          const char *what);
 370
 371 /**
 372  * Check chat lock status
 373  */
 374 typedef enum {
 375         SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED = 0,
 376         SIPE_CHAT_LOCK_STATUS_UNLOCKED,
 377         SIPE_CHAT_LOCK_STATUS_LOCKED
 378 } sipe_chat_lock_status;
 379 sipe_chat_lock_status sipe_core_chat_lock_status(struct sipe_core_public *sipe_public,
 380                                                  struct sipe_chat_session *chat_session);
 381
 382 /**
 383  * Lock chat
 384  */
 385 void sipe_core_chat_modify_lock(struct sipe_core_public *sipe_public,
 386                                 struct sipe_chat_session *chat_session,
 387                                 const gboolean locked);
 388
 389 /**
 390  * Create new session with Focus URI
 391  *
 392  * @param sipe_public (in) SIPE core data.
 393  * @param focus_uri (in) focus URI string
 394  */
 395 void sipe_core_conf_create(struct sipe_core_public *sipe_public,
 396                            const gchar *focus_uri,
 397                            const gchar *organizer,
 398                            const gchar *meeting_id);
 399
 400 /* buddy menu callback: parameter == chat_session */
 401 void sipe_core_conf_make_leader(struct sipe_core_public *sipe_public,
 402                                 gpointer parameter,
 403                                 const gchar *buddy_name);
 404 void sipe_core_conf_remove_from(struct sipe_core_public *sipe_public,
 405                                 gpointer parameter,
 406                                 const gchar *buddy_name);
 407
 408 gchar *
 409 sipe_core_conf_entry_info(struct sipe_core_public *sipe_public,
 410                           struct sipe_chat_session *chat_session);
 411
 412 /* call control (CSTA) */
 413 void sipe_core_buddy_make_call(struct sipe_core_public *sipe_public,
 414                                const gchar *phone);
 415
 416 /* media */
 417 void sipe_core_media_initiate_call(struct sipe_core_public *sipe_public,
 418                                    const char *participant,
 419                                    gboolean with_video);
 420 struct sipe_media_call;
 421 struct sipe_media_stream *
 422 sipe_core_media_get_stream_by_id(struct sipe_media_call *call, const gchar *id);
 423
 424 /**
 425  * Called by media backend after a candidate pair for a media stream component
 426  * has been established.
 427  *
 428  * @param stream (in) SIPE media stream data.
 429  */
 430 void
 431 sipe_core_media_stream_candidate_pair_established(struct sipe_media_stream *stream);
 432
 433 void
 434 sipe_core_media_stream_readable(struct sipe_media_stream *stream);
 435
 436 /**
 437  * Called by media backend when a @c SIPE_MEDIA_APPLICATION stream changes its
 438  * state between writable and unwritable.
 439  *
 440  * @param stream (in) SIPE media stream data.
 441  * @param writable (in) @c TRUE if stream has become writable, otherwise
 442  *                 @c FALSE.
 443  */
 444 void
 445 sipe_core_media_stream_writable(struct sipe_media_stream *stream,
 446                                 gboolean writable);
 447
 448 /**
 449  * Connects to a conference call specified by given chat session
 450  *
 451  * @param sipe_public (in) SIPE core data.
 452  * @param chat_session (in) chat session structure
 453  */
 454 void sipe_core_media_connect_conference(struct sipe_core_public *sipe_public,
 455                                         struct sipe_chat_session *chat_session);
 456
 457 /**
 458  * Retrieves the media call in progress
 459  *
 460  * The function checks only for voice and video calls, ignoring other types of
 461  * data transfers.
 462  *
 463  * @param sipe_public (in) SIPE core data.
 464  *
 465  * @return @c sipe_media_call structure or @c NULL if call is not in progress.
 466  */
 467 struct sipe_media_call *
 468 sipe_core_media_get_call(struct sipe_core_public *sipe_public);
 469
 470 /**
 471  * Initiates a call with given phone number
 472  *
 473  * @param sipe_public (in) SIPE core data.
 474  * @parem phone_number (in) a mobile or landline phone number, i.e. +46123456
 475  */
 476 void sipe_core_media_phone_call(struct sipe_core_public *sipe_public,
 477                                 const gchar *phone_number);
 478
 479 /**
 480  * Checks voice quality by making a call to the test service
 481  *
 482  * @param sipe_public (in) SIPE core data.
 483  */
 484 void sipe_core_media_test_call(struct sipe_core_public *sipe_public);
 485
 486 /* file transfer */
 487 struct sipe_file_transfer *
 488 sipe_core_ft_create_outgoing(struct sipe_core_public *sipe_public,
 489                              const gchar *who,
 490                              const gchar *file);
 491
 492 /* group chat */
 493 gboolean sipe_core_groupchat_query_rooms(struct sipe_core_public *sipe_public);
 494 void sipe_core_groupchat_join(struct sipe_core_public *sipe_public,
 495                               const gchar *uri);
 496
 497 /* IM */
 498 void sipe_core_im_send(struct sipe_core_public *sipe_public,
 499                        const gchar *who,
 500                        const gchar *what);
 501 void sipe_core_im_close(struct sipe_core_public *sipe_public,
 502                         const gchar *who);
 503
 504 /* user */
 505 void sipe_core_user_feedback_typing(struct sipe_core_public *sipe_public,
 506                                     const gchar *to,
 507                                     gboolean typing);
 508
 509 void sipe_core_user_ask_cb(gpointer key, gboolean accepted);
 510
 511 /* groups */
 512 void sipe_core_group_rename(struct sipe_core_public *sipe_public,
 513                             const gchar *old_name,
 514                             const gchar *new_name);
 515
 516 void sipe_core_group_remove(struct sipe_core_public *sipe_public,
 517                             const gchar *name);
 518
 519 /* buddies */
 520 void sipe_core_buddy_group(struct sipe_core_public *sipe_public,
 521                            const gchar *who,
 522                            const gchar *old_group_name,
 523                            const gchar *new_group_name);
 524
 525 struct sipe_backend_search_token;
 526 void sipe_core_buddy_search(struct sipe_core_public *sipe_public,
 527                             struct sipe_backend_search_token *token,
 528                             const gchar *given_name,
 529                             const gchar *surname,
 530                             const gchar *email,
 531                             const gchar *sipid,
 532                             const gchar *company,
 533                             const gchar *country);
 534
 535 void sipe_core_buddy_get_info(struct sipe_core_public *sipe_public,
 536                               const gchar *who);
 537
 538 void sipe_core_buddy_new_chat(struct sipe_core_public *sipe_public,
 539                               const gchar *who);
 540 void sipe_core_buddy_send_email(struct sipe_core_public *sipe_public,
 541                                 const gchar *who);
 542
 543 struct sipe_backend_buddy_menu;
 544 struct sipe_backend_buddy_menu *sipe_core_buddy_create_menu(struct sipe_core_public *sipe_public,
 545                                                             const gchar *buddy_name,
 546                                                             struct sipe_backend_buddy_menu *menu);
 547
 548 void sipe_core_buddy_menu_free(struct sipe_core_public *sipe_public);
 549
 550 /**
 551  * User/Machine has changed the user status
 552  *
 553  * NOTE: must *NEVER* be triggered by @c sipe_backend_status_and_note()!
 554  *
 555  * @param sipe_public   The handle representing the protocol instance
 556  * @param set_by_user   @c TRUE if status has been changed by user
 557  * @param activity      New activity
 558  * @param message       New note text
 559  */
 560 void sipe_core_status_set(struct sipe_core_public *sipe_public,
 561                           gboolean set_by_user,
 562                           guint activity,
 563                           const gchar *note);
 564
 565 #ifdef __cplusplus
 566 }
 567 #endif
 568
 569 /*
 570   Local Variables:
 571   mode: c
 572   c-file-style: "bsd"
 573   indent-tabs-mode: t
 574   tab-width: 8
 575   End:
 576 */