6 * Copyright (C) 2010-11 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 !!! *****************
46 * - core: maps this to OCS protocol values
47 * - backend: maps this to backend status values
51 SIPE_ACTIVITY_UNSET
= 0,
53 SIPE_ACTIVITY_INACTIVE
,
55 SIPE_ACTIVITY_BUSYIDLE
,
60 SIPE_ACTIVITY_OFFLINE
,
61 SIPE_ACTIVITY_ON_PHONE
,
62 SIPE_ACTIVITY_IN_CONF
,
63 SIPE_ACTIVITY_IN_MEETING
,
65 SIPE_ACTIVITY_URGENT_ONLY
,
66 SIPE_ACTIVITY_NUM_TYPES
72 #define SIPE_TRANSPORT_AUTO 0
73 #define SIPE_TRANSPORT_TLS 1
74 #define SIPE_TRANSPORT_TCP 2
77 * Transport connection (public part)
79 * The receiver in the backend fills "buffer". The backend has to zero
80 * terminate the buffer before calling the processing function in the core.
82 * The processing function in the core can remove content from the buffer.
83 * It has to update buffer_used accordingly.
86 struct sipe_transport_connection
{
89 gsize buffer_used
; /* 0 < buffer_used < buffer_length */
90 gsize buffer_length
; /* read-only */
91 guint type
; /* read-only */
92 guint client_port
; /* read-only */
96 * Opaque data type for chat session
98 struct sipe_chat_session
;
101 * File transport (public part)
103 struct sipe_file_transfer
{
104 struct sipe_backend_file_transfer
*backend_private
;
108 * Opaque data type for backend private data.
109 * The backend is responsible to allocate and free it.
111 struct sipe_backend_private
;
116 #define SIPE_CORE_FLAG_KRB5 0x00000001 /* user enabled Kerberos 5 */
117 #define SIPE_CORE_FLAG_SSO 0x00000002 /* user enabled Single-Sign On */
118 #define SIPE_CORE_FLAG_TLS_DSK 0x00000004 /* user enabled TLS-DSK */
120 #define SIPE_CORE_FLAG_IS(flag) \
121 ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
122 #define SIPE_CORE_FLAG_SET(flag) \
123 (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
124 #define SIPE_CORE_FLAG_UNSET(flag) \
125 (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
128 * Public part of the Sipe data structure
130 * This part contains the information needed by the core and the backend.
132 struct sipe_core_public
{
134 * This points to the private data for the backend.
135 * The backend is responsible to allocate and free it.
137 struct sipe_backend_private
*backend_private
;
139 /* flags (see above) */
142 /* user information */
146 /* server information */
147 guint keepalive_timeout
;
151 * Initialize & destroy functions for the SIPE core
152 * Should be called on loading and unloading of the plugin.
154 void sipe_core_init(const char *locale_dir
);
155 void sipe_core_destroy(void);
157 /** Utility functions exported by the core to backends ***********************/
158 gboolean
sipe_strequal(const gchar
*left
, const gchar
*right
);
161 sipe_utils_nameval_add(GSList
*list
, const gchar
*name
, const gchar
*value
);
164 sipe_utils_nameval_find(const GSList
*list
, const gchar
*name
);
167 sipe_utils_nameval_find_instance(const GSList
*list
, const gchar
*name
, int which
);
170 sipe_utils_nameval_free(GSList
*list
);
172 gboolean
sipe_utils_is_avconf_uri(const gchar
*uri
);
174 gchar
*sip_uri_from_name(const gchar
*name
);
176 /*****************************************************************************/
179 * Other functions (need to be sorted once structure becomes clear.
182 /* Get translated about string. Must be g_free'd(). */
183 gchar
*sipe_core_about(void);
185 /* Execute a scheduled action */
186 void sipe_core_schedule_execute(gpointer data
);
189 void sipe_core_update_calendar(struct sipe_core_public
*sipe_public
);
190 void sipe_core_reset_status(struct sipe_core_public
*sipe_public
);
194 * Get status text for buddy.
196 * @param sipe_public Sipe core public data structure.
197 * @param name backend-specific buddy name.
198 * @param activity activity value for buddy
199 * @param status_text backend-specific buddy status text for activity.
201 * @return HTML status text for the buddy or NULL. Must be g_free()'d.
203 gchar
*sipe_core_buddy_status(struct sipe_core_public
*sipe_public
,
205 const sipe_activity activity
,
206 const gchar
*status_text
);
208 void sipe_core_buddy_got_status(struct sipe_core_public
*sipe_public
,
210 const gchar
*status_id
);
213 * Return a list with buddy information label/text pairs
215 * @param sipe_public Sipe core public data structure.
216 * @param name backend-specific buddy name.
217 * @param status_text backend-specific buddy status text for ID.
218 * @param is_online backend considers buddy to be online.
220 * @return GSList of struct sipe_buddy_info or NULL. Must be freed by caller.
222 struct sipe_buddy_info
{ /* must be g_free()'d */
224 gchar
*text
; /* must be g_free()'d */
226 GSList
*sipe_core_buddy_info(struct sipe_core_public
*sipe_public
,
228 const gchar
*status_name
,
234 * @param sipe_public Sipe core public data structure
235 * @param name backend-specific buddy name
236 * @param group_name backend-specific group name
238 void sipe_core_buddy_add(struct sipe_core_public
*sipe_public
,
240 const gchar
*group_name
);
245 * @param sipe_public Sipe core public data structure
246 * @param name backend-specific buddy name
247 * @param group_name backend-specific group name
249 void sipe_core_buddy_remove(struct sipe_core_public
*sipe_public
,
251 const gchar
*group_name
);
253 void sipe_core_contact_allow_deny(struct sipe_core_public
*sipe_public
,
254 const gchar
*who
, gboolean allow
);
255 void sipe_core_group_set_user(struct sipe_core_public
*sipe_public
,
261 struct sipe_core_public
*sipe_core_allocate(const gchar
*signin_name
,
262 const gchar
*login_domain
,
263 const gchar
*login_account
,
264 const gchar
*password
,
266 const gchar
*email_url
,
267 const gchar
**errmsg
);
268 void sipe_core_deallocate(struct sipe_core_public
*sipe_public
);
271 * Connect to SIP server
273 void sipe_core_transport_sip_connect(struct sipe_core_public
*sipe_public
,
277 void sipe_core_transport_sip_keepalive(struct sipe_core_public
*sipe_public
);
282 void sipe_core_chat_invite(struct sipe_core_public
*sipe_public
,
283 struct sipe_chat_session
*chat_session
,
287 * Rejoin a chat after connection re-establishment
289 void sipe_core_chat_rejoin(struct sipe_core_public
*sipe_public
,
290 struct sipe_chat_session
*chat_session
);
295 void sipe_core_chat_leave(struct sipe_core_public
*sipe_public
,
296 struct sipe_chat_session
*chat_session
);
299 * Send message to chat
301 void sipe_core_chat_send(struct sipe_core_public
*sipe_public
,
302 struct sipe_chat_session
*chat_session
,
306 * Check chat lock status
309 SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED
= 0,
310 SIPE_CHAT_LOCK_STATUS_UNLOCKED
,
311 SIPE_CHAT_LOCK_STATUS_LOCKED
312 } sipe_chat_lock_status
;
313 sipe_chat_lock_status
sipe_core_chat_lock_status(struct sipe_core_public
*sipe_public
,
314 struct sipe_chat_session
*chat_session
);
319 void sipe_core_chat_modify_lock(struct sipe_core_public
*sipe_public
,
320 struct sipe_chat_session
*chat_session
,
321 const gboolean locked
);
324 * Create new session with Focus URI
326 * @param sipe_public (in) SIPE core data.
327 * @param focus_uri (in) focus URI string
329 * @return new SIP session
332 sipe_core_conf_create(struct sipe_core_public
*sipe_public
,
333 const gchar
*focus_uri
);
336 void sipe_core_media_initiate_call(struct sipe_core_public
*sipe_public
,
337 const char *participant
,
338 gboolean with_video
);
340 * Connects to a conference call specified by given chat session
342 * @param sipe_public (in) SIPE core data.
343 * @param chat_session (in) chat session structure
345 void sipe_core_media_connect_conference(struct sipe_core_public
*sipe_public
,
346 struct sipe_chat_session
*chat_session
);
349 * Checks whether there is a media call in progress
351 * @param sipe_public (in) SIPE core data.
353 * @return @c TRUE if media call is in progress
355 gboolean
sipe_core_media_in_call(struct sipe_core_public
*sipe_public
);
358 struct sipe_file_transfer
*sipe_core_ft_allocate(struct sipe_core_public
*sipe_public
);
359 void sipe_core_ft_deallocate(struct sipe_file_transfer
*ft
);
360 void sipe_core_ft_cancel(struct sipe_file_transfer
*ft
);
361 void sipe_core_ft_incoming_init(struct sipe_file_transfer
*ft
);
362 void sipe_core_ft_outgoing_init(struct sipe_file_transfer
*ft
,
363 const gchar
*filename
, gsize size
,
366 void sipe_core_tftp_incoming_start(struct sipe_file_transfer
*ft
,
368 gboolean
sipe_core_tftp_incoming_stop(struct sipe_file_transfer
*ft
);
369 void sipe_core_tftp_outgoing_start(struct sipe_file_transfer
*ft
,
371 gboolean
sipe_core_tftp_outgoing_stop(struct sipe_file_transfer
*ft
);
372 gssize
sipe_core_tftp_read(struct sipe_file_transfer
*ft
, guchar
**buffer
,
373 gsize bytes_remaining
, gsize bytes_available
);
374 gssize
sipe_core_tftp_write(struct sipe_file_transfer
*ft
, const guchar
*buffer
,
377 gboolean
sipe_core_groupchat_query_rooms(struct sipe_core_public
*sipe_public
);
378 void sipe_core_groupchat_join(struct sipe_core_public
*sipe_public
,
382 void sipe_core_im_send(struct sipe_core_public
*sipe_public
,
387 void sipe_core_user_feedback_typing(struct sipe_core_public
*sipe_public
,
390 void sipe_core_user_ask_cb(gpointer key
, gboolean accepted
);
393 void sipe_core_group_rename(struct sipe_core_public
*sipe_public
,
394 const gchar
*old_name
,
395 const gchar
*new_name
);
397 void sipe_core_group_remove(struct sipe_core_public
*sipe_public
,
401 void sipe_core_buddy_group(struct sipe_core_public
*sipe_public
,
403 const gchar
*old_group_name
,
404 const gchar
*new_group_name
);
406 void sipe_core_buddy_search(struct sipe_core_public
*sipe_public
,
407 const gchar
*given_name
,
408 const gchar
*surname
,
409 const gchar
*company
,
410 const gchar
*country
);