src/core/sipe-utils.h

   1 /**
   2  * @file sipe-utils.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2009 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  * Interface dependencies:
  25  *
  26  * <time.h>
  27  * <glib.h>
  28  */
  29
  30 /* Forward declarations */
  31 struct sipe_account_data;
  32 struct _xmlnode;
  33
  34 /* Our publication type keys. OCS 2007+
  35  * Format: SIPE_PUB_{Category}[_{SubSategory}]
  36  */
  37 /**
  38  * device
  39  * -
  40  *
  41  * -
  42  * Unique to the device.
  43  */
  44 #define SIPE_PUB_DEVICE         0
  45 /**
  46  * state
  47  * Machine state
  48  *
  49  * Availability, activity, end-point location, time zone, and device type.
  50  * First hexadecimal digit is 0x3; remaining seven hexadecimal digits are unique per device.
  51  */
  52 #define SIPE_PUB_STATE_MACHINE  3
  53 /**
  54  * state
  55  * User state
  56  *
  57  * Availability and activity.
  58  * 0x20000000
  59  */
  60 #define SIPE_PUB_STATE_USER     2
  61 /**
  62  * state
  63  * Calendar state
  64  *
  65  * Availability, activity, meeting subject, and meeting location.
  66  * First hexadecimal digit is 0x4; remaining seven hexadecimal digits are unique per device.
  67  */
  68 #define SIPE_PUB_STATE_CALENDAR 4
  69 /**
  70  * state
  71  * Calendar state for an Out of Office meeting
  72  *
  73  * (??)Activity for when a user sets or removes an Out of Office message in Exchange.
  74  * (+)user sets in Outlook for an Out of Office meeting
  75  * First hexadecimal digit is 0x5; remaining seven hexadecimal digits are unique per device.
  76  */
  77 #define SIPE_PUB_STATE_CALENDAR_OOF     5
  78 /**
  79  * state
  80  * RCC Phone State
  81  *
  82  * Availability and activity for RCC call connect/disconnect or participant count changes from 0 to 2, 2 to N, N to 2, 2 to 0.
  83  * First hexadecimal digit is 0x7; remaining seven hexadecimal digits are unique per device.
  84  */
  85 #define SIPE_PUB_STATE_PHONE    7
  86 /**
  87  * calendarData
  88  * Free/busy data
  89  *
  90  * Start time, granularity, and free/busy data.
  91  * First hexadecimal digit is 0x4; last seven hexadecimal digits uniquely define the calendar.
  92  */
  93 #define SIPE_PUB_CALENDAR_DATA  400
  94 /**
  95  * note
  96  * Out of Office note
  97  *
  98  * Out of Office note that a user sets in Outlook using the Out of Office assistant.
  99  * First hexadecimal digit is 0x4; last seven hexadecimal digits uniquely define the calendar.
 100  */
 101 #define SIPE_PUB_NOTE_OOF       400
 102
 103 /**
 104  * Returns epid value.
 105  * Uses cache.
 106  */
 107 gchar *
 108 get_epid(struct sipe_account_data *sip);
 109
 110 /**
 111  * Generate Call ID
 112  *
 113  * @return Call ID. Must be g_free()'d.
 114  */
 115 gchar *gencallid(void);
 116
 117 /**
 118  * Generate Tag
 119  *
 120  * @return Tag. Must be g_free()'d.
 121  */
 122 gchar *gentag(void);
 123
 124 /**
 125  * Generate conference-id
 126  * 32 characters long. Value space is restricted to printable ASCII characters
 127  *
 128  * Ex.: 8386E6AEAAA41E4AA6627BA76D43B6D1
 129  *
 130  * @return conference-id. Must be g_free()'d.
 131  */
 132 gchar *genconfid(void);
 133
 134 /**
 135  * Returns instance value for particular publication type.
 136  * It should be consistent for the same endpoint
 137  * but different between distinct endpoints.
 138  *
 139  * See defined constants for keys patterned SIPE_PUB_*
 140  */
 141 guint
 142 sipe_get_pub_instance(struct sipe_account_data *sip,
 143                       int publication_key);
 144
 145 /**
 146  * Get contact information from SIPE account
 147  *
 148  * @param sip (in) SIPE account
 149  *
 150  * @return Contact. Must be g_free()'d.
 151  */
 152 gchar *get_contact(const struct sipe_account_data *sip);
 153
 154 /**
 155  * Parses URI from SIP header
 156  *
 157  * @param hdr (in) To/From header
 158  *
 159  * @return URI with sip: prefix. Must be g_free()'d.
 160  */
 161 gchar *parse_from(const gchar *hdr);
 162
 163 /**
 164  * Parses CSeq from SIP header
 165  *
 166  * @param hdr (in) CSeqm header
 167  *
 168  * @return int type CSeq value (i.e. without method).
 169  */
 170 int parse_cseq(const gchar *hdr);
 171
 172 /**
 173  * Create sip: URI from name
 174  *
 175  * @param name (in)
 176  *
 177  * @return URI with sip: prefix. Must be g_free()'d.
 178  */
 179 gchar *sip_uri_from_name(const gchar *name);
 180
 181 /**
 182  * Create sip: URI from SIP account user name
 183  *
 184  * @param sip (in) SIP account data
 185  *
 186  * @return URI with sip: prefix. Must be g_free()'d.
 187  */
 188 #define sip_uri_self(sip) (sip_uri_from_name(sip->username))
 189
 190 /**
 191  * Create sip: URI from name or sip: URI
 192  *
 193  * @param string (in) name or sip: URI
 194  *
 195  * @return URI with sip: prefix. Must be g_free()'d.
 196  */
 197 gchar *sip_uri(const gchar *string);
 198
 199 /**
 200  * Tries to figure out if contact alias which stored locally
 201  * is just SIP URI, not a proper display name or local alias.
 202  *
 203  * @param uri SIP URI with 'sip:' prefix.
 204  * @param alias as returned by purple.
 205  */
 206 gboolean
 207 sipe_is_bad_alias(const char *uri,
 208                   const char *alias);
 209
 210 /**
 211  * Find a XML node from the parent with the specified path
 212  *
 213  * @param parent (in) XML node to start search from
 214  * @param ...    (in) Names of the descendant nodes
 215  *
 216  * @return descendant XML node
 217  */
 218 struct _xmlnode * xmlnode_get_descendant(const struct _xmlnode *parent, ...);
 219
 220 /**
 221  * Convert a XML attribute to an integer
 222  * @param node     (in) XML node
 223  * @param attr     (in) name of the attribute
 224  * @param fallback (in) default value if the attribute doesn't exist
 225  *
 226  * @return attribute value converted to integer or the fallback value
 227  */
 228 gint xmlnode_get_int_attrib(struct _xmlnode *node,
 229                             const char *attr,
 230                             gint fallback);
 231
 232 /**
 233  * Checks if provided string is empty - NULL, zero size or just series of white spaces.
 234  * Doesn't modify input string.
 235  */
 236 gboolean
 237 is_empty(const char *st);
 238
 239 /** Returns newly allocated string. Must be g_free()'d */
 240 char *
 241 replace(const char *st,
 242         const char *search,
 243         const char *replace);
 244
 245 /**
 246  * Replaces \r\n to \n
 247  * Returns newly allocated string. Must be g_free()'d
 248  */
 249 char *
 250 fix_newlines(const char *st);
 251
 252 /**
 253  * Tests two strings for equality.
 254  *
 255  * Unlike strcmp(), this function will not crash if one or both of the
 256  * strings are @c NULL.
 257  *
 258  * Same as purple_strequal (defined only for 2.6) to maintain
 259  * our backward compatibility.
 260  *
 261  * @param left  A string
 262  * @param right A string to compare with left
 263  *
 264  * @return @c TRUE if the strings are the same, else @c FALSE.
 265  *
 266  */
 267 gboolean sipe_strequal(const gchar *left, const gchar *right);
 268
 269 /**
 270  * Tests two strings for equality, ignoring the case
 271  *
 272  * Same as glib @c g_ascii_strcasecmp() but works correctly for @c NULL
 273  * pointers too. Plus it doesn't complain loudly about them...
 274  *
 275  * @param left  A string
 276  * @param right A string to compare with left
 277  *
 278  * @return @c TRUE if the strings are the same, else @c FALSE.
 279  *
 280  */
 281 gboolean sipe_strcase_equal(const gchar *left, const gchar *right);
 282
 283 /**
 284  * Parses a timestamp in ISO8601 format and returns a time_t.
 285  * Assumes UTC if no timezone specified
 286  *
 287  * @param timestamp The timestamp
 288  */
 289 time_t
 290 sipe_utils_str_to_time(const char *timestamp);
 291
 292 /**
 293  * Converts time_t to ISO8601 string.
 294  * Timezone is UTC.
 295  *
 296  * Must be g_free()'d after use.
 297  *
 298  * Example: 2010-02-03T23:59:59Z
 299  */
 300 char *
 301 sipe_utils_time_to_str(time_t timestamp);
 302
 303 struct sipnameval {
 304         gchar *name;
 305         gchar *value;
 306 };
 307
 308 /**
 309  * Parses string of hex digits to buffer.
 310  * Allocates memory.
 311  *
 312  * @param hex_str (in)  string of hex digits to convert.
 313  * @param buff (out)    newly allocated buffer. Must be g_free()'d after use.
 314  *
 315  * @return              size of newly allocated buffer
 316  */
 317 size_t
 318 hex_str_to_buff(const char *hex_str, guint8 **buff);
 319
 320 /**
 321  * Composes hex string out of provided buffer.
 322  * Allocates memory.
 323  *
 324  * @param buff          input buffer
 325  * @param buff_len      length of buffer
 326  *
 327  * @result              newly allocated hex string representing buffer. Must be g_free()'d after use.
 328  */
 329 char *
 330 buff_to_hex_str(const guint8 *buff, const size_t buff_len);
 331
 332 /**
 333  * Creates name-value pairs from given lines and appends them to @c list
 334  *
 335  * Lines must be in format 'name: value'
 336  *
 337  * @param list  a list of @c sipnameval structures
 338  * @param lines array of strings in format 'name: value'
 339  *
 340  * @return @c FALSE if any of @c lines has incorrect format, @c TRUE otherwise
 341  */
 342 gboolean
 343 sipe_utils_parse_lines(GSList **list, gchar **lines);
 344
 345 /**
 346  * Adds a name-value pair to @c list
 347  *
 348  * @param list  a list of @c sipnameval structures
 349  * @param name  attribute's name
 350  * @param value value of attribute @c name
 351  *
 352  * @return the new start of the GSList
 353  */
 354 GSList *
 355 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
 356
 357 /**
 358  * Finds a value of attribute @c name in @c list
 359  *
 360  * @param list a list of @c sipnameval structures
 361  * @param name attribute to find
 362  *
 363  * @return value of @c name or NULL if @c name is not found
 364  */
 365 const gchar *
 366 sipe_utils_nameval_find(const GSList *list, const gchar *name);
 367
 368 /**
 369  * Returns @c which occurrence of attribute @c name in @c list
 370  *
 371  * @c which is zero based, so 0 means first occurrence of @c name in @c list.
 372  *
 373  * @param list  a list of @c sipnameval structures
 374  * @param name  attribute to find
 375  * @param which specifies occurrence of @name in @c list
 376  *
 377  * @return value of @c name or NULL if @c name is not found
 378  */
 379 const gchar *
 380 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
 381
 382 /**
 383  * Frees memory allocated by @c list
 384  *
 385  * @param list a list of @c sipnameval structures
 386  */
 387 void
 388 sipe_utils_nameval_free(GSList *list);
 389