src/api/sipe-core.h

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