6 * Copyright (C) 2010-2013 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
25 * Backend -> SIPE Core API - functions called by backend code
27 ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
29 * The SIPE core assumes atomicity and is *NOT* thread-safe.
31 * It *does not* protect any of its data structures or code paths with locks!
33 * In no circumstances it must be interrupted by another thread calling
34 * sipe_core_xxx() while the first thread has entered the SIPE core through
35 * a sipe_core_xxx() function.
37 ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
47 #define SIPE_TRANSPORT_AUTO 0
48 #define SIPE_TRANSPORT_TLS 1
49 #define SIPE_TRANSPORT_TCP 2
52 * Transport connection (public part)
54 * The receiver in the backend fills "buffer". The backend has to zero
55 * terminate the buffer before calling the processing function in the core.
57 * The processing function in the core can remove content from the buffer.
58 * It has to update buffer_used accordingly.
61 struct sipe_transport_connection
{
64 gsize buffer_used
; /* 0 < buffer_used < buffer_length */
65 gsize buffer_length
; /* read-only */
66 guint type
; /* read-only */
67 guint client_port
; /* read-only */
71 * Opaque data type for chat session
73 struct sipe_chat_session
;
76 * File transport (public part)
78 struct sipe_file_transfer
{
79 struct sipe_backend_file_transfer
*backend_private
;
83 * Opaque data type for backend private data.
84 * The backend is responsible to allocate and free it.
86 struct sipe_backend_private
;
89 * SIP transport authentication scheme
91 #define SIPE_AUTHENTICATION_TYPE_UNSET 0
92 #define SIPE_AUTHENTICATION_TYPE_NTLM 1
93 #define SIPE_AUTHENTICATION_TYPE_KERBEROS 2
94 #define SIPE_AUTHENTICATION_TYPE_NEGOTIATE 3 /* internal use only */
95 #define SIPE_AUTHENTICATION_TYPE_TLS_DSK 4
100 /* user disabled calendar information publishing */
101 #define SIPE_CORE_FLAG_DONT_PUBLISH 0x00000001
103 #define SIPE_CORE_FLAG_IS(flag) \
104 ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
105 #define SIPE_CORE_FLAG_SET(flag) \
106 (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
107 #define SIPE_CORE_FLAG_UNSET(flag) \
108 (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
111 * Public part of the Sipe data structure
113 * This part contains the information needed by the core and the backend.
115 struct sipe_core_public
{
117 * This points to the private data for the backend.
118 * The backend is responsible to allocate and free it.
120 struct sipe_backend_private
*backend_private
;
122 /* flags (see above) */
125 /* user information */
129 /* server information */
130 guint keepalive_timeout
;
134 * Initialize & destroy functions for the SIPE core
135 * Should be called on loading and unloading of the plugin.
137 void sipe_core_init(const char *locale_dir
);
138 void sipe_core_destroy(void);
140 /** Utility functions exported by the core to backends ***********************/
141 gboolean
sipe_strequal(const gchar
*left
, const gchar
*right
);
144 sipe_utils_nameval_add(GSList
*list
, const gchar
*name
, const gchar
*value
);
147 sipe_utils_nameval_find(const GSList
*list
, const gchar
*name
);
150 sipe_utils_nameval_find_instance(const GSList
*list
, const gchar
*name
, int which
);
153 sipe_utils_nameval_free(GSList
*list
);
155 gchar
*sip_uri_from_name(const gchar
*name
);
156 gchar
*sip_uri_if_valid(const gchar
*string
);
158 /*****************************************************************************/
161 * Other functions (need to be sorted once structure becomes clear.
164 /* Get translated about string. Must be g_free'd(). */
165 gchar
*sipe_core_about(void);
167 /* Execute a scheduled action */
168 void sipe_core_schedule_execute(gpointer data
);
171 void sipe_core_update_calendar(struct sipe_core_public
*sipe_public
);
172 void sipe_core_reset_status(struct sipe_core_public
*sipe_public
);
175 void sipe_core_change_access_level_from_container(struct sipe_core_public
*sipe_public
,
177 void sipe_core_change_access_level_for_domain(struct sipe_core_public
*sipe_public
,
183 * - core: maps this to OCS protocol values
184 * maps this to translated descriptions
185 * - backend: maps this to backend status values
186 * backend token string can be used as "ID" in protocol
188 * This is passed back-and-forth and therefore defined as list, not as enum.
189 * Can be used as array index
191 #define SIPE_ACTIVITY_UNSET 0
192 #define SIPE_ACTIVITY_AVAILABLE 1
193 #define SIPE_ACTIVITY_ONLINE 2
194 #define SIPE_ACTIVITY_INACTIVE 3
195 #define SIPE_ACTIVITY_BUSY 4
196 #define SIPE_ACTIVITY_BUSYIDLE 5
197 #define SIPE_ACTIVITY_DND 6
198 #define SIPE_ACTIVITY_BRB 7
199 #define SIPE_ACTIVITY_AWAY 8
200 #define SIPE_ACTIVITY_LUNCH 9
201 #define SIPE_ACTIVITY_INVISIBLE 10
202 #define SIPE_ACTIVITY_OFFLINE 11
203 #define SIPE_ACTIVITY_ON_PHONE 12
204 #define SIPE_ACTIVITY_IN_CONF 13
205 #define SIPE_ACTIVITY_IN_MEETING 14
206 #define SIPE_ACTIVITY_OOF 15
207 #define SIPE_ACTIVITY_URGENT_ONLY 16
208 #define SIPE_ACTIVITY_NUM_TYPES 17 /* use to define array size */
210 const gchar
*sipe_core_activity_description(guint type
);
214 * Get status text for buddy.
216 * @param sipe_public Sipe core public data structure.
217 * @param uri SIP URI of the buddy
218 * @param activity activity value for buddy
219 * @param status_text backend-specific buddy status text for activity.
221 * @return HTML status text for the buddy or NULL. Must be g_free()'d.
223 gchar
*sipe_core_buddy_status(struct sipe_core_public
*sipe_public
,
226 const gchar
*status_text
);
228 void sipe_core_buddy_got_status(struct sipe_core_public
*sipe_public
,
233 * Trigger generation of buddy information label/text pairs
235 * @param sipe_public Sipe core public data structure.
236 * @param uri SIP URI of the buddy
237 * @param status_text backend-specific buddy status text for ID.
238 * @param is_online backend considers buddy to be online.
239 * @param tooltip opaque backend identifier for tooltip info. This is the
240 * parameter given to @c sipe_backend_buddy_tooltip_add()
242 struct sipe_backend_buddy_tooltip
;
243 void sipe_core_buddy_tooltip_info(struct sipe_core_public
*sipe_public
,
245 const gchar
*status_name
,
247 struct sipe_backend_buddy_tooltip
*tooltip
);
252 * @param sipe_public Sipe core public data structure
253 * @param uri SIP URI of the buddy
254 * @param group_name backend-specific group name
256 void sipe_core_buddy_add(struct sipe_core_public
*sipe_public
,
258 const gchar
*group_name
);
263 * @param sipe_public Sipe core public data structure
264 * @param uri SIP URI of the buddy
265 * @param group_name backend-specific group name
267 void sipe_core_buddy_remove(struct sipe_core_public
*sipe_public
,
269 const gchar
*group_name
);
271 void sipe_core_contact_allow_deny(struct sipe_core_public
*sipe_public
,
274 void sipe_core_group_set_alias(struct sipe_core_public
*sipe_public
,
281 struct sipe_core_public
*sipe_core_allocate(const gchar
*signin_name
,
283 const gchar
*login_domain
,
284 const gchar
*login_account
,
285 const gchar
*password
,
287 const gchar
*email_url
,
288 const gchar
**errmsg
);
289 void sipe_core_deallocate(struct sipe_core_public
*sipe_public
);
292 * Check if SIP authentication scheme requires a password
294 * NOTE: this can be called *BEFORE* @c sipe_core_allocate()!
296 * @param authentication SIP transport authentication type
297 * @param sso TRUE if user selected Single-Sign On
299 * @return TRUE if password is required
301 gboolean
sipe_core_transport_sip_requires_password(guint authentication
,
305 * Connect to SIP server
307 void sipe_core_transport_sip_connect(struct sipe_core_public
*sipe_public
,
309 guint authentication
,
312 void sipe_core_transport_sip_keepalive(struct sipe_core_public
*sipe_public
);
317 void sipe_core_chat_invite(struct sipe_core_public
*sipe_public
,
318 struct sipe_chat_session
*chat_session
,
322 * Rejoin a chat after connection re-establishment
324 void sipe_core_chat_rejoin(struct sipe_core_public
*sipe_public
,
325 struct sipe_chat_session
*chat_session
);
330 void sipe_core_chat_leave(struct sipe_core_public
*sipe_public
,
331 struct sipe_chat_session
*chat_session
);
334 * Send message to chat
336 void sipe_core_chat_send(struct sipe_core_public
*sipe_public
,
337 struct sipe_chat_session
*chat_session
,
341 * Check chat lock status
344 SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED
= 0,
345 SIPE_CHAT_LOCK_STATUS_UNLOCKED
,
346 SIPE_CHAT_LOCK_STATUS_LOCKED
347 } sipe_chat_lock_status
;
348 sipe_chat_lock_status
sipe_core_chat_lock_status(struct sipe_core_public
*sipe_public
,
349 struct sipe_chat_session
*chat_session
);
354 void sipe_core_chat_modify_lock(struct sipe_core_public
*sipe_public
,
355 struct sipe_chat_session
*chat_session
,
356 const gboolean locked
);
359 * Create new session with Focus URI
361 * @param sipe_public (in) SIPE core data.
362 * @param focus_uri (in) focus URI string
364 * @return new SIP session
367 sipe_core_conf_create(struct sipe_core_public
*sipe_public
,
368 const gchar
*focus_uri
);
370 /* buddy menu callback: parameter == chat_session */
371 void sipe_core_conf_make_leader(struct sipe_core_public
*sipe_public
,
373 const gchar
*buddy_name
);
374 void sipe_core_conf_remove_from(struct sipe_core_public
*sipe_public
,
376 const gchar
*buddy_name
);
378 /* call control (CSTA) */
379 void sipe_core_buddy_make_call(struct sipe_core_public
*sipe_public
,
383 void sipe_core_media_initiate_call(struct sipe_core_public
*sipe_public
,
384 const char *participant
,
385 gboolean with_video
);
387 * Connects to a conference call specified by given chat session
389 * @param sipe_public (in) SIPE core data.
390 * @param chat_session (in) chat session structure
392 void sipe_core_media_connect_conference(struct sipe_core_public
*sipe_public
,
393 struct sipe_chat_session
*chat_session
);
396 * Checks whether there is a media call in progress
398 * @param sipe_public (in) SIPE core data.
400 * @return @c TRUE if media call is in progress
402 gboolean
sipe_core_media_in_call(struct sipe_core_public
*sipe_public
);
405 * Checks voice quality by making a call to the test service
407 * @param sipe_public (in) SIPE core data.
409 void sipe_core_media_test_call(struct sipe_core_public
*sipe_public
);
412 struct sipe_file_transfer
*sipe_core_ft_allocate(struct sipe_core_public
*sipe_public
);
413 void sipe_core_ft_deallocate(struct sipe_file_transfer
*ft
);
414 void sipe_core_ft_cancel(struct sipe_file_transfer
*ft
);
415 void sipe_core_ft_incoming_init(struct sipe_file_transfer
*ft
);
416 void sipe_core_ft_outgoing_init(struct sipe_file_transfer
*ft
,
417 const gchar
*filename
, gsize size
,
420 void sipe_core_tftp_incoming_start(struct sipe_file_transfer
*ft
,
422 gboolean
sipe_core_tftp_incoming_stop(struct sipe_file_transfer
*ft
);
423 void sipe_core_tftp_outgoing_start(struct sipe_file_transfer
*ft
,
425 gboolean
sipe_core_tftp_outgoing_stop(struct sipe_file_transfer
*ft
);
426 gssize
sipe_core_tftp_read(struct sipe_file_transfer
*ft
, guchar
**buffer
,
427 gsize bytes_remaining
, gsize bytes_available
);
428 gssize
sipe_core_tftp_write(struct sipe_file_transfer
*ft
, const guchar
*buffer
,
431 gboolean
sipe_core_groupchat_query_rooms(struct sipe_core_public
*sipe_public
);
432 void sipe_core_groupchat_join(struct sipe_core_public
*sipe_public
,
436 void sipe_core_im_send(struct sipe_core_public
*sipe_public
,
439 void sipe_core_im_close(struct sipe_core_public
*sipe_public
,
443 void sipe_core_user_feedback_typing(struct sipe_core_public
*sipe_public
,
446 void sipe_core_user_ask_cb(gpointer key
, gboolean accepted
);
449 void sipe_core_group_rename(struct sipe_core_public
*sipe_public
,
450 const gchar
*old_name
,
451 const gchar
*new_name
);
453 void sipe_core_group_remove(struct sipe_core_public
*sipe_public
,
457 void sipe_core_buddy_group(struct sipe_core_public
*sipe_public
,
459 const gchar
*old_group_name
,
460 const gchar
*new_group_name
);
462 struct sipe_backend_search_token
;
463 void sipe_core_buddy_search(struct sipe_core_public
*sipe_public
,
464 struct sipe_backend_search_token
*token
,
465 const gchar
*given_name
,
466 const gchar
*surname
,
468 const gchar
*company
,
469 const gchar
*country
);
471 void sipe_core_buddy_get_info(struct sipe_core_public
*sipe_public
,
474 void sipe_core_buddy_new_chat(struct sipe_core_public
*sipe_public
,
476 void sipe_core_buddy_send_email(struct sipe_core_public
*sipe_public
,
479 struct sipe_backend_buddy_menu
;
480 struct sipe_backend_buddy_menu
*sipe_core_buddy_create_menu(struct sipe_core_public
*sipe_public
,
481 const gchar
*buddy_name
,
482 struct sipe_backend_buddy_menu
*menu
);
484 void sipe_core_buddy_menu_free(struct sipe_core_public
*sipe_public
);
487 void sipe_core_status_set(struct sipe_core_public
*sipe_public
,
490 void sipe_core_status_idle(struct sipe_core_public
*sipe_public
);