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 /**
  41  * Activity
  42  *   - core:    maps this to OCS protocol values
  43  *   - backend: maps this to backend status values
  44  */
  45 typedef enum
  46 {
  47         SIPE_ACTIVITY_UNSET = 0,
  48         SIPE_ACTIVITY_ONLINE,
  49         SIPE_ACTIVITY_INACTIVE,
  50         SIPE_ACTIVITY_BUSY,
  51         SIPE_ACTIVITY_BUSYIDLE,
  52         SIPE_ACTIVITY_DND,
  53         SIPE_ACTIVITY_BRB,
  54         SIPE_ACTIVITY_AWAY,
  55         SIPE_ACTIVITY_LUNCH,
  56         SIPE_ACTIVITY_OFFLINE,
  57         SIPE_ACTIVITY_ON_PHONE,
  58         SIPE_ACTIVITY_IN_CONF,
  59         SIPE_ACTIVITY_IN_MEETING,
  60         SIPE_ACTIVITY_OOF,
  61         SIPE_ACTIVITY_URGENT_ONLY,
  62         SIPE_ACTIVITY_NUM_TYPES
  63 } sipe_activity;
  64
  65 /**
  66  * Transport type
  67  */
  68 #define SIPE_TRANSPORT_AUTO 0
  69 #define SIPE_TRANSPORT_TLS  1
  70 #define SIPE_TRANSPORT_TCP  2
  71
  72 /**
  73  * Transport connection (public part)
  74  *
  75  * The receiver in the backend fills "buffer". The backend has to zero
  76  * terminate the buffer before calling the processing function in the core.
  77  *
  78  * The processing function in the core can remove content from the buffer.
  79  * It has to update buffer_used accordingly.
  80  *
  81  */
  82 struct sipe_transport_connection {
  83         gpointer user_data;
  84         gchar *buffer;
  85         gsize buffer_used;        /* 0 < buffer_used < buffer_length */
  86         gsize buffer_length;      /* read-only */
  87         guint type;               /* read-only */
  88         guint client_port;        /* read-only */
  89 };
  90
  91 /**
  92  * Opaque data type for backend private data.
  93  * The backend is responsible to allocate and free it.
  94  */
  95 struct sipe_backend_private;
  96
  97 /**
  98  * Flags
  99  */
 100 #define SIPE_CORE_FLAG_KRB5 0x00000001 /* user enabled Kerberos 5     */
 101 #define SIPE_CORE_FLAG_SSO  0x00000002 /* user enabled Single-Sign On */
 102
 103 #define SIPE_CORE_FLAG_IS(flag)    \
 104         ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
 105 #define SIPE_CORE_FLAG_SET(flag)   \
 106         (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
 107 #define SIPE_CORE_FLAG_UNSET(flag) \
 108         (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
 109
 110 /**
 111  * Public part of the Sipe data structure
 112  *
 113  * This part contains the information needed by the core and the backend.
 114  */
 115 struct sipe_core_public {
 116         /**
 117          * This points to the private data for the backend.
 118          * The backend is responsible to allocate and free it.
 119          */
 120         struct sipe_backend_private *backend_private;
 121
 122         /* flags (see above) */
 123         guint32 flags;
 124
 125         /* user information */
 126         gchar *sip_name;
 127         gchar *sip_domain;
 128
 129         /* server information */
 130         struct sipe_transport_connection *transport;
 131         guint keepalive_timeout;
 132 };
 133
 134 /**
 135  * Initialize & destroy functions for the SIPE core
 136  * Should be called on loading and unloading of the plugin.
 137  */
 138 void sipe_core_init(void);
 139 void sipe_core_destroy(void);
 140
 141 /** Utility functions exported by the core to backends ***********************/
 142 gboolean sipe_strequal(const gchar *left, const gchar *right);
 143 char *fix_newlines(const char *st);
 144
 145 /*****************************************************************************/
 146
 147 /**
 148  * Other functions (need to be sorted once structure becomes clear.
 149  */
 150
 151 /* Get translated about string. Must be g_free'd(). */
 152 gchar *sipe_core_about(void);
 153
 154 /* menu actions */
 155 void sipe_core_update_calendar(struct sipe_core_public *sipe_public);
 156 void sipe_core_reset_status(struct sipe_core_public *sipe_public);
 157
 158 /* buddy actions */
 159 /**
 160  * Get status text for buddy.
 161  *
 162  * @param sipe_public Sipe core public data structure.
 163  * @param name        backend-specific buddy name.
 164  * @param activity    activity value for buddy
 165  * @param status_text backend-specific buddy status text for activity.
 166  *
 167  * @return HTML status text for the buddy or NULL. Must be g_free()'d.
 168  */
 169 gchar *sipe_core_buddy_status(struct sipe_core_public *sipe_public,
 170                               const gchar *name,
 171                               const sipe_activity activity,
 172                               const gchar *status_text);
 173
 174 /**
 175  * Return a list with buddy information label/text pairs
 176  *
 177  * @param sipe_public Sipe core public data structure.
 178  * @param name        backend-specific buddy name.
 179  * @param status_text backend-specific buddy status text for ID.
 180  * @param is_online   backend considers buddy to be online.
 181  *
 182  * @return GSList of struct sipe_buddy_info or NULL. Must be freed by caller.
 183  */
 184 struct sipe_buddy_info {    /* must be g_free()'d */
 185         const gchar *label;
 186         gchar *text;        /* must be g_free()'d */
 187 };
 188 GSList *sipe_core_buddy_info(struct sipe_core_public *sipe_public,
 189                              const gchar *name,
 190                              const gchar *status_name,
 191                              gboolean is_online);
 192
 193 void sipe_core_contact_allow_deny(struct sipe_core_public *sipe_public,
 194                                   const gchar *who, gboolean allow);
 195 void sipe_core_group_set_user(struct sipe_core_public *sipe_public,
 196                               const gchar * who);
 197
 198 /**
 199  * Setup core data
 200  */
 201 struct sipe_core_public *sipe_core_allocate(const gchar *signin_name,
 202                                             const gchar *login_domain,
 203                                             const gchar *login_account,
 204                                             const gchar *password,
 205                                             const gchar *email,
 206                                             const gchar *email_url,
 207                                             const gchar **errmsg);
 208 void sipe_core_deallocate(struct sipe_core_public *sipe_public);
 209
 210 /**
 211  * Connect to server
 212  */
 213 void sipe_core_transport_sip_connect(struct sipe_core_public *sipe_public,
 214                                      guint transport,
 215                                      const gchar *server,
 216                                      const gchar *port);
 217 void sipe_core_transport_sip_connected(struct sipe_transport_connection *conn);
 218 void sipe_core_transport_sip_message(struct sipe_transport_connection *conn);
 219 void sipe_core_transport_http_connected(struct sipe_transport_connection *conn);
 220 void sipe_core_transport_http_message(struct sipe_transport_connection *conn);
 221 void sipe_core_transport_http_input_error(struct sipe_transport_connection *conn,
 222                                           const gchar *msg);
 223
 224 /**
 225  * DNS SRV resolved hook
 226  *
 227  * @param sipe_public
 228  * @param hostname    SIP server hostname
 229  * @param port        SIP server port
 230  */
 231 void sipe_core_dns_resolved(struct sipe_core_public *sipe_public,
 232                             const gchar *hostname,
 233                             guint port);
 234 void sipe_core_dns_resolve_failure(struct sipe_core_public *sipe_public);
 235
 236 /**
 237  * Create a new chat
 238  */
 239 void sipe_core_chat_create(struct sipe_core_public *sipe_public, int id,
 240                            const char *name);
 241
 242 /*
 243   Local Variables:
 244   mode: c
 245   c-file-style: "bsd"
 246   indent-tabs-mode: t
 247   tab-width: 8
 248   End:
 249 */