src/api/sipe-core.h

   1 /**
   2  * @file sipe-core.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010 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  * File transport (public part)
  97  */
  98 struct sipe_file_transfer {
  99         struct sipe_backend_file_transfer *backend_private;
 100 };
 101
 102 /**
 103  * Opaque data type for backend private data.
 104  * The backend is responsible to allocate and free it.
 105  */
 106 struct sipe_backend_private;
 107
 108 /**
 109  * Flags
 110  */
 111 #define SIPE_CORE_FLAG_KRB5 0x00000001 /* user enabled Kerberos 5     */
 112 #define SIPE_CORE_FLAG_SSO  0x00000002 /* user enabled Single-Sign On */
 113
 114 #define SIPE_CORE_FLAG_IS(flag)    \
 115         ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
 116 #define SIPE_CORE_FLAG_SET(flag)   \
 117         (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
 118 #define SIPE_CORE_FLAG_UNSET(flag) \
 119         (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
 120
 121 /**
 122  * Public part of the Sipe data structure
 123  *
 124  * This part contains the information needed by the core and the backend.
 125  */
 126 struct sipe_core_public {
 127         /**
 128          * This points to the private data for the backend.
 129          * The backend is responsible to allocate and free it.
 130          */
 131         struct sipe_backend_private *backend_private;
 132
 133         /* flags (see above) */
 134         guint32 flags;
 135
 136         /* user information */
 137         gchar *sip_name;
 138         gchar *sip_domain;
 139
 140         /* server information */
 141         guint keepalive_timeout;
 142 };
 143
 144 /**
 145  * Initialize & destroy functions for the SIPE core
 146  * Should be called on loading and unloading of the plugin.
 147  */
 148 void sipe_core_init(const char *locale_dir);
 149 void sipe_core_destroy(void);
 150
 151 /** Utility functions exported by the core to backends ***********************/
 152 gboolean sipe_strequal(const gchar *left, const gchar *right);
 153
 154 GSList *
 155 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
 156
 157 const gchar *
 158 sipe_utils_nameval_find(const GSList *list, const gchar *name);
 159
 160 const gchar *
 161 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
 162
 163 void
 164 sipe_utils_nameval_free(GSList *list);
 165
 166 /*****************************************************************************/
 167
 168 /**
 169  * Other functions (need to be sorted once structure becomes clear.
 170  */
 171
 172 /* Get translated about string. Must be g_free'd(). */
 173 gchar *sipe_core_about(void);
 174
 175 /* Execute a scheduled action */
 176 void sipe_core_schedule_execute(gpointer data);
 177
 178 /* menu actions */
 179 void sipe_core_update_calendar(struct sipe_core_public *sipe_public);
 180 void sipe_core_reset_status(struct sipe_core_public *sipe_public);
 181
 182 /* buddy actions */
 183 /**
 184  * Get status text for buddy.
 185  *
 186  * @param sipe_public Sipe core public data structure.
 187  * @param name        backend-specific buddy name.
 188  * @param activity    activity value for buddy
 189  * @param status_text backend-specific buddy status text for activity.
 190  *
 191  * @return HTML status text for the buddy or NULL. Must be g_free()'d.
 192  */
 193 gchar *sipe_core_buddy_status(struct sipe_core_public *sipe_public,
 194                               const gchar *name,
 195                               const sipe_activity activity,
 196                               const gchar *status_text);
 197
 198 /**
 199  * Return a list with buddy information label/text pairs
 200  *
 201  * @param sipe_public Sipe core public data structure.
 202  * @param name        backend-specific buddy name.
 203  * @param status_text backend-specific buddy status text for ID.
 204  * @param is_online   backend considers buddy to be online.
 205  *
 206  * @return GSList of struct sipe_buddy_info or NULL. Must be freed by caller.
 207  */
 208 struct sipe_buddy_info {    /* must be g_free()'d */
 209         const gchar *label;
 210         gchar *text;        /* must be g_free()'d */
 211 };
 212 GSList *sipe_core_buddy_info(struct sipe_core_public *sipe_public,
 213                              const gchar *name,
 214                              const gchar *status_name,
 215                              gboolean is_online);
 216
 217 void sipe_core_contact_allow_deny(struct sipe_core_public *sipe_public,
 218                                   const gchar *who, gboolean allow);
 219 void sipe_core_group_set_user(struct sipe_core_public *sipe_public,
 220                               const gchar * who);
 221
 222 /**
 223  * Setup core data
 224  */
 225 struct sipe_core_public *sipe_core_allocate(const gchar *signin_name,
 226                                             const gchar *login_domain,
 227                                             const gchar *login_account,
 228                                             const gchar *password,
 229                                             const gchar *email,
 230                                             const gchar *email_url,
 231                                             const gchar **errmsg);
 232 void sipe_core_deallocate(struct sipe_core_public *sipe_public);
 233
 234 /**
 235  * Connect to SIP server
 236  */
 237 void sipe_core_transport_sip_connect(struct sipe_core_public *sipe_public,
 238                                      guint transport,
 239                                      const gchar *server,
 240                                      const gchar *port);
 241 void sipe_core_transport_sip_keepalive(struct sipe_core_public *sipe_public);
 242
 243 /**
 244  * DNS SRV resolved hook
 245  *
 246  * @param sipe_public
 247  * @param hostname    SIP server hostname
 248  * @param port        SIP server port
 249  */
 250 void sipe_core_dns_resolved(struct sipe_core_public *sipe_public,
 251                             const gchar *hostname,
 252                             guint port);
 253 void sipe_core_dns_resolve_failure(struct sipe_core_public *sipe_public);
 254
 255 /**
 256  * Create a new chat
 257  */
 258 void sipe_core_chat_create(struct sipe_core_public *sipe_public, int id,
 259                            const char *name);
 260
 261 /* media */
 262 void sipe_core_media_initiate_call(struct sipe_core_public *sipe_public,
 263                                    const char *participant,
 264                                    gboolean with_video);
 265
 266 /* file transfer */
 267 struct sipe_file_transfer *sipe_core_ft_allocate(struct sipe_core_public *sipe_public);
 268 void sipe_core_ft_deallocate(struct sipe_file_transfer *ft);
 269 void sipe_core_ft_cancel(struct sipe_file_transfer *ft);
 270 void sipe_core_ft_incoming_init(struct sipe_file_transfer *ft);
 271 void sipe_core_ft_incoming_accept(struct sipe_file_transfer *ft,
 272                                   const gchar *who,
 273                                   int fd,
 274                                   unsigned short port);
 275 void sipe_core_ft_incoming_start(struct sipe_file_transfer *ft,
 276                                  gsize total_size);
 277 gboolean sipe_core_ft_incoming_stop(struct sipe_file_transfer *ft);
 278 void sipe_core_ft_outgoing_init(struct sipe_file_transfer *ft,
 279                                 const gchar *filename, gsize size,
 280                                 const gchar *who);
 281 void sipe_core_ft_outgoing_start(struct sipe_file_transfer *ft,
 282                                  gsize total_size);
 283 gboolean sipe_core_ft_outgoing_stop(struct sipe_file_transfer *ft);
 284 gssize sipe_core_ft_read(struct sipe_file_transfer *ft, guchar **buffer,
 285                          gsize bytes_remaining, gsize bytes_available);
 286 gssize sipe_core_ft_write(struct sipe_file_transfer *ft,
 287                           const guchar *buffer, gsize size);
 288
 289 /* user */
 290 void sipe_core_user_feedback_typing(struct sipe_core_public *sipe_public,
 291                                     const gchar *to);
 292
 293 #ifdef __cplusplus
 294 }
 295 #endif
 296
 297 /*
 298   Local Variables:
 299   mode: c
 300   c-file-style: "bsd"
 301   indent-tabs-mode: t
 302   tab-width: 8
 303   End:
 304 */