?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
Release 1.25.0 -- Buddy Idle Time, RTF
[siplcs.git] / src / api / sipe-backend.h
blob850e4cf2a4135b7e0c06dbdab1d2c1d639eb2540
1 /**
2 * @file sipe-backend.h
3 *
4 * pidgin-sipe
5 *
6 * Copyright (C) 2010-2018 SIPE Project <http://sipe.sourceforge.net/>
7 *
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.
12 *
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.
17 *
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
21 */
22
23 /**
24 *
25 * SIPE Core -> Backend API - functions called by SIPE core code
26 *
27 ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
28 *
29 * The SIPE core assumes atomicity and is *NOT* thread-safe.
30 *
31 * It *does not* protect any of its data structures or code paths with locks!
32 *
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.
36 *
37 ***************** !!! IMPORTANT NOTE FOR BACKEND CODERS !!! *****************
38 */
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
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;
51 struct sipe_media;
52
53 /** MISC. STUFF **************************************************************/
54 /**
55 * Get the version of the backend suitable for e.g. UserAgent
56 *
57 * @return backend version string. Will be g_free()'d.by the core.
58 */
59 gchar *sipe_backend_version(void);
60
61 /** DEBUGGING ****************************************************************/
62
63 typedef enum {
64 SIPE_LOG_LEVEL_INFO,
65 SIPE_LOG_LEVEL_WARNING,
66 SIPE_LOG_LEVEL_ERROR,
67 SIPE_DEBUG_LEVEL_INFO,
68 SIPE_DEBUG_LEVEL_WARNING,
69 SIPE_DEBUG_LEVEL_ERROR,
70 } sipe_debug_level;
71 #define SIPE_DEBUG_LEVEL_LOWEST SIPE_DEBUG_LEVEL_INFO
72
73 /**
74 * Output debug information without formatting
75 *
76 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
77 *
78 * @param level debug level
79 * @param msg debug message "\n" will be automatically appended.
80 */
81 void sipe_backend_debug_literal(sipe_debug_level level,
82 const gchar *msg);
83
84 /**
85 * Output debug information
86 *
87 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
88 *
89 * @param level debug level
90 * @param format format string. "\n" will be automatically appended.
91 */
92 void sipe_backend_debug(sipe_debug_level level,
93 const gchar *format,
94 ...) G_GNUC_PRINTF(2, 3);
95
96 /* Convenience macros */
97 #define SIPE_LOG_INFO(fmt, ...) sipe_backend_debug(SIPE_LOG_LEVEL_INFO, fmt, __VA_ARGS__)
98 #define SIPE_LOG_INFO_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_LOG_LEVEL_INFO, msg)
99 #define SIPE_LOG_WARNING(fmt, ...) sipe_backend_debug(SIPE_LOG_LEVEL_WARNING, fmt, __VA_ARGS__)
100 #define SIPE_LOG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_LOG_LEVEL_WARNING, msg)
101 #define SIPE_LOG_ERROR(fmt, ...) sipe_backend_debug(SIPE_LOG_LEVEL_ERROR, fmt, __VA_ARGS__)
102 #define SIPE_LOG_ERROR_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_LOG_LEVEL_ERROR, msg)
103 #define SIPE_DEBUG_INFO(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO, fmt, __VA_ARGS__)
104 #define SIPE_DEBUG_INFO_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_INFO, msg)
105 #define SIPE_DEBUG_WARNING(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
106 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_WARNING, msg)
107 #define SIPE_DEBUG_ERROR(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR, fmt, __VA_ARGS__)
108 #define SIPE_DEBUG_ERROR_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_ERROR, msg)
109
110 /**
111 * Check backend debugging status
112 *
113 * @return TRUE if debugging is enabled
114 */
115 gboolean sipe_backend_debug_enabled(void);
116
117 /** CHAT *********************************************************************/
118
119 void sipe_backend_chat_session_destroy(struct sipe_backend_chat_session *session);
120 void sipe_backend_chat_add(struct sipe_backend_chat_session *backend_session,
121 const gchar *uri,
122 gboolean is_new);
123 void sipe_backend_chat_close(struct sipe_backend_chat_session *backend_session);
124
125 /**
126 * Joined a new chat
127 */
128 struct sipe_backend_chat_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
129 struct sipe_chat_session *session,
130 const gchar *title,
131 const gchar *nick);
132 gboolean sipe_backend_chat_find(struct sipe_backend_chat_session *backend_session,
133 const gchar *uri);
134 gboolean sipe_backend_chat_is_operator(struct sipe_backend_chat_session *backend_session,
135 const gchar *uri);
136 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
137 struct sipe_backend_chat_session *backend_session,
138 const gchar *from,
139 time_t when,
140 const gchar *html);
141 void sipe_backend_chat_operator(struct sipe_backend_chat_session *backend_session,
142 const gchar *uri);
143
144 /**
145 * Rejoin an existing chat window after connection re-establishment
146 */
147 void sipe_backend_chat_rejoin(struct sipe_core_public *sipe_public,
148 struct sipe_backend_chat_session *backend_session,
149 const gchar *nick,
150 const gchar *title);
151
152 /**
153 * Core has completed connection re-establishment.
154 * Should call sipe_core_chat_rejoin() for existing chats.
155 */
156 void sipe_backend_chat_rejoin_all(struct sipe_core_public *sipe_public);
157 void sipe_backend_chat_remove(struct sipe_backend_chat_session *backend_session,
158 const gchar *uri);
159
160 /**
161 * Move chat window to the front. Will be called when
162 * a user tries to join an already joined chat again.
163 */
164 void sipe_backend_chat_show(struct sipe_backend_chat_session *backend_session);
165 void sipe_backend_chat_topic(struct sipe_backend_chat_session *backend_session,
166 const gchar *topic);
167
168 /** CONNECTION ***************************************************************/
169
170 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
171
172 typedef enum {
173 SIPE_CONNECTION_ERROR_NETWORK = 0,
174 SIPE_CONNECTION_ERROR_INVALID_USERNAME,
175 SIPE_CONNECTION_ERROR_INVALID_SETTINGS,
176 SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED,
177 SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE,
178 SIPE_CONNECTION_ERROR_LAST
179 } sipe_connection_error;
180 void sipe_backend_connection_error(struct sipe_core_public *sipe_public,
181 sipe_connection_error error,
182 const gchar *msg);
183
184 gboolean sipe_backend_connection_is_disconnecting(struct sipe_core_public *sipe_public);
185 gboolean sipe_backend_connection_is_valid(struct sipe_core_public *sipe_public);
186
187 /** DNS QUERY ****************************************************************/
188
189 typedef void (*sipe_dns_resolved_cb)(gpointer data, const gchar *hostname, guint port);
190
191 struct sipe_dns_query *sipe_backend_dns_query_srv(struct sipe_core_public *sipe_public,
192 const gchar *protocol,
193 const gchar *transport,
194 const gchar *domain,
195 sipe_dns_resolved_cb callback,
196 gpointer data);
197
198 struct sipe_dns_query *sipe_backend_dns_query_a(struct sipe_core_public *sipe_public,
199 const gchar *hostname,
200 guint port,
201 sipe_dns_resolved_cb callback,
202 gpointer data);
203
204 void sipe_backend_dns_query_cancel(struct sipe_dns_query *query);
205
206 /** FILE TRANSFER ************************************************************/
207
208 struct sipe_backend_fd;
209
210 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
211 const gchar *errmsg);
212 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
213 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
214
215 /**
216 * Try to read up to @c size bytes from file transfer connection
217 *
218 * @param ft file transfer data.
219 * @param data buffer to read data into.
220 * @param size buffer size in bytes.
221 *
222 * @return number of bytes read or negative on failure.
223 * EAGAIN should return 0 bytes read.
224 */
225 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
226 guchar *data,
227 gsize size);
228
229 /**
230 * Try to write up to @c size bytes to file transfer connection
231 *
232 * @param ft file transfer data.
233 * @param data data to write
234 * @param size buffer size in bytes.
235 *
236 * @return number of bytes read or negative on failure.
237 * EAGAIN should return 0 bytes written.
238 */
239 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
240 const guchar *data,
241 gsize size);
242
243 void sipe_backend_ft_set_completed(struct sipe_file_transfer *ft);
244
245 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
246 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
247
248 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
249 struct sipe_file_transfer *ft,
250 const gchar *who,
251 const gchar *file_name,
252 gsize file_size);
253 /**
254 * Allocates and initializes backend file transfer structure for sending a file.
255 *
256 * @param sipe_public (in) the handle representing the protocol instance
257 * @param ft (in) sipe core file transfer structure
258 * @param who (in) SIP URI of the file recipient
259 * @param file_name (in) filesystem path of the file being sent
260 */
261 void sipe_backend_ft_outgoing(struct sipe_core_public *sipe_public,
262 struct sipe_file_transfer *ft,
263 const gchar *who,
264 const gchar *file_name);
265 /**
266 * Begins file transfer with remote peer.
267 *
268 * You can provide either opened file descriptor to use for read/write operations
269 * or ip address and port where the backend should connect.
270 *
271 * @param ft file transfer data
272 * @param fd opaque file descriptor pointer or NULL if ip and port are used
273 * @param ip ip address to connect of NULL when file descriptor is used
274 * @param port port to connect or 0 when file descriptor is used
275 */
276 void sipe_backend_ft_start(struct sipe_file_transfer *ft,
277 struct sipe_backend_fd *fd,
278 const char* ip, unsigned port);
279
280 /**
281 * Check whether file transfer is incoming or outgoing
282 *
283 * @param ft file transfer data
284 * @return @c TRUE if @c ft is incoming, otherwise @c FALSE
285 */
286 gboolean sipe_backend_ft_is_incoming(struct sipe_file_transfer *ft);
287
288 /** GROUP CHAT ***************************************************************/
289
290 #define SIPE_GROUPCHAT_ROOM_FILEPOST 0x00000001
291 #define SIPE_GROUPCHAT_ROOM_INVITE 0x00000002
292 #define SIPE_GROUPCHAT_ROOM_LOGGED 0x00000004
293 #define SIPE_GROUPCHAT_ROOM_PRIVATE 0x00000008
294
295 /**
296 * Add a room found through room query
297 *
298 * @param uri room URI
299 * @param name human readable name for room
300 * @param description room description
301 * @param users number of users in the room
302 * @param flags SIPE_GROUPCHAT_ROOM_* flags
303 */
304 void sipe_backend_groupchat_room_add(struct sipe_core_public *sipe_public,
305 const gchar *uri,
306 const gchar *name,
307 const gchar *description,
308 guint users,
309 guint32 flags);
310
311 /**
312 * Terminate room query
313 */
314 void sipe_backend_groupchat_room_terminate(struct sipe_core_public *sipe_public);
315
316 /** IM ***********************************************************************/
317
318 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
319 const gchar *from,
320 const gchar *html);
321 void sipe_backend_im_topic(struct sipe_core_public *sipe_public,
322 const gchar *with,
323 const gchar *topic);
324
325 /** MARKUP *******************************************************************/
326
327 gchar *sipe_backend_markup_css_property(const gchar *style,
328 const gchar *option);
329 gchar *sipe_backend_markup_strip_html(const gchar *html);
330
331 /** MEDIA ********************************************************************/
332
333 typedef enum {
334 /* This client is the one who invites other participant to the call. */
335 SIPE_MEDIA_CALL_INITIATOR = 1,
336 /* Don't show any user interface elements for the call. */
337 SIPE_MEDIA_CALL_NO_UI = 2
338 } SipeMediaCallFlags;
339
340 typedef enum {
341 SIPE_ICE_NO_ICE,
342 SIPE_ICE_DRAFT_6,
343 SIPE_ICE_RFC_5245
344 } SipeIceVersion;
345
346 typedef enum {
347 SIPE_CANDIDATE_TYPE_ANY,
348 SIPE_CANDIDATE_TYPE_HOST,
349 SIPE_CANDIDATE_TYPE_RELAY,
350 SIPE_CANDIDATE_TYPE_SRFLX,
351 SIPE_CANDIDATE_TYPE_PRFLX
352 } SipeCandidateType;
353
354 typedef enum {
355 SIPE_COMPONENT_NONE = 0,
356 SIPE_COMPONENT_RTP = 1,
357 SIPE_COMPONENT_RTCP = 2
358 } SipeComponentType;
359
360 typedef enum {
361 SIPE_MEDIA_AUDIO,
362 SIPE_MEDIA_VIDEO,
363 SIPE_MEDIA_APPLICATION
364 } SipeMediaType;
365
366 typedef enum {
367 SIPE_NETWORK_PROTOCOL_UDP,
368 SIPE_NETWORK_PROTOCOL_TCP_ACTIVE,
369 SIPE_NETWORK_PROTOCOL_TCP_PASSIVE,
370 SIPE_NETWORK_PROTOCOL_TCP_SO,
371 } SipeNetworkProtocol;
372
373 typedef enum {
374 SIPE_ENCRYPTION_POLICY_REJECTED,
375 SIPE_ENCRYPTION_POLICY_OPTIONAL,
376 SIPE_ENCRYPTION_POLICY_REQUIRED,
377 SIPE_ENCRYPTION_POLICY_OBEY_SERVER
378 } SipeEncryptionPolicy;
379
380 struct sipe_media_call;
381 struct sipe_backend_media;
382 struct sipe_backend_codec;
383 struct sipe_backend_candidate;
384 struct sipe_backend_media_stream;
385 struct sipe_backend_media_relays;
386
387 struct ssrc_range {
388 guint32 begin;
389 guint32 end;
390 };
391
392 struct sipe_media_stream {
393 struct sipe_backend_media_stream *backend_private;
394
395 struct sipe_media_call *call;
396 gchar *id;
397 struct ssrc_range *ssrc_range;
398
399 void (*candidate_pairs_established_cb)(struct sipe_media_stream *);
400 void (*read_cb)(struct sipe_media_stream *);
401 void (*writable_cb)(struct sipe_media_stream *);
402 void (*mute_cb)(struct sipe_media_stream *, gboolean is_muted);
403 };
404
405 struct sipe_media_call {
406 struct sipe_backend_media *backend_private;
407
408 gchar *with;
409
410 void (*stream_initialized_cb)(struct sipe_media_call *,
411 struct sipe_media_stream *);
412 void (*media_end_cb)(struct sipe_media_call *);
413 void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
414 void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
415 void (*call_hold_cb) (struct sipe_media_call *, gboolean local,
416 gboolean state);
417 void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
418 void (*error_cb)(struct sipe_media_call *, gchar *message);
419 };
420
421 struct sipe_media_relay {
422 gchar *hostname;
423 guint udp_port;
424 guint tcp_port;
425 struct sipe_dns_query *dns_query;
426 };
427
428 /* Media handling */
429 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
430 struct sipe_media_call *call,
431 const gchar *participant,
432 SipeMediaCallFlags flags);
433 void sipe_backend_media_free(struct sipe_backend_media *media);
434
435 void sipe_backend_media_set_cname(struct sipe_backend_media *media, gchar *cname);
436
437 struct sipe_backend_media_relays * sipe_backend_media_relays_convert(GSList *media_relays,
438 gchar *username,
439 gchar *password);
440 void sipe_backend_media_relays_free(struct sipe_backend_media_relays *media_relays);
441
442 struct sipe_backend_media_stream *sipe_backend_media_add_stream(struct sipe_media_stream *stream,
443 SipeMediaType type,
444 SipeIceVersion ice_version,
445 gboolean initiator,
446 struct sipe_backend_media_relays *media_relays,
447 guint min_port, guint max_port);
448 void sipe_backend_media_add_remote_candidates(struct sipe_media_call *media,
449 struct sipe_media_stream *stream,
450 GList *candidates);
451 gboolean sipe_backend_media_is_initiator(struct sipe_media_call *media,
452 struct sipe_media_stream *stream);
453 gboolean sipe_backend_media_accepted(struct sipe_backend_media *media);
454 gboolean sipe_backend_stream_initialized(struct sipe_media_call *media,
455 struct sipe_media_stream *stream);
456 void sipe_backend_media_set_encryption_keys(struct sipe_media_call *media,
457 struct sipe_media_stream *stream,
458 const guchar *encryption_key,
459 const guchar *decryption_key);
460 void sipe_backend_media_set_require_encryption(struct sipe_media_call *media,
461 struct sipe_media_stream *stream,
462 const gboolean require_encryption);
463
464 /* Stream handling */
465 void sipe_backend_stream_hold(struct sipe_media_call *media,
466 struct sipe_media_stream *stream,
467 gboolean local);
468 void sipe_backend_stream_unhold(struct sipe_media_call *media,
469 struct sipe_media_stream *stream,
470 gboolean local);
471 gboolean sipe_backend_stream_is_held(struct sipe_media_stream *stream);
472
473 GList *sipe_backend_media_stream_get_active_local_candidates(struct sipe_media_stream *stream);
474 GList *sipe_backend_media_stream_get_active_remote_candidates(struct sipe_media_stream *stream);
475
476 gssize sipe_backend_media_stream_read(struct sipe_media_stream *stream,
477 guint8 *buffer, gsize len);
478 gssize sipe_backend_media_stream_write(struct sipe_media_stream *stream,
479 guint8 *buffer, gsize len);
480
481 void sipe_backend_media_stream_end(struct sipe_media_call *media,
482 struct sipe_media_stream *stream);
483 void sipe_backend_media_stream_free(struct sipe_backend_media_stream *stream);
484
485 /* Codec handling */
486 struct sipe_backend_codec *sipe_backend_codec_new(int id,
487 const char *name,
488 SipeMediaType type,
489 guint clock_rate,
490 guint channels);
491 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
492 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
493 /**
494 * @return codec name. Will be g_free'd() by the core.
495 */
496 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
497 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
498 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
499 const gchar *name,
500 const gchar *value);
501 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
502 gboolean sipe_backend_set_remote_codecs(struct sipe_media_call *media,
503 struct sipe_media_stream *stream,
504 GList *codecs);
505 GList* sipe_backend_get_local_codecs(struct sipe_media_call *media,
506 struct sipe_media_stream *stream);
507
508 /* Candidate handling */
509 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
510 SipeComponentType component,
511 SipeCandidateType type,
512 SipeNetworkProtocol proto,
513 const gchar *ip, guint port,
514 const gchar *username,
515 const gchar *password);
516 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
517 /**
518 * @return user name. Will be g_free'd() by the core.
519 */
520 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
521 /**
522 * @return password. Will be g_free'd() by the core.
523 */
524 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
525 /**
526 * @return foundation. Will be g_free'd() by the core.
527 */
528 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
529 /**
530 * @return IP address string. Will be g_free'd() by the core.
531 */
532 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
533 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
534 /**
535 * @return IP address string. Will be g_free'd() by the core.
536 */
537 gchar *sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate *candidate);
538 guint sipe_backend_candidate_get_base_port(struct sipe_backend_candidate *candidate);
539 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
540 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
541 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
542 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
543 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
544 GList* sipe_backend_get_local_candidates(struct sipe_media_call *media,
545 struct sipe_media_stream *stream);
546 void sipe_backend_media_accept(struct sipe_backend_media *media, gboolean local);
547 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
548 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
549
550 /** NETWORK ******************************************************************/
551
552 struct sipe_backend_listendata;
553
554 typedef void (*sipe_listen_start_cb)(unsigned short port, gpointer data);
555 typedef void (*sipe_client_connected_cb)(struct sipe_backend_fd *fd, gpointer data);
556
557 struct sipe_backend_listendata *
558 sipe_backend_network_listen_range(unsigned short port_min,
559 unsigned short port_max,
560 sipe_listen_start_cb listen_cb,
561 sipe_client_connected_cb connect_cb,
562 gpointer data);
563 void sipe_backend_network_listen_cancel(struct sipe_backend_listendata *ldata);
564
565 struct sipe_backend_fd * sipe_backend_fd_from_int(int fd);
566 gboolean sipe_backend_fd_is_valid(struct sipe_backend_fd *fd);
567 void sipe_backend_fd_free(struct sipe_backend_fd *fd);
568
569 /** NOTIFICATIONS *************************************************************/
570
571 void sipe_backend_notify_message_error(struct sipe_core_public *sipe_public,
572 struct sipe_backend_chat_session *backend_session,
573 const gchar *who,
574 const gchar *message);
575 void sipe_backend_notify_message_info(struct sipe_core_public *sipe_public,
576 struct sipe_backend_chat_session *backend_session,
577 const gchar *who,
578 const gchar *message);
579
580 /**
581 * @param msg error message. Maybe @NULL
582 */
583 void sipe_backend_notify_error(struct sipe_core_public *sipe_public,
584 const gchar *title,
585 const gchar *msg);
586
587 /** SCHEDULE *****************************************************************/
588
589 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
590 guint timeout,
591 gpointer data);
592 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
593 guint timeout,
594 gpointer data);
595 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
596 gpointer data);
597
598 /** SEARCH *******************************************************************/
599
600 struct sipe_backend_search_results;
601 struct sipe_backend_search_token;
602
603 void sipe_backend_search_failed(struct sipe_core_public *sipe_public,
604 struct sipe_backend_search_token *token,
605 const gchar *msg);
606 struct sipe_backend_search_results *sipe_backend_search_results_start(struct sipe_core_public *sipe_public,
607 struct sipe_backend_search_token *token);
608 void sipe_backend_search_results_add(struct sipe_core_public *sipe_public,
609 struct sipe_backend_search_results *results,
610 const gchar *uri,
611 const gchar *name,
612 const gchar *company,
613 const gchar *country,
614 const gchar *email);
615 void sipe_backend_search_results_finalize(struct sipe_core_public *sipe_public,
616 struct sipe_backend_search_results *results,
617 const gchar *description,
618 gboolean more);
619
620 /** SETTINGS *****************************************************************/
621
622 typedef enum {
623 SIPE_SETTING_EMAIL_URL = 0,
624 SIPE_SETTING_EMAIL_LOGIN,
625 SIPE_SETTING_EMAIL_PASSWORD,
626 SIPE_SETTING_GROUPCHAT_USER,
627 SIPE_SETTING_RDP_CLIENT,
628 SIPE_SETTING_USER_AGENT,
629 SIPE_SETTING_LAST
630 } sipe_setting;
631 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
632 sipe_setting type);
633
634 /** STATUS *******************************************************************/
635
636 guint sipe_backend_status(struct sipe_core_public *sipe_public);
637 gboolean sipe_backend_status_changed(struct sipe_core_public *sipe_public,
638 guint activity,
639 const gchar *message);
640
641 /**
642 * Update user client with new status and note received from server
643 *
644 * NOTE: this must *NOT* trigger a call to @c sipe_core_status_set()!
645 *
646 * @param sipe_public The handle representing the protocol instance
647 * @param activity New activity
648 * @param message New note text
649 */
650 void sipe_backend_status_and_note(struct sipe_core_public *sipe_public,
651 guint activity,
652 const gchar *message);
653
654 /** TRANSPORT ****************************************************************/
655
656 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
657 typedef void transport_input_cb(struct sipe_transport_connection *conn);
658 typedef void transport_error_cb(struct sipe_transport_connection *conn,
659 const gchar *msg);
660
661 typedef struct {
662 guint type;
663 const gchar *server_name;
664 guint server_port;
665 gpointer user_data;
666 transport_connected_cb *connected;
667 transport_input_cb *input;
668 transport_error_cb *error;
669 } sipe_connect_setup;
670 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
671 const sipe_connect_setup *setup);
672 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
673 gchar *sipe_backend_transport_ip_address(struct sipe_transport_connection *conn);
674 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
675 const gchar *buffer);
676 void sipe_backend_transport_flush(struct sipe_transport_connection *conn);
677
678 /** USER *********************************************************************/
679
680 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
681 const gchar *from);
682 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
683 const gchar *from);
684
685 /**
686 * Present a query that is to be accepted or declined by the user
687 *
688 * @param sipe_public The handle representing the protocol instance
689 * @param message Text of the query to be shown to user
690 * @param accept_label Label to be displayed on UI control that accepts query
691 * @param decline_label Label to be displayed on UI control that declines query.
692 * When @c NULL, the control will not be shown.
693 * @param key Opaque handle uniquely identifying the query. Backend
694 * should store it for the case SIPE core requests the
695 * query to be closed prematurely.
696 */
697 void sipe_backend_user_ask(struct sipe_core_public *sipe_public,
698 const gchar *message,
699 const gchar *accept_label,
700 const gchar *decline_label,
701 gpointer key);
702
703 /**
704 * Present a set of options to the user to choose from.
705 *
706 * @param sipe_public (in) The handle representing the protocol instance
707 * @param message (in) Text message to be shown to the user
708 * @param choices (in) List of choice options
709 * @param key (in) Opaque handle uniquely identifying the query. Backend
710 * should store it for the case SIPE core requests the query
711 * to be closed prematurely.
712 */
713 void sipe_backend_user_ask_choice(struct sipe_core_public *sipe_public,
714 const gchar *message,
715 GSList *choices,
716 gpointer key);
717
718 /**
719 * Closes the pending user query
720 *
721 * @param key Opaque handle uniquely identifying the query.
722 */
723 void sipe_backend_user_close_ask(gpointer key);
724
725 /** BUDDIES ******************************************************************/
726
727 /*
728 * sipe_backend_buddy_get/set_string(): properties a buddy can have
729 * sipe_backend_buddy_info_add(): mapped, e.g. to a string label
730 */
731 typedef enum
732 {
733 SIPE_BUDDY_INFO_DISPLAY_NAME = 0,
734 SIPE_BUDDY_INFO_JOB_TITLE,
735 SIPE_BUDDY_INFO_CITY,
736 SIPE_BUDDY_INFO_STATE,
737 SIPE_BUDDY_INFO_OFFICE,
738 SIPE_BUDDY_INFO_DEPARTMENT,
739 SIPE_BUDDY_INFO_COUNTRY,
740 SIPE_BUDDY_INFO_WORK_PHONE,
741 SIPE_BUDDY_INFO_WORK_PHONE_DISPLAY,
742 SIPE_BUDDY_INFO_COMPANY,
743 SIPE_BUDDY_INFO_EMAIL,
744 SIPE_BUDDY_INFO_SITE,
745 SIPE_BUDDY_INFO_ZIPCODE,
746 SIPE_BUDDY_INFO_STREET,
747 SIPE_BUDDY_INFO_MOBILE_PHONE,
748 SIPE_BUDDY_INFO_MOBILE_PHONE_DISPLAY,
749 SIPE_BUDDY_INFO_HOME_PHONE,
750 SIPE_BUDDY_INFO_HOME_PHONE_DISPLAY,
751 SIPE_BUDDY_INFO_OTHER_PHONE,
752 SIPE_BUDDY_INFO_OTHER_PHONE_DISPLAY,
753 SIPE_BUDDY_INFO_CUSTOM1_PHONE,
754 SIPE_BUDDY_INFO_CUSTOM1_PHONE_DISPLAY,
755 SIPE_BUDDY_INFO_ALIAS, /* only for sipe_backend_buddy_info_add() */
756 SIPE_BUDDY_INFO_DEVICE, /* only for sipe_backend_buddy_info_add() */
757 } sipe_buddy_info_fields;
758
759 /* Opaque token */
760 typedef void* sipe_backend_buddy;
761
762 /**
763 * Find a buddy in the given group of the buddy list, or anywhere on the
764 * list if @group_name is empty
765 *
766 * @param sipe_public The handle representing the protocol instance making the call
767 * @param buddy_name The name of the buddy
768 * @param group_name The name of the group to look in, or NULL for any group
769 * @return opaque handle to the buddy, or NULL if no buddy found
770 */
771 sipe_backend_buddy sipe_backend_buddy_find(struct sipe_core_public *sipe_public,
772 const gchar *buddy_name,
773 const gchar *group_name);
774
775 /*
776 * Find all named buddies in the given group of the buddy list, or anywhere on the
777 * list if @group_name is empty; or all buddies if @name is empty
778 *
779 * @param sipe_public The handle representing the protocol instance making the call
780 * @param name The name of the buddy
781 * @param group_name The name of the group to look in, or NULL for any group
782 * @return GSList of opaque handles to the buddies
783 */
784 GSList* sipe_backend_buddy_find_all(struct sipe_core_public *sipe_public,
785 const gchar *buddy_name,
786 const gchar *group_name);
787
788 /**
789 * Gets the name of a contact.
790 *
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 * @return The name. Must be freed.
794 */
795 gchar* sipe_backend_buddy_get_name(struct sipe_core_public *sipe_public,
796 const sipe_backend_buddy who);
797
798 /**
799 * Gets the alias for a contact.
800 *
801 * @param sipe_public The handle representing the protocol instance making the call
802 * @param who The opaque handle to the contact as found by find_buddy
803 * @return The alias. Must be gfree'd.
804 */
805 gchar* sipe_backend_buddy_get_alias(struct sipe_core_public *sipe_public,
806 const sipe_backend_buddy who);
807
808 /**
809 * Gets the server alias for a contact.
810 *
811 * @param sipe_public The handle representing the protocol instance making the call
812 * @param who The opaque handle to the contact as found by find_buddy
813 * @return The alias. Must be freed.
814 */
815 gchar* sipe_backend_buddy_get_server_alias(struct sipe_core_public *sipe_public,
816 const sipe_backend_buddy who);
817
818 /**
819 * Gets the local alias for a contact
820 *
821 * @param sipe_public The handle representing the protocol instance making the call
822 * @param uri the budyy name
823 *
824 * @return the alias. Must be @g_free()'d.
825 */
826 gchar *sipe_backend_buddy_get_local_alias(struct sipe_core_public *sipe_public,
827 const sipe_backend_buddy who);
828
829 /**
830 * Gets the name of the group a contact belongs to.
831 *
832 * @param sipe_public The handle representing the protocol instance making the call
833 * @param who The opaque handle to the contact as found by find_buddy
834 * @return The name. Must be freed.
835 */
836 gchar* sipe_backend_buddy_get_group_name(struct sipe_core_public *sipe_public,
837 const sipe_backend_buddy who);
838
839 /**
840 * Called to retrieve a buddy-specific setting.
841 *
842 * @param sipe_public The handle representing the protocol instance making the call
843 * @param buddy The handle representing the buddy
844 * @param key The name of the setting
845 * @return The value of the setting. Must be freed.
846 */
847 gchar* sipe_backend_buddy_get_string(struct sipe_core_public *sipe_public,
848 sipe_backend_buddy buddy,
849 const sipe_buddy_info_fields key);
850
851 /**
852 * Called to set a buddy-specific setting.
853 *
854 * @param sipe_public The handle representing the protocol instance making the call
855 * @param buddy The handle representing the buddy
856 * @param key The name of the setting
857 * @param val The value to set
858 */
859 void sipe_backend_buddy_set_string(struct sipe_core_public *sipe_public,
860 sipe_backend_buddy buddy,
861 const sipe_buddy_info_fields key,
862 const gchar *val);
863
864 /**
865 * Called after one ore more buddy-specific settings have been updated.
866 *
867 * Can be used by the backend to trigger an UI update event
868 *
869 * @param sipe_public The handle representing the protocol instance making the call
870 * @param uri SIP URI of the contact
871 */
872 void sipe_backend_buddy_refresh_properties(struct sipe_core_public *sipe_public,
873 const gchar *uri);
874
875 /**
876 * Get the status token for a contact
877 *
878 * @param sipe_public The handle representing the protocol instance making the call
879 * @param uri SIP URI of the contact
880 *
881 * @return activity
882 */
883 guint sipe_backend_buddy_get_status(struct sipe_core_public *sipe_public,
884 const gchar *uri);
885
886 /**
887 * Sets the alias for a contact.
888 *
889 * @param sipe_public The handle representing the protocol instance making the call
890 * @param who The opaque handle to the contact as found by find_buddy
891 * @param alias The location where the alias will be put
892 * case. FALSE if the buddy was not found. The value of alias will not be changed.
893 */
894 void sipe_backend_buddy_set_alias(struct sipe_core_public *sipe_public,
895 const sipe_backend_buddy who,
896 const gchar *alias);
897
898 /**
899 * Sets the server alias for a contact.
900 *
901 * @param sipe_public The handle representing the protocol instance making the call
902 * @param who The opaque handle to the contact as found by find_buddy
903 * @param alias The server alias of the contact
904 */
905 void sipe_backend_buddy_set_server_alias(struct sipe_core_public *sipe_public,
906 const sipe_backend_buddy who,
907 const gchar *alias);
908
909 /**
910 * Start processing buddy list
911 *
912 * Will be called every time we receive a buddy list in roaming contacts
913 *
914 * @param sipe_public The handle representing the protocol instance making the call
915 */
916 void sipe_backend_buddy_list_processing_start(struct sipe_core_public *sipe_public);
917
918 /**
919 * Finished processing buddy list
920 *
921 * Will be called every time we receive a buddy list in roaming contacts
922 *
923 * @param sipe_public The handle representing the protocol instance making the call
924 */
925 void sipe_backend_buddy_list_processing_finish(struct sipe_core_public *sipe_public);
926
927 /**
928 * Add a contact to the buddy list
929 *
930 * @param sipe_public The handle representing the protocol instance making the call
931 * @param name The name of the contact
932 * @param alias The alias of the contact
933 * @param groupname The name of the group to add this contact to
934 * @return A handle to the newly created buddy
935 */
936 sipe_backend_buddy sipe_backend_buddy_add(struct sipe_core_public *sipe_public,
937 const gchar *name,
938 const gchar *alias,
939 const gchar *groupname);
940
941 /**
942 * Remove a contact from the buddy list
943 *
944 * @param sipe_public The handle representing the protocol instance making the call
945 * @param who The opaque handle to the contact as found by find_buddy
946 */
947 void sipe_backend_buddy_remove(struct sipe_core_public *sipe_public,
948 const sipe_backend_buddy who);
949
950 /**
951 * Notifies the user that a remote user has wants to add the local user to his
952 * or her buddy list and requires authorization to do so.
953 *
954 * @param sipe_public The handle representing the protocol instance making the call
955 * @param who The name of the user that added this account
956 * @param alias The optional alias of the remote user
957 * @param on_list True if the user is already in our list
958 * @param auth_cb The callback called when the local user accepts
959 * @param deny_cb The callback called when the local user rejects
960 * @param data Data to be passed back to the above callbacks
961 */
962 typedef void (*sipe_backend_buddy_request_authorization_cb)(void *);
963
964 void sipe_backend_buddy_request_add(struct sipe_core_public *sipe_public,
965 const gchar *who,
966 const gchar *alias);
967
968 void sipe_backend_buddy_request_authorization(struct sipe_core_public *sipe_public,
969 const gchar *who,
970 const gchar *alias,
971 gboolean on_list,
972 sipe_backend_buddy_request_authorization_cb auth_cb,
973 sipe_backend_buddy_request_authorization_cb deny_cb,
974 gpointer data);
975
976 gboolean sipe_backend_buddy_is_blocked(struct sipe_core_public *sipe_public,
977 const gchar *who);
978
979 void sipe_backend_buddy_set_blocked_status(struct sipe_core_public *sipe_public,
980 const gchar *who,
981 gboolean blocked);
982
983 /**
984 * Set the buddy status
985 *
986 * @param sipe_public The handle representing the protocol instance making the call
987 * @param who The name of the user whose status should be updated
988 * @param activity New activity
989 * @param last_active Seconds since epoch when user entered idle state.
990 * May be @c 0 if unknown.
991 */
992 void sipe_backend_buddy_set_status(struct sipe_core_public *sipe_public,
993 const gchar *who,
994 guint activity,
995 time_t last_active);
996
997 /**
998 * Checks whether backend has a capability to use buddy photos. If this function
999 * returns @c FALSE, SIPE core will not attempt to download the photos from
1000 * server to save bandwidth.
1001 *
1002 * @return @c TRUE if backend is photo capable, otherwise @FALSE
1003 */
1004 gboolean sipe_backend_uses_photo(void);
1005
1006 /**
1007 * Gives backend a photo image associated with a SIP URI. Backend has ownership
1008 * of the data and must free it when not needed.
1009 *
1010 * @param sipe_public The handle representing the protocol instance making the call
1011 * @param who The name of the user whose photo is being set
1012 * @param image_data The photo image data, must be g_free()'d by backend
1013 * @param image_len Size of the image in Bytes
1014 * @param photo_hash A data checksum provided by the server
1015 */
1016 void sipe_backend_buddy_set_photo(struct sipe_core_public *sipe_public,
1017 const gchar *who,
1018 gpointer image_data,
1019 gsize image_len,
1020 const gchar *photo_hash);
1021
1022 /**
1023 * Retrieves a photo hash stored together with image data by
1024 * @c sipe_backend_buddy_set_photo. Value is used by the core to detect photo
1025 * file changes on server.
1026 *
1027 * @param sipe_public The handle representing the protocol instance making the call
1028 * @param who The name of the user whose photo hash to retrieve
1029 * @return a photo hash (may be NULL)
1030 */
1031 const gchar *sipe_backend_buddy_get_photo_hash(struct sipe_core_public *sipe_public,
1032 const gchar *who);
1033
1034 /**
1035 * Called when a new internal group is about to be added. If this returns FALSE,
1036 * the group will not be added.
1037 *
1038 * @param sipe_public The handle representing the protocol instance making the call
1039 * @param group_name The group being added
1040 * @return TRUE if everything is ok, FALSE if the group should not be added
1041 */
1042 gboolean sipe_backend_buddy_group_add(struct sipe_core_public *sipe_public,
1043 const gchar *group_name);
1044
1045 /**
1046 * Called when a new internal group has been renamed
1047 *
1048 * @param sipe_public The handle representing the protocol instance making the call
1049 * @param old_name old name of the group
1050 * @param new_name new name of the group
1051 * @return TRUE if the group was found and renamed
1052 */
1053 gboolean sipe_backend_buddy_group_rename(struct sipe_core_public *sipe_public,
1054 const gchar *old_name,
1055 const gchar *new_name);
1056
1057 /**
1058 * Called when a new internal group should be deleted
1059 *
1060 * NOTE: this will only be called on empty groups.
1061 *
1062 * @param sipe_public The handle representing the protocol instance making the call
1063 * @param group_name The group that should be removed
1064 */
1065 void sipe_backend_buddy_group_remove(struct sipe_core_public *sipe_public,
1066 const gchar *group_name);
1067
1068 /**
1069 * Present requested buddy information to the user
1070 */
1071 struct sipe_backend_buddy_info;
1072 struct sipe_backend_buddy_info *sipe_backend_buddy_info_start(struct sipe_core_public *sipe_public);
1073 void sipe_backend_buddy_info_add(struct sipe_core_public *sipe_public,
1074 struct sipe_backend_buddy_info *info,
1075 sipe_buddy_info_fields key,
1076 const gchar *value);
1077 void sipe_backend_buddy_info_break(struct sipe_core_public *sipe_public,
1078 struct sipe_backend_buddy_info *info);
1079 void sipe_backend_buddy_info_finalize(struct sipe_core_public *sipe_public,
1080 struct sipe_backend_buddy_info *info,
1081 const gchar *uri);
1082
1083 struct sipe_backend_buddy_tooltip;
1084 void sipe_backend_buddy_tooltip_add(struct sipe_core_public *sipe_public,
1085 struct sipe_backend_buddy_tooltip *tooltip,
1086 const gchar *description,
1087 const gchar *value);
1088
1089 /**
1090 * Buddy menu creation
1091 */
1092 enum sipe_buddy_menu_type {
1093 SIPE_BUDDY_MENU_MAKE_CHAT_LEADER = 0,
1094 SIPE_BUDDY_MENU_REMOVE_FROM_CHAT,
1095 SIPE_BUDDY_MENU_INVITE_TO_CHAT,
1096 SIPE_BUDDY_MENU_NEW_CHAT,
1097 SIPE_BUDDY_MENU_MAKE_CALL,
1098 SIPE_BUDDY_MENU_SEND_EMAIL,
1099 SIPE_BUDDY_MENU_ACCESS_LEVEL_HELP,
1100 SIPE_BUDDY_MENU_CHANGE_ACCESS_LEVEL,
1101 SIPE_BUDDY_MENU_ADD_NEW_DOMAIN,
1102 SIPE_BUDDY_MENU_SHARE_DESKTOP,
1103 SIPE_BUDDY_MENU_GIVE_DESKTOP_CONTROL,
1104 SIPE_BUDDY_MENU_TAKE_DESKTOP_CONTROL,
1105 SIPE_BUDDY_MENU_TYPES
1106 };
1107
1108 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_start(struct sipe_core_public *sipe_public);
1109 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_add(struct sipe_core_public *sipe_public,
1110 struct sipe_backend_buddy_menu *menu,
1111 const gchar *label,
1112 enum sipe_buddy_menu_type type,
1113 gpointer parameter);
1114 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_separator(struct sipe_core_public *sipe_public,
1115 struct sipe_backend_buddy_menu *menu,
1116 const gchar *label);
1117 struct sipe_backend_buddy_menu *sipe_backend_buddy_sub_menu_add(struct sipe_core_public *sipe_public,
1118 struct sipe_backend_buddy_menu *menu,
1119 const gchar *label,
1120 struct sipe_backend_buddy_menu *sub);
1121
1122 SipeEncryptionPolicy sipe_backend_media_get_encryption_policy(struct sipe_core_public *sipe_public);
1123
1124 #ifdef __cplusplus
1125 }
1126 #endif
1127
1128 /*
1129 Local Variables:
1130 mode: c
1131 c-file-style: "bsd"
1132 indent-tabs-mode: t
1133 tab-width: 8
1134 End:
1135 */
A third-party Pidgin plugin for Microsoft LCS/OCS