6 * Copyright (C) 2009-2012 SIPE Project <http://sipe.sourceforge.net/>
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.
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.
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
24 * Interface dependencies:
30 /* Forward declarations */
31 struct sipe_core_private
;
32 struct sipe_transport_connection
;
34 /* Our publication type keys. OCS 2007+
35 * Format: SIPE_PUB_{Category}[_{SubSategory}]
42 * Unique to the device.
44 #define SIPE_PUB_DEVICE 0
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.
52 #define SIPE_PUB_STATE_MACHINE 3
57 * Availability and activity.
60 #define SIPE_PUB_STATE_USER 2
65 * Availability, activity, meeting subject, and meeting location.
66 * First hexadecimal digit is 0x4; remaining seven hexadecimal digits are unique per device.
68 #define SIPE_PUB_STATE_CALENDAR 4
71 * Calendar state for an Out of Office meeting
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.
77 #define SIPE_PUB_STATE_CALENDAR_OOF 5
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.
85 #define SIPE_PUB_STATE_PHONE 7
90 * Start time, granularity, and free/busy data.
91 * First hexadecimal digit is 0x4; last seven hexadecimal digits uniquely define the calendar.
93 #define SIPE_PUB_CALENDAR_DATA 400
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.
101 #define SIPE_PUB_NOTE_OOF 400
104 * Returns epid value.
106 * @param sipe_private (in) SIPE core private data
108 * @return epid. Must be g_free()'d.
111 get_epid(struct sipe_core_private
*sipe_private
);
114 * Returns UUID value.
116 * @param sipe_private (in) SIPE core private data
118 * @return uuid. Must be g_free()'d.
121 get_uuid(struct sipe_core_private
*sipe_private
);
126 * @return Call ID. Must be g_free()'d.
128 gchar
*gencallid(void);
133 * @return Tag. Must be g_free()'d.
138 * Generate conference-id
139 * 32 characters long. Value space is restricted to printable ASCII characters
141 * Ex.: 8386E6AEAAA41E4AA6627BA76D43B6D1
143 * @return conference-id. Must be g_free()'d.
145 gchar
*genconfid(void);
148 * Returns instance value for particular publication type.
149 * It should be consistent for the same endpoint
150 * but different between distinct endpoints.
152 * See defined constants for keys patterned SIPE_PUB_*
155 sipe_get_pub_instance(struct sipe_core_private
*sipe_private
,
156 int publication_key
);
159 * Get contact information from SIPE account
161 * @param sipe_private (in) SIPE core private data
163 * @return Contact. Must be g_free()'d.
165 gchar
*get_contact(const struct sipe_core_private
*sipe_private
);
168 * Parses URI from SIP header
170 * @param hdr (in) To/From header
172 * @return URI with sip: prefix. Must be g_free()'d.
174 gchar
*parse_from(const gchar
*hdr
);
177 * Create sip: URI from name
181 * @return URI with sip: prefix. Must be g_free()'d.
183 gchar
*sip_uri_from_name(const gchar
*name
);
186 * Create sip: URI from SIP account user name
188 * @param sipe_private (in) SIPE core private data
190 * @return URI with sip: prefix. Must be g_free()'d.
192 #define sip_uri_self(sipe_private) (sip_uri_from_name(sipe_private->username))
195 * Create sip: URI from name or sip: URI
197 * @param string (in) name or sip: URI
199 * @return URI with sip: prefix. Must be g_free()'d.
201 gchar
*sip_uri(const gchar
*string
);
204 * Create sip: URI from name or sip: URI. Checks for invalid characters
206 * @param string (in) name or sip: URI
208 * @return URI with sip: prefix. Returns NULL if @c string contains invalid
209 * characters. Must be g_free()'d.
211 gchar
*sip_uri_if_valid(const gchar
*string
);
214 * Returns pointer to URI without sip: prefix if any (doesn't allocate memory)
216 * @param sip_uri SIP URI possibly with sip: prefix. Example: sip:first.last@hq.company.com
218 * @return pointer to URL without sip: prefix. Coresponding example: first.last@hq.company.com
220 const gchar
*sipe_get_no_sip_uri(const gchar
*sip_uri
);
223 * Tries to figure out if contact alias which stored locally
224 * is just SIP URI, not a proper display name or local alias.
226 * @param uri SIP URI with 'sip:' prefix.
227 * @param alias as returned by purple.
230 sipe_is_bad_alias(const char *uri
,
234 * Checks if provided string is empty - NULL, zero size or just series of white spaces.
235 * Doesn't modify input string.
238 is_empty(const char *st
);
240 /** Returns newly allocated string. Must be g_free()'d */
242 replace(const char *st
,
244 const char *replace
);
249 * @param type message type description (SIP or HTTP).
250 * @param header message header
251 * @param body message body or NULL
252 * @param sending TRUE if outgoing message
254 void sipe_utils_message_debug(const gchar
*type
,
260 * Tests two strings for equality.
262 * Unlike strcmp(), this function will not crash if one or both of the
263 * strings are @c NULL.
265 * Same as purple_strequal (defined only for 2.6) to maintain
266 * our backward compatibility.
268 * @param left A string
269 * @param right A string to compare with left
271 * @return @c TRUE if the strings are the same, else @c FALSE.
274 gboolean
sipe_strequal(const gchar
*left
, const gchar
*right
);
277 * Tests two strings for equality, ignoring the case
279 * Same as glib @c g_ascii_strcasecmp() but works correctly for @c NULL
280 * pointers too. Plus it doesn't complain loudly about them...
282 * @param left A string
283 * @param right A string to compare with left
285 * @return @c TRUE if the strings are the same, else @c FALSE.
288 gboolean
sipe_strcase_equal(const gchar
*left
, const gchar
*right
);
291 * Compares two strings
293 * Unlike strcmp(), this function will not crash if one or both of the
294 * strings are @c NULL.
296 * Same as g_strcmp0 (defined only for >= 2.16) to maintain
297 * our backward compatibility. The declaration is compatible to
301 * @param b A string to compare with a
303 * @return negative value if a < b; zero if a = b; positive value if a > b.
306 gint
sipe_strcompare(gconstpointer a
, gconstpointer b
);
309 * Parses a timestamp in ISO8601 format and returns a time_t.
310 * Assumes UTC if no timezone specified
312 * @param timestamp The timestamp
315 sipe_utils_str_to_time(const gchar
*timestamp
);
318 * Converts time_t to ISO8601 string.
321 * Must be g_free()'d after use.
323 * Example: 2010-02-03T23:59:59Z
326 sipe_utils_time_to_str(time_t timestamp
);
334 * Parses string of hex digits to buffer.
337 * @param hex_str (in) string of hex digits to convert.
338 * @param buff (out) newly allocated buffer. Must be g_free()'d after use.
340 * @return size of newly allocated buffer
343 hex_str_to_buff(const char *hex_str
, guint8
**buff
);
346 * Composes hex string out of provided buffer.
349 * @param buff input buffer
350 * @param buff_len length of buffer
352 * @result newly allocated hex string representing buffer. Must be g_free()'d after use.
355 buff_to_hex_str(const guint8
*buff
, const size_t buff_len
);
358 * Creates name-value pairs from given lines and appends them to @c list
360 * Lines must be in format 'name [delimiter] value'
362 * @param list a list of @c sipnameval structures
363 * @param lines array of strings in format 'name: value'
364 * @param delimiter sequence of characters between name and value
366 * @return @c FALSE if any of @c lines has incorrect format, @c TRUE otherwise
369 sipe_utils_parse_lines(GSList
**list
, gchar
**lines
, gchar
*delimiter
);
372 * Adds a name-value pair to @c list
374 * @param list a list of @c sipnameval structures
375 * @param name attribute's name
376 * @param value value of attribute @c name
378 * @return the new start of the GSList
381 sipe_utils_nameval_add(GSList
*list
, const gchar
*name
, const gchar
*value
);
384 * Finds a value of attribute @c name in @c list
386 * @param list a list of @c sipnameval structures
387 * @param name attribute to find
389 * @return value of @c name or NULL if @c name is not found
392 sipe_utils_nameval_find(const GSList
*list
, const gchar
*name
);
395 * Returns @c which occurrence of attribute @c name in @c list
397 * @c which is zero based, so 0 means first occurrence of @c name in @c list.
399 * @param list a list of @c sipnameval structures
400 * @param name attribute to find
401 * @param which specifies occurrence of @name in @c list
403 * @return value of @c name or NULL if @c name is not found
406 sipe_utils_nameval_find_instance(const GSList
*list
, const gchar
*name
, int which
);
409 * Frees memory allocated by @c list
411 * @param list a list of @c sipnameval structures
414 sipe_utils_nameval_free(GSList
*list
);
417 * Given a string, this replaces one substring with another
418 * and returns a newly allocated string.
420 * @param string the string from which to replace stuff.
421 * @param delimiter the substring you want replaced.
422 * @param replacement the substring you want as replacement.
424 * @return string with the substitution or NULL. Must be g_free()'d after use.
426 gchar
*sipe_utils_str_replace(const gchar
*string
,
427 const gchar
*delimiter
,
428 const gchar
*replacement
);
431 * Remove read characters from transport buffer
433 * @param conn the transport connection
434 * @param unread pointer to the first character in the buffer
436 void sipe_utils_shrink_buffer(struct sipe_transport_connection
*conn
,
437 const gchar
*unread
);
439 * Checks whether given IP address belongs to private block as defined in RFC1918
441 * @param ip IPv4 address in "X.X.X.X" format
442 * @return @c TRUE if address is private
444 gboolean
sipe_utils_ip_is_private(const char *ip
);
447 * Generate presence key
449 * @param uri presence URI
451 * @return key string. Must be g_free()'d after use.
453 gchar
*sipe_utils_presence_key(const gchar
*uri
);
456 * Generate subscription key
458 * @param event event name
459 * @param uri presence URI
461 * @return key string. Must be g_free()'d after use.
463 gchar
*sipe_utils_subscription_key(const gchar
*event
,
467 * Decodes a URI into a plain string.
469 * @param string the string to translate.
471 * @return the resulting string. Must be g_free()'d after use.
473 gchar
*sipe_utils_uri_unescape(const gchar
*string
);
476 * Tests whether given string is a Uniform Resource Identifier of audio/video
479 * @param uri a string
480 * @return @c TRUE if the string represents AV conference URI
482 gboolean
sipe_utils_is_avconf_uri(const gchar
*uri
);
485 * Inserts in item in the list only if the value isn't already in that list
487 * @param list a singly linked list
488 * @param data the item to insert
489 * @param fund function to use to compare the values
491 * @return the new list head
494 slist_insert_unique_sorted(GSList
*list
, gpointer data
, GCompareFunc func
);