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