buddy: update sipe_core_buddy_got_status() API
[siplcs.git] / src / api / sipe-core.h
blobcde0a9cd548107fe586f9d2fa02dfe7f902be7ee
1 /**
2 * @file sipe-core.h
4 * pidgin-sipe
6 * Copyright (C) 2010-2018 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
23 /**
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 !!! *****************
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
44 /**
45 * Transport type
47 #define SIPE_TRANSPORT_AUTO 0
48 #define SIPE_TRANSPORT_TLS 1
49 #define SIPE_TRANSPORT_TCP 2
51 /**
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 {
62 gpointer user_data;
63 gchar *buffer;
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 */
70 /**
71 * Opaque data type for chat session
73 struct sipe_chat_session;
75 /**
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,
87 gsize size);
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);
93 /**
94 * Opaque data type for backend private data.
95 * The backend is responsible to allocate and free it.
97 struct sipe_backend_private;
99 /**
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 */
111 * Flags
113 /* user disabled calendar information publishing */
114 #define SIPE_CORE_FLAG_DONT_PUBLISH 0x00000001
115 /* user enabled insecure buddy icon download from web */
116 #define SIPE_CORE_FLAG_ALLOW_WEB_PHOTO 0x00000002
118 #define SIPE_CORE_FLAG_IS(flag) \
119 ((sipe_public->flags & SIPE_CORE_FLAG_ ## flag) == SIPE_CORE_FLAG_ ## flag)
120 #define SIPE_CORE_FLAG_SET(flag) \
121 (sipe_public->flags |= SIPE_CORE_FLAG_ ## flag)
122 #define SIPE_CORE_FLAG_UNSET(flag) \
123 (sipe_public->flags &= ~SIPE_CORE_FLAG_ ## flag)
126 * Byte length of cryptographic key for call encryption.
128 #define SIPE_SRTP_KEY_LEN 30
131 * Public part of the Sipe data structure
133 * This part contains the information needed by the core and the backend.
135 struct sipe_core_public {
137 * This points to the private data for the backend.
138 * The backend is responsible to allocate and free it.
140 struct sipe_backend_private *backend_private;
142 /* flags (see above) */
143 guint32 flags;
145 /* user information */
146 gchar *sip_name;
147 gchar *sip_domain;
149 /* server information */
150 /* currently nothing */
154 * Initialize & destroy functions for the SIPE core
155 * Should be called on loading and unloading of the plugin.
157 void sipe_core_init(const char *locale_dir);
158 void sipe_core_destroy(void);
160 /** Utility functions exported by the core to backends ***********************/
161 gboolean sipe_strequal(const gchar *left, const gchar *right);
162 gboolean sipe_strcase_equal(const gchar *left, const gchar *right);
164 GSList *
165 sipe_utils_nameval_add(GSList *list, const gchar *name, const gchar *value);
167 const gchar *
168 sipe_utils_nameval_find(const GSList *list, const gchar *name);
170 const gchar *
171 sipe_utils_nameval_find_instance(const GSList *list, const gchar *name, int which);
173 void
174 sipe_utils_nameval_free(GSList *list);
176 gchar *sip_uri_from_name(const gchar *name);
177 gchar *sip_uri_if_valid(const gchar *string);
179 /*****************************************************************************/
182 * Other functions (need to be sorted once structure becomes clear.
185 /* Get translated about string. Must be g_free'd(). */
186 gchar *sipe_core_about(void);
188 /* Execute a scheduled action */
189 void sipe_core_schedule_execute(gpointer data);
191 /* menu actions */
192 void sipe_core_update_calendar(struct sipe_core_public *sipe_public);
193 void sipe_core_reset_status(struct sipe_core_public *sipe_public);
195 /* access levels */
196 void sipe_core_change_access_level_from_container(struct sipe_core_public *sipe_public,
197 gpointer parameter);
198 void sipe_core_change_access_level_for_domain(struct sipe_core_public *sipe_public,
199 const gchar *domain,
200 guint index);
203 * Activity
204 * - core: maps this to OCS protocol values
205 * maps this to translated descriptions
206 * - backend: maps this to backend status values
207 * backend token string can be used as "ID" in protocol
209 * This is passed back-and-forth and therefore defined as list, not as enum.
210 * Can be used as array index
212 #define SIPE_ACTIVITY_UNSET 0
213 #define SIPE_ACTIVITY_AVAILABLE 1
214 #define SIPE_ACTIVITY_ONLINE 2
215 #define SIPE_ACTIVITY_INACTIVE 3
216 #define SIPE_ACTIVITY_BUSY 4
217 #define SIPE_ACTIVITY_BUSYIDLE 5
218 #define SIPE_ACTIVITY_DND 6
219 #define SIPE_ACTIVITY_BRB 7
220 #define SIPE_ACTIVITY_AWAY 8
221 #define SIPE_ACTIVITY_LUNCH 9
222 #define SIPE_ACTIVITY_INVISIBLE 10
223 #define SIPE_ACTIVITY_OFFLINE 11
224 #define SIPE_ACTIVITY_ON_PHONE 12
225 #define SIPE_ACTIVITY_IN_CONF 13
226 #define SIPE_ACTIVITY_IN_MEETING 14
227 #define SIPE_ACTIVITY_OOF 15
228 #define SIPE_ACTIVITY_URGENT_ONLY 16
229 #define SIPE_ACTIVITY_IN_PRES 17
230 #define SIPE_ACTIVITY_NUM_TYPES 18 /* use to define array size */
232 const gchar *sipe_core_activity_description(guint type);
234 /* buddy actions */
236 * Get status text for buddy.
238 * @param sipe_public Sipe core public data structure.
239 * @param uri SIP URI of the buddy
240 * @param activity activity value for buddy
241 * @param status_text backend-specific buddy status text for activity.
243 * @return HTML status text for the buddy or NULL. Must be g_free()'d.
245 gchar *sipe_core_buddy_status(struct sipe_core_public *sipe_public,
246 const gchar *uri,
247 guint activity,
248 const gchar *status_text);
251 * Received new status for buddy.
253 * @param sipe_public Sipe core public data structure.
254 * @param uri SIP URI of the buddy
255 * @param activity Activity value for buddy
256 * @param last_active Seconds since epoch when buddy entered idle state
257 * May be @c 0 if unknown or buddy is not idle.
259 void sipe_core_buddy_got_status(struct sipe_core_public *sipe_public,
260 const gchar *uri,
261 guint activity,
262 time_t last_active);
265 * Trigger generation of buddy information label/text pairs
267 * @param sipe_public Sipe core public data structure.
268 * @param uri SIP URI of the buddy
269 * @param status_text backend-specific buddy status text for ID.
270 * @param is_online backend considers buddy to be online.
271 * @param tooltip opaque backend identifier for tooltip info. This is the
272 * parameter given to @c sipe_backend_buddy_tooltip_add()
274 struct sipe_backend_buddy_tooltip;
275 void sipe_core_buddy_tooltip_info(struct sipe_core_public *sipe_public,
276 const gchar *uri,
277 const gchar *status_name,
278 gboolean is_online,
279 struct sipe_backend_buddy_tooltip *tooltip);
282 * Add a buddy
284 * @param sipe_public Sipe core public data structure
285 * @param uri SIP URI of the buddy
286 * @param group_name backend-specific group name
288 void sipe_core_buddy_add(struct sipe_core_public *sipe_public,
289 const gchar *uri,
290 const gchar *group_name);
293 * Remove a buddy
295 * @param sipe_public Sipe core public data structure
296 * @param uri SIP URI of the buddy
297 * @param group_name backend-specific group name
299 void sipe_core_buddy_remove(struct sipe_core_public *sipe_public,
300 const gchar *uri,
301 const gchar *group_name);
303 void sipe_core_contact_allow_deny(struct sipe_core_public *sipe_public,
304 const gchar *who,
305 gboolean allow);
306 void sipe_core_group_set_alias(struct sipe_core_public *sipe_public,
307 const gchar *who,
308 const gchar *alias);
311 * Setup core data
313 struct sipe_core_public *sipe_core_allocate(const gchar *signin_name,
314 gboolean sso,
315 const gchar *login_account,
316 const gchar *password,
317 const gchar *email,
318 const gchar *email_url,
319 const gchar **errmsg);
320 void sipe_core_deallocate(struct sipe_core_public *sipe_public);
323 * Check if SIP authentication scheme requires a password
325 * NOTE: this can be called *BEFORE* @c sipe_core_allocate()!
327 * @param authentication SIP transport authentication type
328 * @param sso TRUE if user selected Single-Sign On
330 * @return TRUE if password is required
332 gboolean sipe_core_transport_sip_requires_password(guint authentication,
333 gboolean sso);
336 * Connect to SIP server
338 void sipe_core_transport_sip_connect(struct sipe_core_public *sipe_public,
339 guint transport,
340 guint authentication,
341 const gchar *server,
342 const gchar *port);
345 * Get SIP server host name
347 * @param sipe_public Sipe core public data structure
349 * @return server host name (may be @c NULL if not fully connected yet)
351 const gchar *sipe_core_transport_sip_server_name(struct sipe_core_public *sipe_public);
354 * Get chat ID, f.ex. group chat URI
356 const gchar *sipe_core_chat_id(struct sipe_core_public *sipe_public,
357 struct sipe_chat_session *chat_session);
360 * Get type of chat session, e.g. group chat
362 #define SIPE_CHAT_TYPE_UNKNOWN 0
363 #define SIPE_CHAT_TYPE_MULTIPARTY 1
364 #define SIPE_CHAT_TYPE_CONFERENCE 2
365 #define SIPE_CHAT_TYPE_GROUPCHAT 3
366 guint sipe_core_chat_type(struct sipe_chat_session *chat_session);
369 * Invite to chat
371 void sipe_core_chat_invite(struct sipe_core_public *sipe_public,
372 struct sipe_chat_session *chat_session,
373 const char *name);
376 * Rejoin a chat after connection re-establishment
378 void sipe_core_chat_rejoin(struct sipe_core_public *sipe_public,
379 struct sipe_chat_session *chat_session);
382 * Leave a chat
384 void sipe_core_chat_leave(struct sipe_core_public *sipe_public,
385 struct sipe_chat_session *chat_session);
388 * Send message to chat
390 void sipe_core_chat_send(struct sipe_core_public *sipe_public,
391 struct sipe_chat_session *chat_session,
392 const char *what);
395 * Check chat lock status
397 typedef enum {
398 SIPE_CHAT_LOCK_STATUS_NOT_ALLOWED = 0,
399 SIPE_CHAT_LOCK_STATUS_UNLOCKED,
400 SIPE_CHAT_LOCK_STATUS_LOCKED
401 } sipe_chat_lock_status;
402 sipe_chat_lock_status sipe_core_chat_lock_status(struct sipe_core_public *sipe_public,
403 struct sipe_chat_session *chat_session);
406 * Lock chat
408 void sipe_core_chat_modify_lock(struct sipe_core_public *sipe_public,
409 struct sipe_chat_session *chat_session,
410 const gboolean locked);
413 * Create new session with Focus URI
415 * @param sipe_public (in) SIPE core data.
416 * @param focus_uri (in) focus URI string
418 void sipe_core_conf_create(struct sipe_core_public *sipe_public,
419 const gchar *focus_uri,
420 const gchar *organizer,
421 const gchar *meeting_id);
423 /* buddy menu callback: parameter == chat_session */
424 void sipe_core_conf_make_leader(struct sipe_core_public *sipe_public,
425 gpointer parameter,
426 const gchar *buddy_name);
427 void sipe_core_conf_remove_from(struct sipe_core_public *sipe_public,
428 gpointer parameter,
429 const gchar *buddy_name);
431 gchar *
432 sipe_core_conf_entry_info(struct sipe_core_public *sipe_public,
433 struct sipe_chat_session *chat_session);
435 typedef enum {
436 SIPE_APPSHARE_ROLE_NONE,
437 SIPE_APPSHARE_ROLE_VIEWER,
438 SIPE_APPSHARE_ROLE_PRESENTER
439 } sipe_appshare_role;
442 * Gets user's application sharing role in given chat session.
444 * @param sipe_public (in) SIPE core data.
445 * @param chat_session (in) chat session structure
447 * @return User's application sharing role.
449 sipe_appshare_role
450 sipe_core_conf_get_appshare_role(struct sipe_core_public *sipe_public,
451 struct sipe_chat_session *chat_session);
453 /* call control (CSTA) */
454 void sipe_core_buddy_make_call(struct sipe_core_public *sipe_public,
455 const gchar *phone);
457 /* media */
458 void sipe_core_media_initiate_call(struct sipe_core_public *sipe_public,
459 const char *participant,
460 gboolean with_video);
461 struct sipe_media_call;
462 struct sipe_media_stream *
463 sipe_core_media_get_stream_by_id(struct sipe_media_call *call, const gchar *id);
466 * Called by media backend after a candidate pair for a media stream component
467 * has been established.
469 * @param stream (in) SIPE media stream data.
471 void
472 sipe_core_media_stream_candidate_pair_established(struct sipe_media_stream *stream);
474 void
475 sipe_core_media_stream_readable(struct sipe_media_stream *stream);
478 * Called by media backend when a @c SIPE_MEDIA_APPLICATION stream changes its
479 * state between writable and unwritable.
481 * @param stream (in) SIPE media stream data.
482 * @param writable (in) @c TRUE if stream has become writable, otherwise
483 * @c FALSE.
485 void
486 sipe_core_media_stream_writable(struct sipe_media_stream *stream,
487 gboolean writable);
490 * Called by media backend when @c stream has ended and should be destroyed.
492 * @param stream (in) SIPE media stream data.
494 void
495 sipe_core_media_stream_end(struct sipe_media_stream *stream);
498 * Connects to a conference call specified by given chat session
500 * @param sipe_public (in) SIPE core data.
501 * @param chat_session (in) chat session structure
503 void sipe_core_media_connect_conference(struct sipe_core_public *sipe_public,
504 struct sipe_chat_session *chat_session);
507 * Retrieves the media call in progress
509 * The function checks only for voice and video calls, ignoring other types of
510 * data transfers.
512 * @param sipe_public (in) SIPE core data.
514 * @return @c sipe_media_call structure or @c NULL if call is not in progress.
516 struct sipe_media_call *
517 sipe_core_media_get_call(struct sipe_core_public *sipe_public);
520 * Initiates a call with given phone number
522 * @param sipe_public (in) SIPE core data.
523 * @parem phone_number (in) a mobile or landline phone number, i.e. +46123456
525 void sipe_core_media_phone_call(struct sipe_core_public *sipe_public,
526 const gchar *phone_number);
529 * Checks voice quality by making a call to the test service
531 * @param sipe_public (in) SIPE core data.
533 void sipe_core_media_test_call(struct sipe_core_public *sipe_public);
535 /* file transfer */
536 struct sipe_file_transfer *
537 sipe_core_ft_create_outgoing(struct sipe_core_public *sipe_public,
538 const gchar *who,
539 const gchar *file);
541 /* application sharing */
544 * Connects to a meeting's presentation
546 * @param sipe_public (in) SIPE core data.
547 * @param chat_session (in) chat session structure
548 * @param user_must_accept (in) @c TRUE if user should be shown accept/decline
549 * dialog before the action can proceed.
551 void sipe_core_appshare_connect_conference(struct sipe_core_public *sipe_public,
552 struct sipe_chat_session *chat_session,
553 gboolean user_must_accept);
556 * Starts presenting user's desktop
558 * @param sipe_public (in) SIPE core data.
559 * @param with (in) SIP URI of the contact to share the desktop with.
561 void sipe_core_appshare_share_desktop(struct sipe_core_public *sipe_public,
562 const gchar *with);
565 * Starts presenting user's desktop with a conference call
567 * @param sipe_public (in) SIPE core data.
568 * @param chat_session (in) chat session structure.
570 void
571 sipe_core_conf_share_desktop(struct sipe_core_public *sipe_public,
572 struct sipe_chat_session *chat_session);
575 * Changes the state of remote desktop control on an application sharing call.
577 * @param call (in) media call structure.
578 * @param enabled (in) @c TRUE to enable remote control, @c FALSE to disable it.
580 void
581 sipe_core_appshare_set_remote_control(struct sipe_media_call *call,
582 gboolean enabled);
585 * Gets the state of remote desktop control on an application sharing call.
587 * @param call (in) media call structure.
589 * @return @c TRUE if remote control is enabled, otherwise @c FALSE.
591 gboolean
592 sipe_core_appshare_get_remote_control(struct sipe_media_call *call);
594 /* group chat */
595 gboolean sipe_core_groupchat_query_rooms(struct sipe_core_public *sipe_public);
596 void sipe_core_groupchat_join(struct sipe_core_public *sipe_public,
597 const gchar *uri);
599 /* IM */
600 void sipe_core_im_send(struct sipe_core_public *sipe_public,
601 const gchar *who,
602 const gchar *what);
603 void sipe_core_im_close(struct sipe_core_public *sipe_public,
604 const gchar *who);
606 /* user */
607 void sipe_core_user_feedback_typing(struct sipe_core_public *sipe_public,
608 const gchar *to,
609 gboolean typing);
611 void sipe_core_user_ask_cb(gpointer key, gboolean accepted);
613 static const guint SIPE_CHOICE_CANCELLED = G_MAXUINT;
615 void sipe_core_user_ask_choice_cb(gpointer key, guint choice_id);
617 /* groups */
618 void sipe_core_group_rename(struct sipe_core_public *sipe_public,
619 const gchar *old_name,
620 const gchar *new_name);
622 void sipe_core_group_remove(struct sipe_core_public *sipe_public,
623 const gchar *name);
625 /* buddies */
626 void sipe_core_buddy_group(struct sipe_core_public *sipe_public,
627 const gchar *who,
628 const gchar *old_group_name,
629 const gchar *new_group_name);
631 struct sipe_backend_search_token;
632 void sipe_core_buddy_search(struct sipe_core_public *sipe_public,
633 struct sipe_backend_search_token *token,
634 const gchar *given_name,
635 const gchar *surname,
636 const gchar *email,
637 const gchar *sipid,
638 const gchar *company,
639 const gchar *country);
641 void sipe_core_buddy_get_info(struct sipe_core_public *sipe_public,
642 const gchar *who);
644 void sipe_core_buddy_new_chat(struct sipe_core_public *sipe_public,
645 const gchar *who);
646 void sipe_core_buddy_send_email(struct sipe_core_public *sipe_public,
647 const gchar *who);
649 struct sipe_backend_buddy_menu;
650 struct sipe_backend_buddy_menu *sipe_core_buddy_create_menu(struct sipe_core_public *sipe_public,
651 const gchar *buddy_name,
652 struct sipe_backend_buddy_menu *menu);
654 void sipe_core_buddy_menu_free(struct sipe_core_public *sipe_public);
657 * User/Machine has changed the user status
659 * NOTE: must *NEVER* be triggered by @c sipe_backend_status_and_note()!
661 * @param sipe_public The handle representing the protocol instance
662 * @param set_by_user @c TRUE if status has been changed by user
663 * @param activity New activity
664 * @param message New note text
666 void sipe_core_status_set(struct sipe_core_public *sipe_public,
667 gboolean set_by_user,
668 guint activity,
669 const gchar *note);
671 #define SIPE_MSRTP_VSR_HEADER_LEN 20
672 #define SIPE_MSRTP_VSR_ENTRY_LEN 0x44
673 #define SIPE_MSRTP_VSR_FCI_WORDLEN \
674 (SIPE_MSRTP_VSR_HEADER_LEN + SIPE_MSRTP_VSR_ENTRY_LEN) / 4
676 #define SIPE_MSRTP_VSR_SOURCE_ANY 0xFFFFFFFE
677 #define SIPE_MSRTP_VSR_SOURCE_NONE 0xFFFFFFFF
680 * Fills @buffer with Video Source Request described in [MS-RTP] 2.2.12.2.
682 * @param buffer (out) destination the VSR will be written to. The byte length
683 * of @c buffer MUST be at least @c SIPE_MSRTP_VSR_HEADER_LEN +
684 * @c SIPE_MSRTP_VSR_ENTRY_LEN.
685 * @param payload_type (in) payload ID of the codec negotiated with the peer.
687 void sipe_core_msrtp_write_video_source_request(guint8 *buffer,
688 guint8 payload_type);
691 * Fills @buffer with customized Payload Content Scalability Information packet
692 * described in [MS-H264PF] consisting of a Stream Layout SEI Message (section
693 * 2.2.5) and a Bitstream Info SEI Message (section 2.2.7).
695 * @param buffer (out) destination the PACSI will be written to.
696 * @param nal_count (in) number of NAL units this packet describes.
698 * @return Byte length of the PACSI packet.
700 gsize sipe_core_msrtp_write_video_scalability_info(guint8 *buffer,
701 guint8 nal_count);
703 #ifdef __cplusplus
705 #endif
708 Local Variables:
709 mode: c
710 c-file-style: "bsd"
711 indent-tabs-mode: t
712 tab-width: 8
713 End: