src/core/sipe-utils.h

   1 /**
   2  * @file sipe-utils.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2009-2011 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_core_private;
  32 struct sipe_transport_connection;
  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  *
 106  * @param sipe_private (in) SIPE core private data
 107  *
 108  * @return epid. Must be g_free()'d.
 109  */
 110 gchar *
 111 get_epid(struct sipe_core_private *sipe_private);
 112
 113 /**
 114  * Returns UUID value.
 115  *
 116  * @param sipe_private (in) SIPE core private data
 117  *
 118  * @return uuid. Must be g_free()'d.
 119  */
 120 gchar *
 121 get_uuid(struct sipe_core_private *sipe_private);
 122
 123 /**
 124  * Generate Call ID
 125  *
 126  * @return Call ID. Must be g_free()'d.
 127  */
 128 gchar *gencallid(void);
 129
 130 /**
 131  * Generate Tag
 132  *
 133  * @return Tag. Must be g_free()'d.
 134  */
 135 gchar *gentag(void);
 136
 137 /**
 138  * Generate conference-id
 139  * 32 characters long. Value space is restricted to printable ASCII characters
 140  *
 141  * Ex.: 8386E6AEAAA41E4AA6627BA76D43B6D1
 142  *
 143  * @return conference-id. Must be g_free()'d.
 144  */
 145 gchar *genconfid(void);
 146
 147 /**
 148  * Returns instance value for particular publication type.
 149  * It should be consistent for the same endpoint
 150  * but different between distinct endpoints.
 151  *
 152  * See defined constants for keys patterned SIPE_PUB_*
 153  */
 154 guint
 155 sipe_get_pub_instance(struct sipe_core_private *sipe_private,
 156                       int publication_key);
 157
 158 /**
 159  * Get contact information from SIPE account
 160  *
 161  * @param sipe_private (in) SIPE core private data
 162  *
 163  * @return Contact. Must be g_free()'d.
 164  */
 165 gchar *get_contact(const struct sipe_core_private *sipe_private);
 166
 167 /**
 168  * Parses URI from SIP header
 169  *
 170  * @param hdr (in) To/From header
 171  *
 172  * @return URI with sip: prefix. Must be g_free()'d.
 173  */
 174 gchar *parse_from(const gchar *hdr);
 175
 176 /**
 177  * Create sip: URI from name
 178  *
 179  * @param name (in)
 180  *
 181  * @return URI with sip: prefix. Must be g_free()'d.
 182  */
 183 gchar *sip_uri_from_name(const gchar *name);
 184
 185 /**
 186  * Create sip: URI from SIP account user name
 187  *
 188  * @param sipe_private (in) SIPE core private data
 189  *
 190  * @return URI with sip: prefix. Must be g_free()'d.
 191  */
 192 #define sip_uri_self(sipe_private) (sip_uri_from_name(sipe_private->username))
 193
 194 /**
 195  * Create sip: URI from name or sip: URI
 196  *
 197  * @param string (in) name or sip: URI
 198  *
 199  * @return URI with sip: prefix. Must be g_free()'d.
 200  */
 201 gchar *sip_uri(const gchar *string);
 202
 203 /**
 204  * Tries to figure out if contact alias which stored locally
 205  * is just SIP URI, not a proper display name or local alias.
 206  *
 207  * @param uri SIP URI with 'sip:' prefix.
 208  * @param alias as returned by purple.
 209  */
 210 gboolean
 211 sipe_is_bad_alias(const char *uri,
 212                   const char *alias);
 213
 214 /**
 215  * Checks if provided string is empty - NULL, zero size or just series of white spaces.
 216  * Doesn't modify input string.
 217  */
 218 gboolean
 219 is_empty(const char *st);
 220
 221 /** Returns newly allocated string. Must be g_free()'d */
 222 char *
 223 replace(const char *st,
 224         const char *search,
 225         const char *replace);
 226
 227 /**
 228  * Message debugging
 229  *
 230  * @param type    message type description (SIP or HTTP).
 231  * @param header  message header
 232  * @param body    message body or NULL
 233  * @param sending TRUE if outgoing message
 234  */
 235 void sipe_utils_message_debug(const gchar *type,
 236                               const gchar *header,
 237                               const gchar *body,
 238                               gboolean sending);
 239
 240 /**
 241  * Tests two strings for equality.
 242  *
 243  * Unlike strcmp(), this function will not crash if one or both of the
 244  * strings are @c NULL.
 245  *
 246  * Same as purple_strequal (defined only for 2.6) to maintain
 247  * our backward compatibility.
 248  *
 249  * @param left  A string
 250  * @param right A string to compare with left
 251  *
 252  * @return @c TRUE if the strings are the same, else @c FALSE.
 253  *
 254  */
 255 gboolean sipe_strequal(const gchar *left, const gchar *right);
 256
 257 /**
 258  * Tests two strings for equality, ignoring the case
 259  *
 260  * Same as glib @c g_ascii_strcasecmp() but works correctly for @c NULL
 261  * pointers too. Plus it doesn't complain loudly about them...
 262  *
 263  * @param left  A string
 264  * @param right A string to compare with left
 265  *
 266  * @return @c TRUE if the strings are the same, else @c FALSE.
 267  *
 268  */
 269 gboolean sipe_strcase_equal(const gchar *left, const gchar *right);
 270
 271 /**
 272  * Compares two strings
 273  *
 274  * Unlike strcmp(), this function will not crash if one or both of the
 275  * strings are @c NULL.
 276  *
 277  * Same as g_strcmp0 (defined only for >= 2.16) to maintain
 278  * our backward compatibility. The declaration is compatible to
 279  * @c GCompareFunc.
 280  *
 281  * @param a A string
 282  * @param b A string to compare with a
 283  *
 284  * @return negative value if a < b; zero if a = b; positive value if a > b.
 285  *
 286  */
 287 gint sipe_strcompare(gconstpointer a, gconstpointer b);
 288
 289 /**
 290  * Parses a timestamp in ISO8601 format and returns a time_t.
 291  * Assumes UTC if no timezone specified
 292  *
 293  * @param timestamp The timestamp
 294  */
 295 time_t
 296 sipe_utils_str_to_time(const gchar *timestamp);
 297
 298 /**
 299  * Converts time_t to ISO8601 string.
 300  * Timezone is UTC.
 301  *
 302  * Must be g_free()'d after use.
 303  *
 304  * Example: 2010-02-03T23:59:59Z
 305  */
 306 gchar *
 307 sipe_utils_time_to_str(time_t timestamp);
 308
 309 struct sipnameval {
 310         gchar *name;
 311         gchar *value;
 312 };
 313
 314 /**
 315  * Parses string of hex digits to buffer.
 316  * Allocates memory.
 317  *
 318  * @param hex_str (in)  string of hex digits to convert.
 319  * @param buff (out)    newly allocated buffer. Must be g_free()'d after use.
 320  *
 321  * @return              size of newly allocated buffer
 322  */
 323 size_t
 324 hex_str_to_buff(const char *hex_str, guint8 **buff);
 325
 326 /**
 327  * Composes hex string out of provided buffer.
 328  * Allocates memory.
 329  *
 330  * @param buff          input buffer
 331  * @param buff_len      length of buffer
 332  *
 333  * @result              newly allocated hex string representing buffer. Must be g_free()'d after use.
 334  */
 335 char *
 336 buff_to_hex_str(const guint8 *buff, const size_t buff_len);
 337
 338 /**
 339  * Creates name-value pairs from given lines and appends them to @c list
 340  *
 341  * Lines must be in format 'name [delimiter] value'
 342  *
 343  * @param list      a list of @c sipnameval structures
 344  * @param lines     array of strings in format 'name: value'
 345  * @param delimiter sequence of characters between name and value
 346  *
 347  * @return @c FALSE if any of @c lines has incorrect format, @c TRUE otherwise
 348  */
 349 gboolean
 350 sipe_utils_parse_lines(GSList **list, gchar **lines, gchar *delimiter);
 351
 352 /**
 353  * Adds a name-value pair to @c list
 354  *
 355  * @param list  a list of @c sipnameval structures
 356  * @param name  attribute's name
 357  * @param value value of attribute @c name
 358  *
 359  * @return the new start of the GSList
 360  */
 361 GSList *
 362 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
 363
 364 /**
 365  * Finds a value of attribute @c name in @c list
 366  *
 367  * @param list a list of @c sipnameval structures
 368  * @param name attribute to find
 369  *
 370  * @return value of @c name or NULL if @c name is not found
 371  */
 372 const gchar *
 373 sipe_utils_nameval_find(const GSList *list, const gchar *name);
 374
 375 /**
 376  * Returns @c which occurrence of attribute @c name in @c list
 377  *
 378  * @c which is zero based, so 0 means first occurrence of @c name in @c list.
 379  *
 380  * @param list  a list of @c sipnameval structures
 381  * @param name  attribute to find
 382  * @param which specifies occurrence of @name in @c list
 383  *
 384  * @return value of @c name or NULL if @c name is not found
 385  */
 386 const gchar *
 387 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
 388
 389 /**
 390  * Frees memory allocated by @c list
 391  *
 392  * @param list a list of @c sipnameval structures
 393  */
 394 void
 395 sipe_utils_nameval_free(GSList *list);
 396
 397 /**
 398  * Given a string, this replaces one substring with another
 399  * and returns a newly allocated string.
 400  *
 401  * @param string      the string from which to replace stuff.
 402  * @param delimiter   the substring you want replaced.
 403  * @param replacement the substring you want as replacement.
 404  *
 405  * @return string with the substitution or NULL. Must be g_free()'d after use.
 406  */
 407 gchar *sipe_utils_str_replace(const gchar *string,
 408                               const gchar *delimiter,
 409                               const gchar *replacement);
 410
 411 /**
 412  * Remove read characters from transport buffer
 413  *
 414  * @param conn   the transport connection
 415  * @param unread pointer to the first character in the buffer
 416  */
 417 void sipe_utils_shrink_buffer(struct sipe_transport_connection *conn,
 418                               const gchar *unread);
 419 /**
 420  * Checks whether given IP address belongs to private block as defined in RFC1918
 421  *
 422  * @param ip IPv4 address in "X.X.X.X" format
 423  * @return @c TRUE if address is private
 424  */
 425 gboolean sipe_utils_ip_is_private(const char *ip);
 426
 427 /**
 428  * Generate presence key
 429  *
 430  * @param uri presence URI
 431  *
 432  * @return key string. Must be g_free()'d after use.
 433  */
 434 gchar *sipe_utils_presence_key(const gchar *uri);
 435
 436 /**
 437  * Generate subscription key
 438  *
 439  * @param event event name
 440  * @param uri   presence URI
 441  *
 442  * @return key string. Must be g_free()'d after use.
 443  */
 444 gchar *sipe_utils_subscription_key(const gchar *event,
 445                                    const gchar *uri);
 446
 447 /**
 448  * Decodes a URI into a plain string.
 449  *
 450  * @param string the string to translate.
 451  *
 452  * @return the resulting string. Must be g_free()'d after use.
 453  */
 454 gchar *sipe_utils_uri_unescape(const gchar *string);
 455
 456 /**
 457  * Tests whether given string is a Uniform Resource Identifier of audio/video
 458  * conference
 459  *
 460  * @param uri a string
 461  * @return @c TRUE if the string represents AV conference URI
 462  */
 463 gboolean sipe_utils_is_avconf_uri(const gchar *uri);
 464
 465 /**
 466  * Inserts in item in the list only if the value isn't already in that list
 467  *
 468  * @param list a singly linked list
 469  * @param data the item to insert
 470  * @param fund function to use to compare the values
 471  *
 472  * @return the new list head
 473  */
 474 GSList *
 475 slist_insert_unique_sorted(GSList *list, gpointer data, GCompareFunc func);
 476