src/core/sipe-utils.h

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