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