src/core/sipe-utils.h

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