6 * Copyright (C) 2010-12 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 * SIPE Core -> Backend API - functions called by SIPE core 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 possible that a sipe_core_xxx() function can
34 * be entered through another thread while the first thread has entered the
35 * backend specific code through a sipe_backend_xxx() function.
37 ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
44 /* Forward declarations */
45 struct sipe_backend_chat_session
;
46 struct sipe_chat_session
;
47 struct sipe_core_public
;
48 struct sipe_transport_connection
;
49 struct sipe_file_transfer
;
50 struct sipe_media_call
;
53 /** MISC. STUFF **************************************************************/
55 * Get the version of the backend suitable for e.g. UserAgent
57 * @return backend version string. Will be g_free()'d.by the core.
59 gchar
*sipe_backend_version(void);
61 /** DEBUGGING ****************************************************************/
64 SIPE_DEBUG_LEVEL_INFO
,
65 SIPE_DEBUG_LEVEL_WARNING
,
66 SIPE_DEBUG_LEVEL_ERROR
,
67 SIPE_DEBUG_LEVEL_FATAL
,
71 * Output debug information without formatting
73 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
75 * @param level debug level
76 * @param msg debug message "\n" will be automatically appended.
78 void sipe_backend_debug_literal(sipe_debug_level level
,
82 * Output debug information
84 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
86 * @param level debug level
87 * @param format format string. "\n" will be automatically appended.
89 void sipe_backend_debug(sipe_debug_level level
,
91 ...) G_GNUC_PRINTF(2, 3);
93 /* Convenience macros */
94 #define SIPE_DEBUG_INFO(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO, fmt, __VA_ARGS__)
95 #define SIPE_DEBUG_INFO_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_INFO, msg)
96 #define SIPE_DEBUG_WARNING(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
97 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_WARNING, msg)
98 #define SIPE_DEBUG_ERROR(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR, fmt, __VA_ARGS__)
99 #define SIPE_DEBUG_ERROR_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_ERROR, msg)
100 #define SIPE_DEBUG_FATAL(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL, fmt, __VA_ARGS__)
101 #define SIPE_DEBUG_FATAL_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_FATAL, msg)
104 * Check backend debugging status
106 * @return TRUE if debugging is enabled
108 gboolean
sipe_backend_debug_enabled(void);
110 /** CHAT *********************************************************************/
112 void sipe_backend_chat_session_destroy(struct sipe_backend_chat_session
*session
);
113 void sipe_backend_chat_add(struct sipe_backend_chat_session
*backend_session
,
116 void sipe_backend_chat_close(struct sipe_backend_chat_session
*backend_session
);
121 struct sipe_backend_chat_session
*sipe_backend_chat_create(struct sipe_core_public
*sipe_public
,
122 struct sipe_chat_session
*session
,
125 gboolean
sipe_backend_chat_find(struct sipe_backend_chat_session
*backend_session
,
127 gboolean
sipe_backend_chat_is_operator(struct sipe_backend_chat_session
*backend_session
,
129 void sipe_backend_chat_message(struct sipe_core_public
*sipe_public
,
130 struct sipe_backend_chat_session
*backend_session
,
133 void sipe_backend_chat_operator(struct sipe_backend_chat_session
*backend_session
,
137 * Rejoin an existing chat window after connection re-establishment
139 void sipe_backend_chat_rejoin(struct sipe_core_public
*sipe_public
,
140 struct sipe_backend_chat_session
*backend_session
,
145 * Core has completed connection re-establishment.
146 * Should call sipe_core_chat_rejoin() for existing chats.
148 void sipe_backend_chat_rejoin_all(struct sipe_core_public
*sipe_public
);
149 void sipe_backend_chat_remove(struct sipe_backend_chat_session
*backend_session
,
153 * Move chat window to the front. Will be called when
154 * a user tries to join an already joined chat again.
156 void sipe_backend_chat_show(struct sipe_backend_chat_session
*backend_session
);
157 void sipe_backend_chat_topic(struct sipe_backend_chat_session
*backend_session
,
160 /** CONNECTION ***************************************************************/
162 void sipe_backend_connection_completed(struct sipe_core_public
*sipe_public
);
165 SIPE_CONNECTION_ERROR_NETWORK
= 0,
166 SIPE_CONNECTION_ERROR_INVALID_USERNAME
,
167 SIPE_CONNECTION_ERROR_INVALID_SETTINGS
,
168 SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED
,
169 SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE
,
170 SIPE_CONNECTION_ERROR_LAST
171 } sipe_connection_error
;
172 void sipe_backend_connection_error(struct sipe_core_public
*sipe_public
,
173 sipe_connection_error error
,
176 gboolean
sipe_backend_connection_is_disconnecting(struct sipe_core_public
*sipe_public
);
177 gboolean
sipe_backend_connection_is_valid(struct sipe_core_public
*sipe_public
);
179 /** DNS QUERY ****************************************************************/
181 typedef void (*sipe_dns_resolved_cb
)(gpointer data
, const gchar
*hostname
, guint port
);
183 struct sipe_dns_query
*sipe_backend_dns_query_srv(struct sipe_core_public
*sipe_public
,
184 const gchar
*protocol
,
185 const gchar
*transport
,
187 sipe_dns_resolved_cb callback
,
190 struct sipe_dns_query
*sipe_backend_dns_query_a(struct sipe_core_public
*sipe_public
,
191 const gchar
*hostname
,
193 sipe_dns_resolved_cb callback
,
196 void sipe_backend_dns_query_cancel(struct sipe_dns_query
*query
);
198 /** FILE TRANSFER ************************************************************/
200 struct sipe_backend_fd
;
202 void sipe_backend_ft_error(struct sipe_file_transfer
*ft
,
203 const gchar
*errmsg
);
204 const gchar
*sipe_backend_ft_get_error(struct sipe_file_transfer
*ft
);
205 void sipe_backend_ft_deallocate(struct sipe_file_transfer
*ft
);
208 * Try to read up to @c size bytes from file transfer connection
210 * @param ft file transfer data.
211 * @param data buffer to read data into.
212 * @param size buffer size in bytes.
214 * @return number of bytes read or negative on failure.
215 * EAGAIN should return 0 bytes read.
217 gssize
sipe_backend_ft_read(struct sipe_file_transfer
*ft
,
222 * Try to write up to @c size bytes to file transfer connection
224 * @param ft file transfer data.
225 * @param data data to write
226 * @param size buffer size in bytes.
228 * @return number of bytes read or negative on failure.
229 * EAGAIN should return 0 bytes written.
231 gssize
sipe_backend_ft_write(struct sipe_file_transfer
*ft
,
236 void sipe_backend_ft_cancel_local(struct sipe_file_transfer
*ft
);
237 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer
*ft
);
239 void sipe_backend_ft_incoming(struct sipe_core_public
*sipe_public
,
240 struct sipe_file_transfer
*ft
,
242 const gchar
*file_name
,
245 * Begins file transfer with remote peer.
247 * You can provide either opened file descriptor to use for read/write operations
248 * or ip address and port where the backend should connect.
250 * @param ft file transfer data
251 * @param fd opaque file descriptor pointer or NULL if ip and port are used
252 * @param ip ip address to connect of NULL when file descriptor is used
253 * @param port port to connect or 0 when file descriptor is used
255 void sipe_backend_ft_start(struct sipe_file_transfer
*ft
,
256 struct sipe_backend_fd
*fd
,
257 const char* ip
, unsigned port
);
260 * Check whether file transfer is incoming or outgoing
262 * @param ft file transfer data
263 * @return @c TRUE if @c ft is incoming, otherwise @c FALSE
265 gboolean
sipe_backend_ft_is_incoming(struct sipe_file_transfer
*ft
);
267 /** GROUP CHAT ***************************************************************/
269 #define SIPE_GROUPCHAT_ROOM_FILEPOST 0x00000001
270 #define SIPE_GROUPCHAT_ROOM_INVITE 0x00000002
271 #define SIPE_GROUPCHAT_ROOM_LOGGED 0x00000004
272 #define SIPE_GROUPCHAT_ROOM_PRIVATE 0x00000008
275 * Add a room found through room query
277 * @param uri room URI
278 * @param name human readable name for room
279 * @param description room description
280 * @param users number of users in the room
281 * @param flags SIPE_GROUPCHAT_ROOM_* flags
283 void sipe_backend_groupchat_room_add(struct sipe_core_public
*sipe_public
,
286 const gchar
*description
,
291 * Terminate room query
293 void sipe_backend_groupchat_room_terminate(struct sipe_core_public
*sipe_public
);
295 /** IM ***********************************************************************/
297 void sipe_backend_im_message(struct sipe_core_public
*sipe_public
,
300 void sipe_backend_im_topic(struct sipe_core_public
*sipe_public
,
304 /** MARKUP *******************************************************************/
306 gchar
*sipe_backend_markup_css_property(const gchar
*style
,
307 const gchar
*option
);
308 gchar
*sipe_backend_markup_strip_html(const gchar
*html
);
310 /** MEDIA ********************************************************************/
319 SIPE_CANDIDATE_TYPE_ANY
,
320 SIPE_CANDIDATE_TYPE_HOST
,
321 SIPE_CANDIDATE_TYPE_RELAY
,
322 SIPE_CANDIDATE_TYPE_SRFLX
,
323 SIPE_CANDIDATE_TYPE_PRFLX
327 SIPE_COMPONENT_NONE
= 0,
328 SIPE_COMPONENT_RTP
= 1,
329 SIPE_COMPONENT_RTCP
= 2
338 SIPE_NETWORK_PROTOCOL_TCP_ACTIVE
,
339 SIPE_NETWORK_PROTOCOL_TCP_PASSIVE
,
340 SIPE_NETWORK_PROTOCOL_UDP
341 } SipeNetworkProtocol
;
343 struct sipe_media_call
;
344 struct sipe_backend_media
;
345 struct sipe_backend_codec
;
346 struct sipe_backend_candidate
;
347 struct sipe_backend_stream
;
348 struct sipe_backend_media_relays
;
350 struct sipe_media_call
{
351 struct sipe_backend_media
*backend_private
;
353 void (*candidates_prepared_cb
)(struct sipe_media_call
*,
354 struct sipe_backend_stream
*);
355 void (*media_end_cb
)(struct sipe_media_call
*);
356 void (*call_accept_cb
)(struct sipe_media_call
*, gboolean local
);
357 void (*call_reject_cb
)(struct sipe_media_call
*, gboolean local
);
358 void (*call_hold_cb
) (struct sipe_media_call
*, gboolean local
,
360 void (*call_hangup_cb
)(struct sipe_media_call
*, gboolean local
);
361 void (*error_cb
)(struct sipe_media_call
*, gchar
*message
);
364 struct sipe_media_relay
{
368 struct sipe_dns_query
*dns_query
;
372 struct sipe_backend_media
*sipe_backend_media_new(struct sipe_core_public
*sipe_public
,
373 struct sipe_media_call
*call
,
374 const gchar
*participant
,
376 void sipe_backend_media_free(struct sipe_backend_media
*media
);
378 void sipe_backend_media_set_cname(struct sipe_backend_media
*media
, gchar
*cname
);
380 struct sipe_backend_media_relays
* sipe_backend_media_relays_convert(GSList
*media_relays
,
383 void sipe_backend_media_relays_free(struct sipe_backend_media_relays
*media_relays
);
385 struct sipe_backend_stream
*sipe_backend_media_add_stream(struct sipe_backend_media
*media
,
387 const gchar
*participant
,
389 SipeIceVersion ice_version
,
391 struct sipe_backend_media_relays
*media_relays
);
392 void sipe_backend_media_remove_stream(struct sipe_backend_media
*media
,
393 struct sipe_backend_stream
*stream
);
394 GSList
*sipe_backend_media_get_streams(struct sipe_backend_media
*media
);
395 struct sipe_backend_stream
*sipe_backend_media_get_stream_by_id(struct sipe_backend_media
*media
,
397 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media
*media
,
398 struct sipe_backend_stream
*stream
,
400 gboolean
sipe_backend_media_is_initiator(struct sipe_backend_media
*media
,
401 struct sipe_backend_stream
*stream
);
402 gboolean
sipe_backend_media_accepted(struct sipe_backend_media
*media
);
403 gboolean
sipe_backend_candidates_prepared(struct sipe_backend_media
*media
);
404 GList
*sipe_backend_media_get_active_local_candidates(struct sipe_backend_media
*media
,
405 struct sipe_backend_stream
*stream
);
406 GList
*sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media
*media
,
407 struct sipe_backend_stream
*stream
);
409 /* Stream handling */
410 const gchar
*sipe_backend_stream_get_id(struct sipe_backend_stream
*stream
);
411 SipeMediaType
sipe_backend_stream_get_type(struct sipe_backend_stream
*stream
);
412 void sipe_backend_stream_hold(struct sipe_backend_media
*media
,
413 struct sipe_backend_stream
*stream
,
415 void sipe_backend_stream_unhold(struct sipe_backend_media
*media
,
416 struct sipe_backend_stream
*stream
,
418 gboolean
sipe_backend_stream_is_held(struct sipe_backend_stream
*stream
);
421 struct sipe_backend_codec
*sipe_backend_codec_new(int id
,
423 SipeMediaType type
, guint clock_rate
);
424 void sipe_backend_codec_free(struct sipe_backend_codec
*codec
);
425 int sipe_backend_codec_get_id(struct sipe_backend_codec
*codec
);
427 * @return codec name. Will be g_free'd() by the core.
429 gchar
*sipe_backend_codec_get_name(struct sipe_backend_codec
*codec
);
430 guint
sipe_backend_codec_get_clock_rate(struct sipe_backend_codec
*codec
);
431 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec
*codec
,
434 GList
*sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec
*codec
);
435 gboolean
sipe_backend_set_remote_codecs(struct sipe_backend_media
*media
,
436 struct sipe_backend_stream
*stream
,
438 GList
* sipe_backend_get_local_codecs(struct sipe_backend_media
*media
,
439 struct sipe_backend_stream
*stream
);
441 /* Candidate handling */
442 struct sipe_backend_candidate
* sipe_backend_candidate_new(const gchar
*foundation
,
443 SipeComponentType component
,
444 SipeCandidateType type
,
445 SipeNetworkProtocol proto
,
446 const gchar
*ip
, guint port
,
447 const gchar
*username
,
448 const gchar
*password
);
449 void sipe_backend_candidate_free(struct sipe_backend_candidate
*candidate
);
451 * @return user name. Will be g_free'd() by the core.
453 gchar
*sipe_backend_candidate_get_username(struct sipe_backend_candidate
*candidate
);
455 * @return password. Will be g_free'd() by the core.
457 gchar
*sipe_backend_candidate_get_password(struct sipe_backend_candidate
*candidate
);
459 * @return foundation. Will be g_free'd() by the core.
461 gchar
*sipe_backend_candidate_get_foundation(struct sipe_backend_candidate
*candidate
);
463 * @return IP address string. Will be g_free'd() by the core.
465 gchar
*sipe_backend_candidate_get_ip(struct sipe_backend_candidate
*candidate
);
466 guint
sipe_backend_candidate_get_port(struct sipe_backend_candidate
*candidate
);
468 * @return IP address string. Will be g_free'd() by the core.
470 gchar
*sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate
*candidate
);
471 guint
sipe_backend_candidate_get_base_port(struct sipe_backend_candidate
*candidate
);
472 guint32
sipe_backend_candidate_get_priority(struct sipe_backend_candidate
*candidate
);
473 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate
*candidate
, guint32 priority
);
474 SipeComponentType
sipe_backend_candidate_get_component_type(struct sipe_backend_candidate
*candidate
);
475 SipeCandidateType
sipe_backend_candidate_get_type(struct sipe_backend_candidate
*candidate
);
476 SipeNetworkProtocol
sipe_backend_candidate_get_protocol(struct sipe_backend_candidate
*candidate
);
477 GList
* sipe_backend_get_local_candidates(struct sipe_backend_media
*media
,
478 struct sipe_backend_stream
*stream
);
479 void sipe_backend_media_accept(struct sipe_backend_media
*media
, gboolean local
);
480 void sipe_backend_media_hangup(struct sipe_backend_media
*media
, gboolean local
);
481 void sipe_backend_media_reject(struct sipe_backend_media
*media
, gboolean local
);
483 /** NETWORK ******************************************************************/
485 const gchar
*sipe_backend_network_ip_address(void);
487 struct sipe_backend_listendata
;
489 typedef void (*sipe_listen_start_cb
)(unsigned short port
, gpointer data
);
490 typedef void (*sipe_client_connected_cb
)(struct sipe_backend_fd
*fd
, gpointer data
);
492 struct sipe_backend_listendata
*
493 sipe_backend_network_listen_range(unsigned short port_min
,
494 unsigned short port_max
,
495 sipe_listen_start_cb listen_cb
,
496 sipe_client_connected_cb connect_cb
,
498 void sipe_backend_network_listen_cancel(struct sipe_backend_listendata
*ldata
);
500 gboolean
sipe_backend_fd_is_valid(struct sipe_backend_fd
*fd
);
501 void sipe_backend_fd_free(struct sipe_backend_fd
*fd
);
503 /** NOTIFICATIONS *************************************************************/
505 void sipe_backend_notify_message_error(struct sipe_core_public
*sipe_public
,
506 struct sipe_backend_chat_session
*backend_session
,
508 const gchar
*message
);
509 void sipe_backend_notify_message_info(struct sipe_core_public
*sipe_public
,
510 struct sipe_backend_chat_session
*backend_session
,
512 const gchar
*message
);
515 * @param msg error message. Maybe @NULL
517 void sipe_backend_notify_error(struct sipe_core_public
*sipe_public
,
521 /** SCHEDULE *****************************************************************/
523 gpointer
sipe_backend_schedule_seconds(struct sipe_core_public
*sipe_public
,
526 gpointer
sipe_backend_schedule_mseconds(struct sipe_core_public
*sipe_public
,
529 void sipe_backend_schedule_cancel(struct sipe_core_public
*sipe_public
,
532 /** SEARCH *******************************************************************/
534 struct sipe_backend_search_results
;
536 struct sipe_backend_search_results
*sipe_backend_search_results_start(struct sipe_core_public
*sipe_public
);
537 void sipe_backend_search_results_add(struct sipe_core_public
*sipe_public
,
538 struct sipe_backend_search_results
*results
,
541 const gchar
*company
,
542 const gchar
*country
,
544 void sipe_backend_search_results_finalize(struct sipe_core_public
*sipe_public
,
545 struct sipe_backend_search_results
*results
,
546 const gchar
*description
,
549 /** SETTINGS *****************************************************************/
552 SIPE_SETTING_EMAIL_URL
= 0,
553 SIPE_SETTING_EMAIL_LOGIN
,
554 SIPE_SETTING_EMAIL_PASSWORD
,
555 SIPE_SETTING_GROUPCHAT_USER
,
556 SIPE_SETTING_USER_AGENT
,
559 const gchar
*sipe_backend_setting(struct sipe_core_public
*sipe_public
,
562 /** STATUS *******************************************************************/
564 guint
sipe_backend_status(struct sipe_core_public
*sipe_public
);
565 gboolean
sipe_backend_status_changed(struct sipe_core_public
*sipe_public
,
567 const gchar
*message
);
568 void sipe_backend_status_and_note(struct sipe_core_public
*sipe_public
,
570 const gchar
*message
);
572 /** TRANSPORT ****************************************************************/
574 typedef void transport_connected_cb(struct sipe_transport_connection
*conn
);
575 typedef void transport_input_cb(struct sipe_transport_connection
*conn
);
576 typedef void transport_error_cb(struct sipe_transport_connection
*conn
,
581 const gchar
*server_name
;
584 transport_connected_cb
*connected
;
585 transport_input_cb
*input
;
586 transport_error_cb
*error
;
587 } sipe_connect_setup
;
588 struct sipe_transport_connection
*sipe_backend_transport_connect(struct sipe_core_public
*sipe_public
,
589 const sipe_connect_setup
*setup
);
590 void sipe_backend_transport_disconnect(struct sipe_transport_connection
*conn
);
591 void sipe_backend_transport_message(struct sipe_transport_connection
*conn
,
592 const gchar
*buffer
);
593 void sipe_backend_transport_flush(struct sipe_transport_connection
*conn
);
595 /** USER *********************************************************************/
597 void sipe_backend_user_feedback_typing(struct sipe_core_public
*sipe_public
,
599 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public
*sipe_public
,
603 * Present a query that is to be accepted or declined by the user
605 * @param sipe_public The handle representing the protocol instance
606 * @param message Text of the query to be shown to user
607 * @param accept_label Label to be displayed on UI control that accepts query
608 * @param decline_label Label to be displayed on UI control that declines query
609 * @param key Opaque handle uniquely identifying the query. Backend
610 * should store it for the case SIPE core requests the
611 * query to be closed prematurely.
613 void sipe_backend_user_ask(struct sipe_core_public
*sipe_public
,
614 const gchar
*message
,
615 const gchar
*accept_label
,
616 const gchar
*decline_label
,
620 * Closes the pending user query
622 * @param key Opaque handle uniquely identifying the query.
624 void sipe_backend_user_close_ask(gpointer key
);
626 /** BUDDIES ******************************************************************/
629 * sipe_backend_buddy_get/set_string(): properties a buddy can have
630 * sipe_backend_buddy_info_add(): mapped, e.g. to a string label
634 SIPE_BUDDY_INFO_DISPLAY_NAME
= 0,
635 SIPE_BUDDY_INFO_JOB_TITLE
,
636 SIPE_BUDDY_INFO_CITY
,
637 SIPE_BUDDY_INFO_STATE
,
638 SIPE_BUDDY_INFO_OFFICE
,
639 SIPE_BUDDY_INFO_DEPARTMENT
,
640 SIPE_BUDDY_INFO_COUNTRY
,
641 SIPE_BUDDY_INFO_WORK_PHONE
,
642 SIPE_BUDDY_INFO_WORK_PHONE_DISPLAY
,
643 SIPE_BUDDY_INFO_COMPANY
,
644 SIPE_BUDDY_INFO_EMAIL
,
645 SIPE_BUDDY_INFO_SITE
,
646 SIPE_BUDDY_INFO_ZIPCODE
,
647 SIPE_BUDDY_INFO_STREET
,
648 SIPE_BUDDY_INFO_MOBILE_PHONE
,
649 SIPE_BUDDY_INFO_MOBILE_PHONE_DISPLAY
,
650 SIPE_BUDDY_INFO_HOME_PHONE
,
651 SIPE_BUDDY_INFO_HOME_PHONE_DISPLAY
,
652 SIPE_BUDDY_INFO_OTHER_PHONE
,
653 SIPE_BUDDY_INFO_OTHER_PHONE_DISPLAY
,
654 SIPE_BUDDY_INFO_CUSTOM1_PHONE
,
655 SIPE_BUDDY_INFO_CUSTOM1_PHONE_DISPLAY
,
656 SIPE_BUDDY_INFO_ALIAS
, /* only for sipe_backend_buddy_info_add() */
657 SIPE_BUDDY_INFO_DEVICE
, /* only for sipe_backend_buddy_info_add() */
658 } sipe_buddy_info_fields
;
661 typedef void* sipe_backend_buddy
;
664 * Find a buddy in the given group of the buddy list, or anywhere on the
665 * list if @group_name is empty
667 * @param sipe_public The handle representing the protocol instance making the call
668 * @param buddy_name The name of the buddy
669 * @param group_name The name of the group to look in, or NULL for any group
670 * @return opaque handle to the buddy, or NULL if no buddy found
672 sipe_backend_buddy
sipe_backend_buddy_find(struct sipe_core_public
*sipe_public
,
673 const gchar
*buddy_name
,
674 const gchar
*group_name
);
677 * Find all named buddies in the given group of the buddy list, or anywhere on the
678 * list if @group_name is empty; or all buddies if @name is empty
680 * @param sipe_public The handle representing the protocol instance making the call
681 * @param name The name of the buddy
682 * @param group_name The name of the group to look in, or NULL for any group
683 * @return GSList of opaque handles to the buddies
685 GSList
* sipe_backend_buddy_find_all(struct sipe_core_public
*sipe_public
,
686 const gchar
*buddy_name
,
687 const gchar
*group_name
);
690 * Gets the name of a contact.
692 * @param sipe_public The handle representing the protocol instance making the call
693 * @param who The opaque handle to the contact as found by find_buddy
694 * @return The name. Must be freed.
696 gchar
* sipe_backend_buddy_get_name(struct sipe_core_public
*sipe_public
,
697 const sipe_backend_buddy who
);
700 * Gets the alias for a contact.
702 * @param sipe_public The handle representing the protocol instance making the call
703 * @param who The opaque handle to the contact as found by find_buddy
704 * @return The alias. Must be gfree'd.
706 gchar
* sipe_backend_buddy_get_alias(struct sipe_core_public
*sipe_public
,
707 const sipe_backend_buddy who
);
710 * Gets the server alias for a contact.
712 * @param sipe_public The handle representing the protocol instance making the call
713 * @param who The opaque handle to the contact as found by find_buddy
714 * @return The alias. Must be freed.
716 gchar
* sipe_backend_buddy_get_server_alias(struct sipe_core_public
*sipe_public
,
717 const sipe_backend_buddy who
);
720 * Gets the local alias for a contact
722 * @param sipe_public The handle representing the protocol instance making the call
723 * @param uri the budyy name
725 * @return the alias. Must be @g_free()'d.
727 gchar
*sipe_backend_buddy_get_local_alias(struct sipe_core_public
*sipe_public
,
728 const sipe_backend_buddy who
);
731 * Gets the name of the group a contact belongs to.
733 * @param sipe_public The handle representing the protocol instance making the call
734 * @param who The opaque handle to the contact as found by find_buddy
735 * @return The name. Must be freed.
737 gchar
* sipe_backend_buddy_get_group_name(struct sipe_core_public
*sipe_public
,
738 const sipe_backend_buddy who
);
741 * Called to retrieve a buddy-specific setting.
743 * @param sipe_public The handle representing the protocol instance making the call
744 * @param buddy The handle representing the buddy
745 * @param key The name of the setting
746 * @return The value of the setting. Must be freed.
748 gchar
* sipe_backend_buddy_get_string(struct sipe_core_public
*sipe_public
,
749 sipe_backend_buddy buddy
,
750 const sipe_buddy_info_fields key
);
753 * Called to set a buddy-specific setting.
755 * @param sipe_public The handle representing the protocol instance making the call
756 * @param buddy The handle representing the buddy
757 * @param key The name of the setting
758 * @param val The value to set
760 void sipe_backend_buddy_set_string(struct sipe_core_public
*sipe_public
,
761 sipe_backend_buddy buddy
,
762 const sipe_buddy_info_fields key
,
766 * Get the status token for a contact
768 * @param sipe_public The handle representing the protocol instance making the call
769 * @param uri SIP URI of the contact
773 guint
sipe_backend_buddy_get_status(struct sipe_core_public
*sipe_public
,
777 * Sets the alias for a contact.
779 * @param sipe_public The handle representing the protocol instance making the call
780 * @param who The opaque handle to the contact as found by find_buddy
781 * @param alias The location where the alias will be put
782 * case. FALSE if the buddy was not found. The value of alias will not be changed.
784 void sipe_backend_buddy_set_alias(struct sipe_core_public
*sipe_public
,
785 const sipe_backend_buddy who
,
789 * Sets the server alias for a contact.
791 * @param sipe_public The handle representing the protocol instance making the call
792 * @param who The opaque handle to the contact as found by find_buddy
793 * @param alias The server alias of the contact
795 void sipe_backend_buddy_set_server_alias(struct sipe_core_public
*sipe_public
,
796 const sipe_backend_buddy who
,
800 * Add a contact to the buddy list
802 * @param sipe_public The handle representing the protocol instance making the call
803 * @param name The name of the contact
804 * @param alias The alias of the contact
805 * @param groupname The name of the group to add this contact to
806 * @return A handle to the newly created buddy
808 sipe_backend_buddy
sipe_backend_buddy_add(struct sipe_core_public
*sipe_public
,
811 const gchar
*groupname
);
814 * Remove a contact from the buddy list
816 * @param sipe_public The handle representing the protocol instance making the call
817 * @param who The opaque handle to the contact as found by find_buddy
819 void sipe_backend_buddy_remove(struct sipe_core_public
*sipe_public
,
820 const sipe_backend_buddy who
);
823 * Notifies the user that a remote user has wants to add the local user to his
824 * or her buddy list and requires authorization to do so.
826 * @param sipe_public The handle representing the protocol instance making the call
827 * @param who The name of the user that added this account
828 * @param alias The optional alias of the remote user
829 * @param on_list True if the user is already in our list
830 * @param auth_cb The callback called when the local user accepts
831 * @param deny_cb The callback called when the local user rejects
832 * @param data Data to be passed back to the above callbacks
834 typedef void (*sipe_backend_buddy_request_authorization_cb
)(void *);
836 void sipe_backend_buddy_request_add(struct sipe_core_public
*sipe_public
,
840 void sipe_backend_buddy_request_authorization(struct sipe_core_public
*sipe_public
,
844 sipe_backend_buddy_request_authorization_cb auth_cb
,
845 sipe_backend_buddy_request_authorization_cb deny_cb
,
848 gboolean
sipe_backend_buddy_is_blocked(struct sipe_core_public
*sipe_public
,
851 void sipe_backend_buddy_set_blocked_status(struct sipe_core_public
*sipe_public
,
855 void sipe_backend_buddy_set_status(struct sipe_core_public
*sipe_public
,
860 * Gives backend a photo image associated with a SIP URI. Backend has ownership
861 * of the data and must free it when not needed.
863 * @param sipe_public The handle representing the protocol instance making the call
864 * @param who The name of the user whose photo is being set
865 * @param image_data The photo image data, must be g_free()'d by backend
866 * @param image_len Size of the image in Bytes
867 * @param photo_hash A data checksum provided by the server
869 void sipe_backend_buddy_set_photo(struct sipe_core_public
*sipe_public
,
873 const gchar
*photo_hash
);
876 * Retrieves a photo hash stored together with image data by
877 * @c sipe_backend_buddy_set_photo. Value is used by the core to detect photo
878 * file changes on server.
880 * @param sipe_public The handle representing the protocol instance making the call
881 * @param who The name of the user whose photo hash to retrieve
882 * @return a photo hash (may be NULL)
884 const gchar
*sipe_backend_buddy_get_photo_hash(struct sipe_core_public
*sipe_public
,
888 * Called when a new internal group is about to be added. If this returns FALSE,
889 * the group will not be added.
891 * @param sipe_public The handle representing the protocol instance making the call
892 * @param group The group being added
893 * @return TRUE if everything is ok, FALSE if the group should not be added
895 gboolean
sipe_backend_buddy_group_add(struct sipe_core_public
*sipe_public
,
896 const gchar
*group_name
);
899 * Present requested buddy information to the user
901 struct sipe_backend_buddy_info
;
902 struct sipe_backend_buddy_info
*sipe_backend_buddy_info_start(struct sipe_core_public
*sipe_public
);
903 void sipe_backend_buddy_info_add(struct sipe_core_public
*sipe_public
,
904 struct sipe_backend_buddy_info
*info
,
905 sipe_buddy_info_fields key
,
907 void sipe_backend_buddy_info_break(struct sipe_core_public
*sipe_public
,
908 struct sipe_backend_buddy_info
*info
);
909 void sipe_backend_buddy_info_finalize(struct sipe_core_public
*sipe_public
,
910 struct sipe_backend_buddy_info
*info
,
913 struct sipe_backend_buddy_tooltip
;
914 void sipe_backend_buddy_tooltip_add(struct sipe_core_public
*sipe_public
,
915 struct sipe_backend_buddy_tooltip
*tooltip
,
916 const gchar
*description
,
920 * Buddy menu creation
922 enum sipe_buddy_menu_type
{
923 SIPE_BUDDY_MENU_MAKE_CHAT_LEADER
= 0,
924 SIPE_BUDDY_MENU_REMOVE_FROM_CHAT
,
925 SIPE_BUDDY_MENU_INVITE_TO_CHAT
,
926 SIPE_BUDDY_MENU_NEW_CHAT
,
927 SIPE_BUDDY_MENU_MAKE_CALL
,
928 SIPE_BUDDY_MENU_SEND_EMAIL
,
929 SIPE_BUDDY_MENU_ACCESS_LEVEL_HELP
,
930 SIPE_BUDDY_MENU_CHANGE_ACCESS_LEVEL
,
931 SIPE_BUDDY_MENU_ADD_NEW_DOMAIN
,
932 SIPE_BUDDY_MENU_TYPES
935 struct sipe_backend_buddy_menu
*sipe_backend_buddy_menu_start(struct sipe_core_public
*sipe_public
);
936 struct sipe_backend_buddy_menu
*sipe_backend_buddy_menu_add(struct sipe_core_public
*sipe_public
,
937 struct sipe_backend_buddy_menu
*menu
,
939 enum sipe_buddy_menu_type type
,
941 struct sipe_backend_buddy_menu
*sipe_backend_buddy_menu_separator(struct sipe_core_public
*sipe_public
,
942 struct sipe_backend_buddy_menu
*menu
,
944 struct sipe_backend_buddy_menu
*sipe_backend_buddy_sub_menu_add(struct sipe_core_public
*sipe_public
,
945 struct sipe_backend_buddy_menu
*menu
,
947 struct sipe_backend_buddy_menu
*sub
);