6 * Copyright (C) 2010-2017 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
;
81 void (* ft_init
)(struct sipe_file_transfer
*ft
, const gchar
*filename
,
82 gsize size
, const gchar
*who
);
83 void (* ft_start
)(struct sipe_file_transfer
*ft
, gsize total_size
);
84 gssize (* ft_read
)(struct sipe_file_transfer
*ft
, guchar
**buffer
,
85 gsize bytes_remaining
, gsize bytes_available
);
86 gssize (* ft_write
)(struct sipe_file_transfer
*ft
, const guchar
*buffer
,
88 gboolean (* ft_end
)(struct sipe_file_transfer
*ft
);
89 void (* ft_request_denied
)(struct sipe_file_transfer
*ft
);
90 void (* ft_cancelled
)(struct sipe_file_transfer
*ft
);
94 * Opaque data type for backend private data.
95 * The backend is responsible to allocate and free it.
97 struct sipe_backend_private
;
100 * SIP transport authentication scheme
102 #define SIPE_AUTHENTICATION_TYPE_UNSET 0
103 #define SIPE_AUTHENTICATION_TYPE_BASIC 1 /* internal use only */
104 #define SIPE_AUTHENTICATION_TYPE_NTLM 2
105 #define SIPE_AUTHENTICATION_TYPE_KERBEROS 3
106 #define SIPE_AUTHENTICATION_TYPE_NEGOTIATE 4 /* internal use only */
107 #define SIPE_AUTHENTICATION_TYPE_TLS_DSK 5
108 #define SIPE_AUTHENTICATION_TYPE_AUTOMATIC 6 /* always last */
113 /* user disabled calendar information publishing */
114 #define SIPE_CORE_FLAG_DONT_PUBLISH 0x00000001
116 #define SIPE_CORE_FLAG_IS(flag) \
117 ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
118 #define SIPE_CORE_FLAG_SET(flag) \
119 (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
120 #define SIPE_CORE_FLAG_UNSET(flag) \
121 (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
124 * Byte length of cryptographic key for call encryption.
126 #define SIPE_SRTP_KEY_LEN 30
129 * Public part of the Sipe data structure
131 * This part contains the information needed by the core and the backend.
133 struct sipe_core_public
{
135 * This points to the private data for the backend.
136 * The backend is responsible to allocate and free it.
138 struct sipe_backend_private
*backend_private
;
140 /* flags (see above) */
143 /* user information */
147 /* server information */
148 /* currently nothing */
152 * Initialize & destroy functions for the SIPE core
153 * Should be called on loading and unloading of the plugin.
155 void sipe_core_init(const char *locale_dir
);
156 void sipe_core_destroy(void);
158 /** Utility functions exported by the core to backends ***********************/
159 gboolean
sipe_strequal(const gchar
*left
, const gchar
*right
);
160 gboolean
sipe_strcase_equal(const gchar
*left
, const gchar
*right
);
163 sipe_utils_nameval_add(GSList
*list
, const gchar
*name
, const gchar
*value
);
166 sipe_utils_nameval_find(const GSList
*list
, const gchar
*name
);
169 sipe_utils_nameval_find_instance(const GSList
*list
, const gchar
*name
, int which
);
172 sipe_utils_nameval_free(GSList
*list
);
174 gchar
*sip_uri_from_name(const gchar
*name
);
175 gchar
*sip_uri_if_valid(const gchar
*string
);
177 /*****************************************************************************/
180 * Other functions (need to be sorted once structure becomes clear.
183 /* Get translated about string. Must be g_free'd(). */
184 gchar
*sipe_core_about(void);
186 /* Execute a scheduled action */
187 void sipe_core_schedule_execute(gpointer data
);
190 void sipe_core_update_calendar(struct sipe_core_public
*sipe_public
);
191 void sipe_core_reset_status(struct sipe_core_public
*sipe_public
);
194 void sipe_core_change_access_level_from_container(struct sipe_core_public
*sipe_public
,
196 void sipe_core_change_access_level_for_domain(struct sipe_core_public
*sipe_public
,
202 * - core: maps this to OCS protocol values
203 * maps this to translated descriptions
204 * - backend: maps this to backend status values
205 * backend token string can be used as "ID" in protocol
207 * This is passed back-and-forth and therefore defined as list, not as enum.
208 * Can be used as array index
210 #define SIPE_ACTIVITY_UNSET 0
211 #define SIPE_ACTIVITY_AVAILABLE 1
212 #define SIPE_ACTIVITY_ONLINE 2
213 #define SIPE_ACTIVITY_INACTIVE 3
214 #define SIPE_ACTIVITY_BUSY 4
215 #define SIPE_ACTIVITY_BUSYIDLE 5
216 #define SIPE_ACTIVITY_DND 6
217 #define SIPE_ACTIVITY_BRB 7
218 #define SIPE_ACTIVITY_AWAY 8
219 #define SIPE_ACTIVITY_LUNCH 9
220 #define SIPE_ACTIVITY_INVISIBLE 10
221 #define SIPE_ACTIVITY_OFFLINE 11
222 #define SIPE_ACTIVITY_ON_PHONE 12
223 #define SIPE_ACTIVITY_IN_CONF 13
224 #define SIPE_ACTIVITY_IN_MEETING 14
225 #define SIPE_ACTIVITY_OOF 15
226 #define SIPE_ACTIVITY_URGENT_ONLY 16
227 #define SIPE_ACTIVITY_NUM_TYPES 17 /* use to define array size */
229 const gchar
*sipe_core_activity_description(guint type
);
233 * Get status text for buddy.
235 * @param sipe_public Sipe core public data structure.
236 * @param uri SIP URI of the buddy
237 * @param activity activity value for buddy
238 * @param status_text backend-specific buddy status text for activity.
240 * @return HTML status text for the buddy or NULL. Must be g_free()'d.
242 gchar
*sipe_core_buddy_status(struct sipe_core_public
*sipe_public
,
245 const gchar
*status_text
);
247 void sipe_core_buddy_got_status(struct sipe_core_public
*sipe_public
,
252 * Trigger generation of buddy information label/text pairs
254 * @param sipe_public Sipe core public data structure.
255 * @param uri SIP URI of the buddy
256 * @param status_text backend-specific buddy status text for ID.
257 * @param is_online backend considers buddy to be online.
258 * @param tooltip opaque backend identifier for tooltip info. This is the
259 * parameter given to @c sipe_backend_buddy_tooltip_add()
261 struct sipe_backend_buddy_tooltip
;
262 void sipe_core_buddy_tooltip_info(struct sipe_core_public
*sipe_public
,
264 const gchar
*status_name
,
266 struct sipe_backend_buddy_tooltip
*tooltip
);
271 * @param sipe_public Sipe core public data structure
272 * @param uri SIP URI of the buddy
273 * @param group_name backend-specific group name
275 void sipe_core_buddy_add(struct sipe_core_public
*sipe_public
,
277 const gchar
*group_name
);
282 * @param sipe_public Sipe core public data structure
283 * @param uri SIP URI of the buddy
284 * @param group_name backend-specific group name
286 void sipe_core_buddy_remove(struct sipe_core_public
*sipe_public
,
288 const gchar
*group_name
);
290 void sipe_core_contact_allow_deny(struct sipe_core_public
*sipe_public
,
293 void sipe_core_group_set_alias(struct sipe_core_public
*sipe_public
,
300 struct sipe_core_public
*sipe_core_allocate(const gchar
*signin_name
,
302 const gchar
*login_account
,
303 const gchar
*password
,
305 const gchar
*email_url
,
306 const gchar
**errmsg
);
307 void sipe_core_deallocate(struct sipe_core_public
*sipe_public
);
310 * Check if SIP authentication scheme requires a password
312 * NOTE: this can be called *BEFORE* @c sipe_core_allocate()!
314 * @param authentication SIP transport authentication type
315 * @param sso TRUE if user selected Single-Sign On
317 * @return TRUE if password is required
319 gboolean
sipe_core_transport_sip_requires_password(guint authentication
,
323 * Connect to SIP server
325 void sipe_core_transport_sip_connect(struct sipe_core_public
*sipe_public
,
327 guint authentication
,
332 * Get SIP server host name
334 * @param sipe_public Sipe core public data structure
336 * @return server host name (may be @c NULL if not fully connected yet)
338 const gchar
*sipe_core_transport_sip_server_name(struct sipe_core_public
*sipe_public
);
341 * Get chat ID, f.ex. group chat URI
343 const gchar
*sipe_core_chat_id(struct sipe_core_public
*sipe_public
,
344 struct sipe_chat_session
*chat_session
);
347 * Get type of chat session, e.g. group chat
349 #define SIPE_CHAT_TYPE_UNKNOWN 0
350 #define SIPE_CHAT_TYPE_MULTIPARTY 1
351 #define SIPE_CHAT_TYPE_CONFERENCE 2
352 #define SIPE_CHAT_TYPE_GROUPCHAT 3
353 guint
sipe_core_chat_type(struct sipe_chat_session
*chat_session
);
358 void sipe_core_chat_invite(struct sipe_core_public
*sipe_public
,
359 struct sipe_chat_session
*chat_session
,
363 * Rejoin a chat after connection re-establishment
365 void sipe_core_chat_rejoin(struct sipe_core_public
*sipe_public
,
366 struct sipe_chat_session
*chat_session
);
371 void sipe_core_chat_leave(struct sipe_core_public
*sipe_public
,
372 struct sipe_chat_session
*chat_session
);
375 * Send message to chat
377 void sipe_core_chat_send(struct sipe_core_public
*sipe_public
,
378 struct sipe_chat_session
*chat_session
,
382 * Check chat lock status
385 SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED
= 0,
386 SIPE_CHAT_LOCK_STATUS_UNLOCKED
,
387 SIPE_CHAT_LOCK_STATUS_LOCKED
388 } sipe_chat_lock_status
;
389 sipe_chat_lock_status
sipe_core_chat_lock_status(struct sipe_core_public
*sipe_public
,
390 struct sipe_chat_session
*chat_session
);
395 void sipe_core_chat_modify_lock(struct sipe_core_public
*sipe_public
,
396 struct sipe_chat_session
*chat_session
,
397 const gboolean locked
);
400 * Create new session with Focus URI
402 * @param sipe_public (in) SIPE core data.
403 * @param focus_uri (in) focus URI string
405 void sipe_core_conf_create(struct sipe_core_public
*sipe_public
,
406 const gchar
*focus_uri
,
407 const gchar
*organizer
,
408 const gchar
*meeting_id
);
410 /* buddy menu callback: parameter == chat_session */
411 void sipe_core_conf_make_leader(struct sipe_core_public
*sipe_public
,
413 const gchar
*buddy_name
);
414 void sipe_core_conf_remove_from(struct sipe_core_public
*sipe_public
,
416 const gchar
*buddy_name
);
419 sipe_core_conf_entry_info(struct sipe_core_public
*sipe_public
,
420 struct sipe_chat_session
*chat_session
);
423 * Checks if given chat session has an open RDP client window.
425 * @param sipe_public (in) SIPE core data.
426 * @param chat_session (in) chat session structure
428 * @return @c TRUE if RDP session is in progress.
431 sipe_core_conf_is_viewing_appshare(struct sipe_core_public
*sipe_public
,
432 struct sipe_chat_session
*chat_session
);
434 /* call control (CSTA) */
435 void sipe_core_buddy_make_call(struct sipe_core_public
*sipe_public
,
439 void sipe_core_media_initiate_call(struct sipe_core_public
*sipe_public
,
440 const char *participant
,
441 gboolean with_video
);
442 struct sipe_media_call
;
443 struct sipe_media_stream
*
444 sipe_core_media_get_stream_by_id(struct sipe_media_call
*call
, const gchar
*id
);
447 * Called by media backend after a candidate pair for a media stream component
448 * has been established.
450 * @param stream (in) SIPE media stream data.
453 sipe_core_media_stream_candidate_pair_established(struct sipe_media_stream
*stream
);
456 sipe_core_media_stream_readable(struct sipe_media_stream
*stream
);
459 * Called by media backend when a @c SIPE_MEDIA_APPLICATION stream changes its
460 * state between writable and unwritable.
462 * @param stream (in) SIPE media stream data.
463 * @param writable (in) @c TRUE if stream has become writable, otherwise
467 sipe_core_media_stream_writable(struct sipe_media_stream
*stream
,
471 * Called by media backend when @c stream has ended and should be destroyed.
473 * @param stream (in) SIPE media stream data.
476 sipe_core_media_stream_end(struct sipe_media_stream
*stream
);
479 * Connects to a conference call specified by given chat session
481 * @param sipe_public (in) SIPE core data.
482 * @param chat_session (in) chat session structure
484 void sipe_core_media_connect_conference(struct sipe_core_public
*sipe_public
,
485 struct sipe_chat_session
*chat_session
);
488 * Retrieves the media call in progress
490 * The function checks only for voice and video calls, ignoring other types of
493 * @param sipe_public (in) SIPE core data.
495 * @return @c sipe_media_call structure or @c NULL if call is not in progress.
497 struct sipe_media_call
*
498 sipe_core_media_get_call(struct sipe_core_public
*sipe_public
);
501 * Initiates a call with given phone number
503 * @param sipe_public (in) SIPE core data.
504 * @parem phone_number (in) a mobile or landline phone number, i.e. +46123456
506 void sipe_core_media_phone_call(struct sipe_core_public
*sipe_public
,
507 const gchar
*phone_number
);
510 * Checks voice quality by making a call to the test service
512 * @param sipe_public (in) SIPE core data.
514 void sipe_core_media_test_call(struct sipe_core_public
*sipe_public
);
517 struct sipe_file_transfer
*
518 sipe_core_ft_create_outgoing(struct sipe_core_public
*sipe_public
,
522 /* application sharing */
525 * Connects to a meeting's presentation
527 * @param sipe_public (in) SIPE core data.
528 * @param chat_session (in) chat session structure
529 * @param user_must_accept (in) @c TRUE if user should be shown accept/decline
530 * dialog before the action can proceed.
532 void sipe_core_appshare_connect_conference(struct sipe_core_public
*sipe_public
,
533 struct sipe_chat_session
*chat_session
,
534 gboolean user_must_accept
);
537 gboolean
sipe_core_groupchat_query_rooms(struct sipe_core_public
*sipe_public
);
538 void sipe_core_groupchat_join(struct sipe_core_public
*sipe_public
,
542 void sipe_core_im_send(struct sipe_core_public
*sipe_public
,
545 void sipe_core_im_close(struct sipe_core_public
*sipe_public
,
549 void sipe_core_user_feedback_typing(struct sipe_core_public
*sipe_public
,
553 void sipe_core_user_ask_cb(gpointer key
, gboolean accepted
);
556 void sipe_core_group_rename(struct sipe_core_public
*sipe_public
,
557 const gchar
*old_name
,
558 const gchar
*new_name
);
560 void sipe_core_group_remove(struct sipe_core_public
*sipe_public
,
564 void sipe_core_buddy_group(struct sipe_core_public
*sipe_public
,
566 const gchar
*old_group_name
,
567 const gchar
*new_group_name
);
569 struct sipe_backend_search_token
;
570 void sipe_core_buddy_search(struct sipe_core_public
*sipe_public
,
571 struct sipe_backend_search_token
*token
,
572 const gchar
*given_name
,
573 const gchar
*surname
,
576 const gchar
*company
,
577 const gchar
*country
);
579 void sipe_core_buddy_get_info(struct sipe_core_public
*sipe_public
,
582 void sipe_core_buddy_new_chat(struct sipe_core_public
*sipe_public
,
584 void sipe_core_buddy_send_email(struct sipe_core_public
*sipe_public
,
587 struct sipe_backend_buddy_menu
;
588 struct sipe_backend_buddy_menu
*sipe_core_buddy_create_menu(struct sipe_core_public
*sipe_public
,
589 const gchar
*buddy_name
,
590 struct sipe_backend_buddy_menu
*menu
);
592 void sipe_core_buddy_menu_free(struct sipe_core_public
*sipe_public
);
595 * User/Machine has changed the user status
597 * NOTE: must *NEVER* be triggered by @c sipe_backend_status_and_note()!
599 * @param sipe_public The handle representing the protocol instance
600 * @param set_by_user @c TRUE if status has been changed by user
601 * @param activity New activity
602 * @param message New note text
604 void sipe_core_status_set(struct sipe_core_public
*sipe_public
,
605 gboolean set_by_user
,
609 #define SIPE_MSRTP_VSR_HEADER_LEN 20
610 #define SIPE_MSRTP_VSR_ENTRY_LEN 0x44
611 #define SIPE_MSRTP_VSR_FCI_WORDLEN \
612 (SIPE_MSRTP_VSR_HEADER_LEN + SIPE_MSRTP_VSR_ENTRY_LEN) / 4
614 #define SIPE_MSRTP_VSR_SOURCE_ANY 0xFFFFFFFE
615 #define SIPE_MSRTP_VSR_SOURCE_NONE 0xFFFFFFFF
618 * Fills @buffer with Video Source Request described in [MS-RTP] 2.2.12.2.
620 * @param buffer (out) destination the VSR will be written to. The byte length
621 * of @c buffer MUST be at least @c SIPE_MSRTP_VSR_HEADER_LEN +
622 * @c SIPE_MSRTP_VSR_ENTRY_LEN.
623 * @param payload_type (in) payload ID of the codec negotiated with the peer.
625 void sipe_core_msrtp_write_video_source_request(guint8
*buffer
,
626 guint8 payload_type
);
629 * Fills @buffer with customized Payload Content Scalability Information packet
630 * described in [MS-H264PF] consisting of a Stream Layout SEI Message (section
631 * 2.2.5) and a Bitstream Info SEI Message (section 2.2.7).
633 * @param buffer (out) destination the PACSI will be written to.
634 * @param nal_count (in) number of NAL units this packet describes.
636 * @return Byte length of the PACSI packet.
638 gsize
sipe_core_msrtp_write_video_scalability_info(guint8
*buffer
,