src/api/sipe-core.h

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