src/api/sipe-core.h

   1 /**
   2  * @file sipe-core.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  * 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  * Activity
  46  *   - core:    maps this to OCS protocol values
  47  *   - backend: maps this to backend status values
  48  */
  49 typedef enum
  50 {
  51         SIPE_ACTIVITY_UNSET = 0,
  52         SIPE_ACTIVITY_ONLINE,
  53         SIPE_ACTIVITY_INACTIVE,
  54         SIPE_ACTIVITY_BUSY,
  55         SIPE_ACTIVITY_BUSYIDLE,
  56         SIPE_ACTIVITY_DND,
  57         SIPE_ACTIVITY_BRB,
  58         SIPE_ACTIVITY_AWAY,
  59         SIPE_ACTIVITY_LUNCH,
  60         SIPE_ACTIVITY_OFFLINE,
  61         SIPE_ACTIVITY_ON_PHONE,
  62         SIPE_ACTIVITY_IN_CONF,
  63         SIPE_ACTIVITY_IN_MEETING,
  64         SIPE_ACTIVITY_OOF,
  65         SIPE_ACTIVITY_URGENT_ONLY,
  66         SIPE_ACTIVITY_NUM_TYPES
  67 } sipe_activity;
  68
  69 /**
  70  * Transport type
  71  */
  72 #define SIPE_TRANSPORT_AUTO 0
  73 #define SIPE_TRANSPORT_TLS  1
  74 #define SIPE_TRANSPORT_TCP  2
  75
  76 /**
  77  * Transport connection (public part)
  78  *
  79  * The receiver in the backend fills "buffer". The backend has to zero
  80  * terminate the buffer before calling the processing function in the core.
  81  *
  82  * The processing function in the core can remove content from the buffer.
  83  * It has to update buffer_used accordingly.
  84  *
  85  */
  86 struct sipe_transport_connection {
  87         gpointer user_data;
  88         gchar *buffer;
  89         gsize buffer_used;        /* 0 < buffer_used < buffer_length */
  90         gsize buffer_length;      /* read-only */
  91         guint type;               /* read-only */
  92         guint client_port;        /* read-only */
  93 };
  94
  95 /**
  96  * Opaque data type for chat session
  97  */
  98 struct sipe_chat_session;
  99
 100 /**
 101  * File transport (public part)
 102  */
 103 struct sipe_file_transfer {
 104         struct sipe_backend_file_transfer *backend_private;
 105 };
 106
 107 /**
 108  * Opaque data type for backend private data.
 109  * The backend is responsible to allocate and free it.
 110  */
 111 struct sipe_backend_private;
 112
 113 /**
 114  * Flags
 115  */
 116 #define SIPE_CORE_FLAG_KRB5    0x00000001 /* user enabled Kerberos 5     */
 117 #define SIPE_CORE_FLAG_SSO     0x00000002 /* user enabled Single-Sign On */
 118 #define SIPE_CORE_FLAG_TLS_DSK 0x00000004 /* user enabled TLS-DSK        */
 119
 120 #define SIPE_CORE_FLAG_IS(flag)    \
 121         ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
 122 #define SIPE_CORE_FLAG_SET(flag)   \
 123         (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
 124 #define SIPE_CORE_FLAG_UNSET(flag) \
 125         (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
 126
 127 /**
 128  * Public part of the Sipe data structure
 129  *
 130  * This part contains the information needed by the core and the backend.
 131  */
 132 struct sipe_core_public {
 133         /**
 134          * This points to the private data for the backend.
 135          * The backend is responsible to allocate and free it.
 136          */
 137         struct sipe_backend_private *backend_private;
 138
 139         /* flags (see above) */
 140         guint32 flags;
 141
 142         /* user information */
 143         gchar *sip_name;
 144         gchar *sip_domain;
 145
 146         /* server information */
 147         guint keepalive_timeout;
 148 };
 149
 150 /**
 151  * Initialize & destroy functions for the SIPE core
 152  * Should be called on loading and unloading of the plugin.
 153  */
 154 void sipe_core_init(const char *locale_dir);
 155 void sipe_core_destroy(void);
 156
 157 /** Utility functions exported by the core to backends ***********************/
 158 gboolean sipe_strequal(const gchar *left, const gchar *right);
 159
 160 GSList *
 161 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
 162
 163 const gchar *
 164 sipe_utils_nameval_find(const GSList *list, const gchar *name);
 165
 166 const gchar *
 167 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
 168
 169 void
 170 sipe_utils_nameval_free(GSList *list);
 171
 172 gboolean sipe_utils_is_avconf_uri(const gchar *uri);
 173
 174 gchar *sip_uri_from_name(const gchar *name);
 175 gchar *sip_uri(const gchar *string);
 176
 177 /*****************************************************************************/
 178
 179 /**
 180  * Other functions (need to be sorted once structure becomes clear.
 181  */
 182
 183 /* Get translated about string. Must be g_free'd(). */
 184 gchar *sipe_core_about(void);
 185
 186 /* Execute a scheduled action */
 187 void sipe_core_schedule_execute(gpointer data);
 188
 189 /* menu actions */
 190 void sipe_core_update_calendar(struct sipe_core_public *sipe_public);
 191 void sipe_core_reset_status(struct sipe_core_public *sipe_public);
 192
 193 /* buddy actions */
 194 /**
 195  * Get status text for buddy.
 196  *
 197  * @param sipe_public Sipe core public data structure.
 198  * @param uri         SIP URI of the buddy
 199  * @param activity    activity value for buddy
 200  * @param status_text backend-specific buddy status text for activity.
 201  *
 202  * @return HTML status text for the buddy or NULL. Must be g_free()'d.
 203  */
 204 gchar *sipe_core_buddy_status(struct sipe_core_public *sipe_public,
 205                               const gchar *uri,
 206                               const sipe_activity activity,
 207                               const gchar *status_text);
 208
 209 void sipe_core_buddy_got_status(struct sipe_core_public *sipe_public,
 210                                 const gchar *uri,
 211                                 const gchar *status_id);
 212
 213 /**
 214  * Trigger generation of buddy information label/text pairs
 215  *
 216  * @param sipe_public Sipe core public data structure.
 217  * @param uri         SIP URI of the buddy
 218  * @param status_text backend-specific buddy status text for ID.
 219  * @param is_online   backend considers buddy to be online.
 220  * @param tooltip     opaque backend identifier for tooltip info. This is the
 221  *                    parameter given to @c sipe_backend_buddy_tooltip_add()
 222  */
 223 struct sipe_backend_buddy_tooltip;
 224 void sipe_core_buddy_tooltip_info(struct sipe_core_public *sipe_public,
 225                                   const gchar *uri,
 226                                   const gchar *status_name,
 227                                   gboolean is_online,
 228                                   struct sipe_backend_buddy_tooltip *tooltip);
 229
 230 /**
 231  * Add a buddy
 232  *
 233  * @param sipe_public Sipe core public data structure
 234  * @param uri         SIP URI of the buddy
 235  * @param group_name  backend-specific group name
 236  */
 237 void sipe_core_buddy_add(struct sipe_core_public *sipe_public,
 238                          const gchar *uri,
 239                          const gchar *group_name);
 240
 241 /**
 242  * Remove a buddy
 243  *
 244  * @param sipe_public Sipe core public data structure
 245  * @param uri         SIP URI of the buddy
 246  * @param group_name  backend-specific group name
 247  */
 248 void sipe_core_buddy_remove(struct sipe_core_public *sipe_public,
 249                             const gchar *uri,
 250                             const gchar *group_name);
 251
 252 void sipe_core_contact_allow_deny(struct sipe_core_public *sipe_public,
 253                                   const gchar *who,
 254                                   gboolean allow);
 255 void sipe_core_group_set_user(struct sipe_core_public *sipe_public,
 256                               const gchar * who);
 257
 258 /**
 259  * Setup core data
 260  */
 261 struct sipe_core_public *sipe_core_allocate(const gchar *signin_name,
 262                                             const gchar *login_domain,
 263                                             const gchar *login_account,
 264                                             const gchar *password,
 265                                             const gchar *email,
 266                                             const gchar *email_url,
 267                                             const gchar **errmsg);
 268 void sipe_core_deallocate(struct sipe_core_public *sipe_public);
 269
 270 /**
 271  * Connect to SIP server
 272  */
 273 void sipe_core_transport_sip_connect(struct sipe_core_public *sipe_public,
 274                                      guint transport,
 275                                      const gchar *server,
 276                                      const gchar *port);
 277 void sipe_core_transport_sip_keepalive(struct sipe_core_public *sipe_public);
 278
 279 /**
 280  * Invite to chat
 281  */
 282 void sipe_core_chat_invite(struct sipe_core_public *sipe_public,
 283                            struct sipe_chat_session *chat_session,
 284                            const char *name);
 285
 286 /**
 287  * Rejoin a chat after connection re-establishment
 288  */
 289 void sipe_core_chat_rejoin(struct sipe_core_public *sipe_public,
 290                            struct sipe_chat_session *chat_session);
 291
 292 /**
 293  * Leave a chat
 294  */
 295 void sipe_core_chat_leave(struct sipe_core_public *sipe_public,
 296                           struct sipe_chat_session *chat_session);
 297
 298 /**
 299  * Send message to chat
 300  */
 301 void sipe_core_chat_send(struct sipe_core_public *sipe_public,
 302                          struct sipe_chat_session *chat_session,
 303                          const char *what);
 304
 305 /**
 306  * Check chat lock status
 307  */
 308 typedef enum {
 309         SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED = 0,
 310         SIPE_CHAT_LOCK_STATUS_UNLOCKED,
 311         SIPE_CHAT_LOCK_STATUS_LOCKED
 312 } sipe_chat_lock_status;
 313 sipe_chat_lock_status sipe_core_chat_lock_status(struct sipe_core_public *sipe_public,
 314                                                  struct sipe_chat_session *chat_session);
 315
 316 /**
 317  * Lock chat
 318  */
 319 void sipe_core_chat_modify_lock(struct sipe_core_public *sipe_public,
 320                                 struct sipe_chat_session *chat_session,
 321                                 const gboolean locked);
 322
 323 /**
 324  * Create new session with Focus URI
 325  *
 326  * @param sipe_public (in) SIPE core data.
 327  * @param focus_uri (in) focus URI string
 328  *
 329  * @return new SIP session
 330  */
 331 struct sip_session *
 332 sipe_core_conf_create(struct sipe_core_public *sipe_public,
 333                       const gchar *focus_uri);
 334
 335 /* media */
 336 void sipe_core_media_initiate_call(struct sipe_core_public *sipe_public,
 337                                    const char *participant,
 338                                    gboolean with_video);
 339 /**
 340  * Connects to a conference call specified by given chat session
 341  *
 342  * @param sipe_public (in) SIPE core data.
 343  * @param chat_session (in) chat session structure
 344  */
 345 void sipe_core_media_connect_conference(struct sipe_core_public *sipe_public,
 346                                         struct sipe_chat_session *chat_session);
 347
 348 /**
 349  * Checks whether there is a media call in progress
 350  *
 351  * @param sipe_public (in) SIPE core data.
 352  *
 353  * @return @c TRUE if media call is in progress
 354  */
 355 gboolean sipe_core_media_in_call(struct sipe_core_public *sipe_public);
 356
 357 /* file transfer */
 358 struct sipe_file_transfer *sipe_core_ft_allocate(struct sipe_core_public *sipe_public);
 359 void sipe_core_ft_deallocate(struct sipe_file_transfer *ft);
 360 void sipe_core_ft_cancel(struct sipe_file_transfer *ft);
 361 void sipe_core_ft_incoming_init(struct sipe_file_transfer *ft);
 362 void sipe_core_ft_outgoing_init(struct sipe_file_transfer *ft,
 363                                 const gchar *filename, gsize size,
 364                                 const gchar *who);
 365
 366 void sipe_core_tftp_incoming_start(struct sipe_file_transfer *ft,
 367                                    gsize total_size);
 368 gboolean sipe_core_tftp_incoming_stop(struct sipe_file_transfer *ft);
 369 void sipe_core_tftp_outgoing_start(struct sipe_file_transfer *ft,
 370                                    gsize total_size);
 371 gboolean sipe_core_tftp_outgoing_stop(struct sipe_file_transfer *ft);
 372 gssize sipe_core_tftp_read(struct sipe_file_transfer *ft, guchar **buffer,
 373                            gsize bytes_remaining, gsize bytes_available);
 374 gssize sipe_core_tftp_write(struct sipe_file_transfer *ft, const guchar *buffer,
 375                             gsize size);
 376 /* group chat */
 377 gboolean sipe_core_groupchat_query_rooms(struct sipe_core_public *sipe_public);
 378 void sipe_core_groupchat_join(struct sipe_core_public *sipe_public,
 379                               const gchar *uri);
 380
 381 /* IM */
 382 void sipe_core_im_send(struct sipe_core_public *sipe_public,
 383                        const gchar *who,
 384                        const gchar *what);
 385 void sipe_core_im_close(struct sipe_core_public *sipe_public,
 386                         const gchar *who);
 387
 388 /* user */
 389 void sipe_core_user_feedback_typing(struct sipe_core_public *sipe_public,
 390                                     const gchar *to);
 391
 392 void sipe_core_user_ask_cb(gpointer key, gboolean accepted);
 393
 394 /* groups */
 395 void sipe_core_group_rename(struct sipe_core_public *sipe_public,
 396                             const gchar *old_name,
 397                             const gchar *new_name);
 398
 399 void sipe_core_group_remove(struct sipe_core_public *sipe_public,
 400                             const gchar *name);
 401
 402 /* buddies */
 403 void sipe_core_buddy_group(struct sipe_core_public *sipe_public,
 404                            const gchar *who,
 405                            const gchar *old_group_name,
 406                            const gchar *new_group_name);
 407
 408 void sipe_core_buddy_search(struct sipe_core_public *sipe_public,
 409                             const gchar *given_name,
 410                             const gchar *surname,
 411                             const gchar *company,
 412                             const gchar *country);
 413
 414 void sipe_core_buddy_get_info(struct sipe_core_public *sipe_public,
 415                               const gchar *who);
 416
 417 /* status */
 418 void sipe_core_status_set(struct sipe_core_public *sipe_public,
 419                           const gchar *status_id,
 420                           const gchar *note);
 421 void sipe_core_status_idle(struct sipe_core_public *sipe_public);
 422
 423 #ifdef __cplusplus
 424 }
 425 #endif
 426
 427 /*
 428   Local Variables:
 429   mode: c
 430   c-file-style: "bsd"
 431   indent-tabs-mode: t
 432   tab-width: 8
 433   End:
 434 */