?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
core cleanup: add last level of access levels menu
[siplcs.git] / src / api / sipe-backend.h
blob016bb99ddbe307ffefd6b71802bab3d17f8af2ad
1 /**
2 * @file sipe-backend.h
3 *
4 * pidgin-sipe
5 *
6 * Copyright (C) 2010-11 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_DEBUG_LEVEL_INFO,
65 SIPE_DEBUG_LEVEL_WARNING,
66 SIPE_DEBUG_LEVEL_ERROR,
67 SIPE_DEBUG_LEVEL_FATAL,
68 } sipe_debug_level;
69
70 /**
71 * Output debug information without formatting
72 *
73 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
74 *
75 * @param level debug level
76 * @param msg debug message "\n" will be automatically appended.
77 */
78 void sipe_backend_debug_literal(sipe_debug_level level,
79 const gchar *msg);
80
81 /**
82 * Output debug information
83 *
84 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
85 *
86 * @param level debug level
87 * @param format format string. "\n" will be automatically appended.
88 */
89 void sipe_backend_debug(sipe_debug_level level,
90 const gchar *format,
91 ...) G_GNUC_PRINTF(2, 3);
92
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)
102
103 /**
104 * Check backend debugging status
105 *
106 * @return TRUE if debugging is enabled
107 */
108 gboolean sipe_backend_debug_enabled(void);
109
110 /** CHAT *********************************************************************/
111
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,
114 const gchar *uri,
115 gboolean is_new);
116 void sipe_backend_chat_close(struct sipe_backend_chat_session *backend_session);
117
118 /**
119 * Joined a new chat
120 */
121 struct sipe_backend_chat_session *sipe_backend_chat_create(struct sipe_core_public *sipe_public,
122 struct sipe_chat_session *session,
123 const gchar *title,
124 const gchar *nick);
125 gboolean sipe_backend_chat_find(struct sipe_backend_chat_session *backend_session,
126 const gchar *uri);
127 gboolean sipe_backend_chat_is_operator(struct sipe_backend_chat_session *backend_session,
128 const gchar *uri);
129 void sipe_backend_chat_message(struct sipe_core_public *sipe_public,
130 struct sipe_backend_chat_session *backend_session,
131 const gchar *from,
132 const gchar *html);
133 void sipe_backend_chat_operator(struct sipe_backend_chat_session *backend_session,
134 const gchar *uri);
135
136 /**
137 * Rejoin an existing chat window after connection re-establishment
138 */
139 void sipe_backend_chat_rejoin(struct sipe_core_public *sipe_public,
140 struct sipe_backend_chat_session *backend_session,
141 const gchar *nick,
142 const gchar *title);
143
144 /**
145 * Core has completed connection re-establishment.
146 * Should call sipe_core_chat_rejoin() for existing chats.
147 */
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,
150 const gchar *uri);
151
152 /**
153 * Move chat window to the front. Will be called when
154 * a user tries to join an already joined chat again.
155 */
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,
158 const gchar *topic);
159
160 /** CONNECTION ***************************************************************/
161
162 void sipe_backend_connection_completed(struct sipe_core_public *sipe_public);
163
164 typedef enum {
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,
174 const gchar *msg);
175
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);
178
179 /** DNS QUERY ****************************************************************/
180
181 typedef void (*sipe_dns_resolved_cb)(gpointer data, const gchar *hostname, guint port);
182
183 struct sipe_dns_query *sipe_backend_dns_query_srv(const gchar *protocol,
184 const gchar *transport,
185 const gchar *domain,
186 sipe_dns_resolved_cb callback,
187 gpointer data);
188
189 struct sipe_dns_query *sipe_backend_dns_query_a(const gchar *hostname,
190 int port,
191 sipe_dns_resolved_cb callback,
192 gpointer data);
193
194 void sipe_backend_dns_query_cancel(struct sipe_dns_query *query);
195
196 /** FILE TRANSFER ************************************************************/
197
198 struct sipe_backend_fd;
199
200 void sipe_backend_ft_error(struct sipe_file_transfer *ft,
201 const gchar *errmsg);
202 const gchar *sipe_backend_ft_get_error(struct sipe_file_transfer *ft);
203 void sipe_backend_ft_deallocate(struct sipe_file_transfer *ft);
204
205 /**
206 * Try to read up to @c size bytes from file transfer connection
207 *
208 * @param ft file transfer data.
209 * @param data buffer to read data into.
210 * @param size buffer size in bytes.
211 *
212 * @return number of bytes read or negative on failure.
213 * EAGAIN should return 0 bytes read.
214 */
215 gssize sipe_backend_ft_read(struct sipe_file_transfer *ft,
216 guchar *data,
217 gsize size);
218
219 /**
220 * Try to write up to @c size bytes to file transfer connection
221 *
222 * @param ft file transfer data.
223 * @param data data to write
224 * @param size buffer size in bytes.
225 *
226 * @return number of bytes read or negative on failure.
227 * EAGAIN should return 0 bytes written.
228 */
229 gssize sipe_backend_ft_write(struct sipe_file_transfer *ft,
230 const guchar *data,
231 gsize size);
232
233
234 void sipe_backend_ft_cancel_local(struct sipe_file_transfer *ft);
235 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer *ft);
236
237 void sipe_backend_ft_incoming(struct sipe_core_public *sipe_public,
238 struct sipe_file_transfer *ft,
239 const gchar *who,
240 const gchar *file_name,
241 gsize file_size);
242 /**
243 * Begins file transfer with remote peer.
244 *
245 * You can provide either opened file descriptor to use for read/write operations
246 * or ip address and port where the backend should connect.
247 *
248 * @param ft file transfer data
249 * @param fd opaque file descriptor pointer or NULL if ip and port are used
250 * @param ip ip address to connect of NULL when file descriptor is used
251 * @param port port to connect or 0 when file descriptor is used
252 */
253 void sipe_backend_ft_start(struct sipe_file_transfer *ft,
254 struct sipe_backend_fd *fd,
255 const char* ip, unsigned port);
256
257 /**
258 * Check whether file transfer is incoming or outgoing
259 *
260 * @param ft file transfer data
261 * @return @c TRUE if @c ft is incoming, otherwise @c FALSE
262 */
263 gboolean sipe_backend_ft_is_incoming(struct sipe_file_transfer *ft);
264
265 /** GROUP CHAT ***************************************************************/
266
267 #define SIPE_GROUPCHAT_ROOM_FILEPOST 0x00000001
268 #define SIPE_GROUPCHAT_ROOM_INVITE 0x00000002
269 #define SIPE_GROUPCHAT_ROOM_LOGGED 0x00000004
270 #define SIPE_GROUPCHAT_ROOM_PRIVATE 0x00000008
271
272 /**
273 * Add a room found through room query
274 *
275 * @param uri room URI
276 * @param name human readable name for room
277 * @param description room description
278 * @param users number of users in the room
279 * @param flags SIPE_GROUPCHAT_ROOM_* flags
280 */
281 void sipe_backend_groupchat_room_add(struct sipe_core_public *sipe_public,
282 const gchar *uri,
283 const gchar *name,
284 const gchar *description,
285 guint users,
286 guint32 flags);
287
288 /**
289 * Terminate room query
290 */
291 void sipe_backend_groupchat_room_terminate(struct sipe_core_public *sipe_public);
292
293 /** IM ***********************************************************************/
294
295 void sipe_backend_im_message(struct sipe_core_public *sipe_public,
296 const gchar *from,
297 const gchar *html);
298 void sipe_backend_im_topic(struct sipe_core_public *sipe_public,
299 const gchar *with,
300 const gchar *topic);
301
302 /** MARKUP *******************************************************************/
303
304 gchar *sipe_backend_markup_css_property(const gchar *style,
305 const gchar *option);
306 gchar *sipe_backend_markup_strip_html(const gchar *html);
307
308 /** MEDIA ********************************************************************/
309
310 typedef enum {
311 SIPE_ICE_NO_ICE,
312 SIPE_ICE_DRAFT_6,
313 SIPE_ICE_RFC_5245
314 } SipeIceVersion;
315
316 typedef enum {
317 SIPE_CANDIDATE_TYPE_ANY,
318 SIPE_CANDIDATE_TYPE_HOST,
319 SIPE_CANDIDATE_TYPE_RELAY,
320 SIPE_CANDIDATE_TYPE_SRFLX,
321 SIPE_CANDIDATE_TYPE_PRFLX
322 } SipeCandidateType;
323
324 typedef enum {
325 SIPE_COMPONENT_NONE = 0,
326 SIPE_COMPONENT_RTP = 1,
327 SIPE_COMPONENT_RTCP = 2
328 } SipeComponentType;
329
330 typedef enum {
331 SIPE_MEDIA_AUDIO,
332 SIPE_MEDIA_VIDEO
333 } SipeMediaType;
334
335 typedef enum {
336 SIPE_NETWORK_PROTOCOL_TCP_ACTIVE,
337 SIPE_NETWORK_PROTOCOL_TCP_PASSIVE,
338 SIPE_NETWORK_PROTOCOL_UDP
339 } SipeNetworkProtocol;
340
341 struct sipe_media_call;
342 struct sipe_backend_media;
343 struct sipe_backend_codec;
344 struct sipe_backend_candidate;
345 struct sipe_backend_stream;
346 struct sipe_backend_media_relays;
347
348 struct sipe_media_call {
349 struct sipe_backend_media *backend_private;
350
351 void (*candidates_prepared_cb)(struct sipe_media_call *,
352 struct sipe_backend_stream *);
353 void (*media_end_cb)(struct sipe_media_call *);
354 void (*call_accept_cb)(struct sipe_media_call *, gboolean local);
355 void (*call_reject_cb)(struct sipe_media_call *, gboolean local);
356 void (*call_hold_cb) (struct sipe_media_call *, gboolean local,
357 gboolean state);
358 void (*call_hangup_cb)(struct sipe_media_call *, gboolean local);
359 void (*error_cb)(struct sipe_media_call *, gchar *message);
360 };
361
362 struct sipe_media_relay {
363 gchar *hostname;
364 guint udp_port;
365 guint tcp_port;
366 struct sipe_dns_query *dns_query;
367 };
368
369 /* Media handling */
370 struct sipe_backend_media *sipe_backend_media_new(struct sipe_core_public *sipe_public,
371 struct sipe_media_call *call,
372 const gchar *participant,
373 gboolean initiator);
374 void sipe_backend_media_free(struct sipe_backend_media *media);
375
376 void sipe_backend_media_set_cname(struct sipe_backend_media *media, gchar *cname);
377
378 struct sipe_backend_media_relays * sipe_backend_media_relays_convert(GSList *media_relays,
379 gchar *username,
380 gchar *password);
381 void sipe_backend_media_relays_free(struct sipe_backend_media_relays *media_relays);
382
383 struct sipe_backend_stream *sipe_backend_media_add_stream(struct sipe_backend_media *media,
384 const gchar *id,
385 const gchar *participant,
386 SipeMediaType type,
387 SipeIceVersion ice_version,
388 gboolean initiator,
389 struct sipe_backend_media_relays *media_relays);
390 void sipe_backend_media_remove_stream(struct sipe_backend_media *media,
391 struct sipe_backend_stream *stream);
392 GSList *sipe_backend_media_get_streams(struct sipe_backend_media *media);
393 struct sipe_backend_stream *sipe_backend_media_get_stream_by_id(struct sipe_backend_media *media,
394 const gchar *id);
395 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media *media,
396 struct sipe_backend_stream *stream,
397 GList *candidates);
398 gboolean sipe_backend_media_is_initiator(struct sipe_backend_media *media,
399 struct sipe_backend_stream *stream);
400 gboolean sipe_backend_media_accepted(struct sipe_backend_media *media);
401 gboolean sipe_backend_candidates_prepared(struct sipe_backend_media *media);
402 GList *sipe_backend_media_get_active_local_candidates(struct sipe_backend_media *media,
403 struct sipe_backend_stream *stream);
404 GList *sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media *media,
405 struct sipe_backend_stream *stream);
406
407 /* Stream handling */
408 gchar *sipe_backend_stream_get_id(struct sipe_backend_stream *stream);
409 SipeMediaType sipe_backend_stream_get_type(struct sipe_backend_stream *stream);
410 void sipe_backend_stream_hold(struct sipe_backend_media *media,
411 struct sipe_backend_stream *stream,
412 gboolean local);
413 void sipe_backend_stream_unhold(struct sipe_backend_media *media,
414 struct sipe_backend_stream *stream,
415 gboolean local);
416 gboolean sipe_backend_stream_is_held(struct sipe_backend_stream *stream);
417
418 /* Codec handling */
419 struct sipe_backend_codec *sipe_backend_codec_new(int id,
420 const char *name,
421 SipeMediaType type, guint clock_rate);
422 void sipe_backend_codec_free(struct sipe_backend_codec *codec);
423 int sipe_backend_codec_get_id(struct sipe_backend_codec *codec);
424 /**
425 * @return codec name. Will be g_free'd() by the core.
426 */
427 gchar *sipe_backend_codec_get_name(struct sipe_backend_codec *codec);
428 guint sipe_backend_codec_get_clock_rate(struct sipe_backend_codec *codec);
429 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec *codec,
430 const gchar *name,
431 const gchar *value);
432 GList *sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec *codec);
433 gboolean sipe_backend_set_remote_codecs(struct sipe_backend_media *media,
434 struct sipe_backend_stream *stream,
435 GList *codecs);
436 GList* sipe_backend_get_local_codecs(struct sipe_backend_media *media,
437 struct sipe_backend_stream *stream);
438
439 /* Candidate handling */
440 struct sipe_backend_candidate * sipe_backend_candidate_new(const gchar *foundation,
441 SipeComponentType component,
442 SipeCandidateType type,
443 SipeNetworkProtocol proto,
444 const gchar *ip, guint port,
445 const gchar *username,
446 const gchar *password);
447 void sipe_backend_candidate_free(struct sipe_backend_candidate *candidate);
448 /**
449 * @return user name. Will be g_free'd() by the core.
450 */
451 gchar *sipe_backend_candidate_get_username(struct sipe_backend_candidate *candidate);
452 /**
453 * @return password. Will be g_free'd() by the core.
454 */
455 gchar *sipe_backend_candidate_get_password(struct sipe_backend_candidate *candidate);
456 /**
457 * @return foundation. Will be g_free'd() by the core.
458 */
459 gchar *sipe_backend_candidate_get_foundation(struct sipe_backend_candidate *candidate);
460 /**
461 * @return IP address string. Will be g_free'd() by the core.
462 */
463 gchar *sipe_backend_candidate_get_ip(struct sipe_backend_candidate *candidate);
464 guint sipe_backend_candidate_get_port(struct sipe_backend_candidate *candidate);
465 /**
466 * @return IP address string. Will be g_free'd() by the core.
467 */
468 gchar *sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate *candidate);
469 guint sipe_backend_candidate_get_base_port(struct sipe_backend_candidate *candidate);
470 guint32 sipe_backend_candidate_get_priority(struct sipe_backend_candidate *candidate);
471 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate *candidate, guint32 priority);
472 SipeComponentType sipe_backend_candidate_get_component_type(struct sipe_backend_candidate *candidate);
473 SipeCandidateType sipe_backend_candidate_get_type(struct sipe_backend_candidate *candidate);
474 SipeNetworkProtocol sipe_backend_candidate_get_protocol(struct sipe_backend_candidate *candidate);
475 GList* sipe_backend_get_local_candidates(struct sipe_backend_media *media,
476 struct sipe_backend_stream *stream);
477 void sipe_backend_media_accept(struct sipe_backend_media *media, gboolean local);
478 void sipe_backend_media_hangup(struct sipe_backend_media *media, gboolean local);
479 void sipe_backend_media_reject(struct sipe_backend_media *media, gboolean local);
480
481 /** NETWORK ******************************************************************/
482
483 const gchar *sipe_backend_network_ip_address(void);
484
485 struct sipe_backend_listendata;
486
487 typedef void (*sipe_listen_start_cb)(unsigned short port, gpointer data);
488 typedef void (*sipe_client_connected_cb)(struct sipe_backend_fd *fd, gpointer data);
489
490 struct sipe_backend_listendata *
491 sipe_backend_network_listen_range(unsigned short port_min,
492 unsigned short port_max,
493 sipe_listen_start_cb listen_cb,
494 sipe_client_connected_cb connect_cb,
495 gpointer data);
496 void sipe_backend_network_listen_cancel(struct sipe_backend_listendata *ldata);
497
498 gboolean sipe_backend_fd_is_valid(struct sipe_backend_fd *fd);
499 void sipe_backend_fd_free(struct sipe_backend_fd *fd);
500
501 /** NOTIFICATIONS *************************************************************/
502
503 void sipe_backend_notify_message_error(struct sipe_core_public *sipe_public,
504 struct sipe_backend_chat_session *backend_session,
505 const gchar *who,
506 const gchar *message);
507 void sipe_backend_notify_message_info(struct sipe_core_public *sipe_public,
508 struct sipe_backend_chat_session *backend_session,
509 const gchar *who,
510 const gchar *message);
511
512 /**
513 * @param msg error message. Maybe @NULL
514 */
515 void sipe_backend_notify_error(struct sipe_core_public *sipe_public,
516 const gchar *title,
517 const gchar *msg);
518
519 /** SCHEDULE *****************************************************************/
520
521 gpointer sipe_backend_schedule_seconds(struct sipe_core_public *sipe_public,
522 guint timeout,
523 gpointer data);
524 gpointer sipe_backend_schedule_mseconds(struct sipe_core_public *sipe_public,
525 guint timeout,
526 gpointer data);
527 void sipe_backend_schedule_cancel(struct sipe_core_public *sipe_public,
528 gpointer data);
529
530 /** SEARCH *******************************************************************/
531
532 struct sipe_backend_search_results;
533
534 struct sipe_backend_search_results *sipe_backend_search_results_start(struct sipe_core_public *sipe_public);
535 void sipe_backend_search_results_add(struct sipe_core_public *sipe_public,
536 struct sipe_backend_search_results *results,
537 const gchar *uri,
538 const gchar *name,
539 const gchar *company,
540 const gchar *country,
541 const gchar *email);
542 void sipe_backend_search_results_finalize(struct sipe_core_public *sipe_public,
543 struct sipe_backend_search_results *results,
544 const gchar *description,
545 gboolean more);
546
547 /** SETTINGS *****************************************************************/
548
549 typedef enum {
550 SIPE_SETTING_EMAIL_URL = 0,
551 SIPE_SETTING_EMAIL_LOGIN,
552 SIPE_SETTING_EMAIL_PASSWORD,
553 SIPE_SETTING_GROUPCHAT_USER,
554 SIPE_SETTING_USER_AGENT,
555 SIPE_SETTING_LAST
556 } sipe_setting;
557 const gchar *sipe_backend_setting(struct sipe_core_public *sipe_public,
558 sipe_setting type);
559
560 /** STATUS *******************************************************************/
561
562 /* type == SIPE_ACTIVITY_xxx (see sipe-core.h) */
563 const gchar *sipe_backend_activity_to_token(guint type);
564 guint sipe_backend_token_to_activity(const gchar *token);
565
566 const gchar *sipe_backend_status(struct sipe_core_public *sipe_public);
567 gboolean sipe_backend_status_and_note(struct sipe_core_public *sipe_public,
568 const gchar *status_id,
569 const gchar *message);
570
571 /** TRANSPORT ****************************************************************/
572
573 typedef void transport_connected_cb(struct sipe_transport_connection *conn);
574 typedef void transport_input_cb(struct sipe_transport_connection *conn);
575 typedef void transport_error_cb(struct sipe_transport_connection *conn,
576 const gchar *msg);
577
578 typedef struct {
579 guint type;
580 const gchar *server_name;
581 guint server_port;
582 gpointer user_data;
583 transport_connected_cb *connected;
584 transport_input_cb *input;
585 transport_error_cb *error;
586 } sipe_connect_setup;
587 struct sipe_transport_connection *sipe_backend_transport_connect(struct sipe_core_public *sipe_public,
588 const sipe_connect_setup *setup);
589 void sipe_backend_transport_disconnect(struct sipe_transport_connection *conn);
590 void sipe_backend_transport_message(struct sipe_transport_connection *conn,
591 const gchar *buffer);
592 void sipe_backend_transport_flush(struct sipe_transport_connection *conn);
593
594 /** USER *********************************************************************/
595
596 void sipe_backend_user_feedback_typing(struct sipe_core_public *sipe_public,
597 const gchar *from);
598 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public *sipe_public,
599 const gchar *from);
600
601 /**
602 * Present a query that is to be accepted or declined by the user
603 *
604 * @param sipe_public The handle representing the protocol instance
605 * @param message Text of the query to be shown to user
606 * @param accept_label Label to be displayed on UI control that accepts query
607 * @param decline_label Label to be displayed on UI control that declines query
608 * @param key Opaque handle uniquely identifying the query. Backend
609 * should store it for the case SIPE core requests the
610 * query to be closed prematurely.
611 */
612 void sipe_backend_user_ask(struct sipe_core_public *sipe_public,
613 const gchar *message,
614 const gchar *accept_label,
615 const gchar *decline_label,
616 gpointer key);
617
618 /**
619 * Closes the pending user query
620 *
621 * @param key Opaque handle uniquely identifying the query.
622 */
623 void sipe_backend_user_close_ask(gpointer key);
624
625 /** BUDDIES ******************************************************************/
626
627 /* The list of properties a buddy can have */
628 typedef enum
629 {
630 SIPE_BUDDY_INFO_DISPLAY_NAME,
631 SIPE_BUDDY_INFO_JOB_TITLE,
632 SIPE_BUDDY_INFO_CITY,
633 SIPE_BUDDY_INFO_STATE,
634 SIPE_BUDDY_INFO_OFFICE,
635 SIPE_BUDDY_INFO_DEPARTMENT,
636 SIPE_BUDDY_INFO_COUNTRY,
637 SIPE_BUDDY_INFO_WORK_PHONE,
638 SIPE_BUDDY_INFO_WORK_PHONE_DISPLAY,
639 SIPE_BUDDY_INFO_COMPANY,
640 SIPE_BUDDY_INFO_EMAIL,
641 SIPE_BUDDY_INFO_DEVICE,
642 SIPE_BUDDY_INFO_SITE,
643 SIPE_BUDDY_INFO_ZIPCODE,
644 SIPE_BUDDY_INFO_STREET,
645 SIPE_BUDDY_INFO_MOBILE_PHONE,
646 SIPE_BUDDY_INFO_MOBILE_PHONE_DISPLAY,
647 SIPE_BUDDY_INFO_HOME_PHONE,
648 SIPE_BUDDY_INFO_HOME_PHONE_DISPLAY,
649 SIPE_BUDDY_INFO_OTHER_PHONE,
650 SIPE_BUDDY_INFO_OTHER_PHONE_DISPLAY,
651 SIPE_BUDDY_INFO_CUSTOM1_PHONE,
652 SIPE_BUDDY_INFO_CUSTOM1_PHONE_DISPLAY,
653 } sipe_buddy_info_fields;
654
655 /* Opaque token */
656 typedef void* sipe_backend_buddy;
657
658 /**
659 * Find a buddy in the given group of the buddy list, or anywhere on the
660 * list if @group_name is empty
661 *
662 * @param sipe_public The handle representing the protocol instance making the call
663 * @param buddy_name The name of the buddy
664 * @param group_name The name of the group to look in, or NULL for any group
665 * @return opaque handle to the buddy, or NULL if no buddy found
666 */
667 sipe_backend_buddy sipe_backend_buddy_find(struct sipe_core_public *sipe_public,
668 const gchar *buddy_name,
669 const gchar *group_name);
670
671 /*
672 * Find all named buddies in the given group of the buddy list, or anywhere on the
673 * list if @group_name is empty; or all buddies if @name is empty
674 *
675 * @param sipe_public The handle representing the protocol instance making the call
676 * @param name The name of the buddy
677 * @param group_name The name of the group to look in, or NULL for any group
678 * @return GSList of opaque handles to the buddies
679 */
680 GSList* sipe_backend_buddy_find_all(struct sipe_core_public *sipe_public,
681 const gchar *buddy_name,
682 const gchar *group_name);
683
684 /**
685 * Gets the name of a contact.
686 *
687 * @param sipe_public The handle representing the protocol instance making the call
688 * @param who The opaque handle to the contact as found by find_buddy
689 * @return The name. Must be freed.
690 */
691 gchar* sipe_backend_buddy_get_name(struct sipe_core_public *sipe_public,
692 const sipe_backend_buddy who);
693
694 /**
695 * Gets the alias for a contact.
696 *
697 * @param sipe_public The handle representing the protocol instance making the call
698 * @param who The opaque handle to the contact as found by find_buddy
699 * @return The alias. Must be gfree'd.
700 */
701 gchar* sipe_backend_buddy_get_alias(struct sipe_core_public *sipe_public,
702 const sipe_backend_buddy who);
703
704 /**
705 * Gets the server alias for a contact.
706 *
707 * @param sipe_public The handle representing the protocol instance making the call
708 * @param who The opaque handle to the contact as found by find_buddy
709 * @return The alias. Must be freed.
710 */
711 gchar* sipe_backend_buddy_get_server_alias(struct sipe_core_public *sipe_public,
712 const sipe_backend_buddy who);
713
714 /**
715 * Gets the local alias for a contact
716 *
717 * @param sipe_public The handle representing the protocol instance making the call
718 * @param uri the budyy name
719 *
720 * @return the alias. Must be @g_free()'d.
721 */
722 gchar *sipe_backend_buddy_get_local_alias(struct sipe_core_public *sipe_public,
723 const sipe_backend_buddy who);
724
725 /**
726 * Gets the name of the group a contact belongs to.
727 *
728 * @param sipe_public The handle representing the protocol instance making the call
729 * @param who The opaque handle to the contact as found by find_buddy
730 * @return The name. Must be freed.
731 */
732 gchar* sipe_backend_buddy_get_group_name(struct sipe_core_public *sipe_public,
733 const sipe_backend_buddy who);
734
735 /**
736 * Called to retrieve a buddy-specific setting.
737 *
738 * @param sipe_public The handle representing the protocol instance making the call
739 * @param buddy The handle representing the buddy
740 * @param key The name of the setting
741 * @return The value of the setting. Must be freed.
742 */
743 gchar* sipe_backend_buddy_get_string(struct sipe_core_public *sipe_public,
744 sipe_backend_buddy buddy,
745 const sipe_buddy_info_fields key);
746
747 /**
748 * Called to set a buddy-specific setting.
749 *
750 * @param sipe_public The handle representing the protocol instance making the call
751 * @param buddy The handle representing the buddy
752 * @param key The name of the setting
753 * @param val The value to set
754 */
755 void sipe_backend_buddy_set_string(struct sipe_core_public *sipe_public,
756 sipe_backend_buddy buddy,
757 const sipe_buddy_info_fields key,
758 const gchar *val);
759
760 /**
761 * Get the status token for a contact
762 *
763 * @param sipe_public The handle representing the protocol instance making the call
764 * @param uri SIP URI of the contact
765 *
766 * @return status token
767 */
768 const gchar *sipe_backend_buddy_get_status(struct sipe_core_public *sipe_public,
769 const gchar *uri);
770
771 /**
772 * Sets the alias for a contact.
773 *
774 * @param sipe_public The handle representing the protocol instance making the call
775 * @param who The opaque handle to the contact as found by find_buddy
776 * @param alias The location where the alias will be put
777 * case. FALSE if the buddy was not found. The value of alias will not be changed.
778 */
779 void sipe_backend_buddy_set_alias(struct sipe_core_public *sipe_public,
780 const sipe_backend_buddy who,
781 const gchar *alias);
782
783 /**
784 * Sets the server alias for a contact.
785 *
786 * @param sipe_public The handle representing the protocol instance making the call
787 * @param who The opaque handle to the contact as found by find_buddy
788 * @param alias The server alias of the contact
789 */
790 void sipe_backend_buddy_set_server_alias(struct sipe_core_public *sipe_public,
791 const sipe_backend_buddy who,
792 const gchar *alias);
793
794 /**
795 * Add a contact to the buddy list
796 *
797 * @param sipe_public The handle representing the protocol instance making the call
798 * @param name The name of the contact
799 * @param alias The alias of the contact
800 * @param groupname The name of the group to add this contact to
801 * @return A handle to the newly created buddy
802 */
803 sipe_backend_buddy sipe_backend_buddy_add(struct sipe_core_public *sipe_public,
804 const gchar *name,
805 const gchar *alias,
806 const gchar *groupname);
807
808 /**
809 * Remove a contact from the buddy list
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 */
814 void sipe_backend_buddy_remove(struct sipe_core_public *sipe_public,
815 const sipe_backend_buddy who);
816
817 /**
818 * Notifies the user that a remote user has wants to add the local user to his
819 * or her buddy list and requires authorization to do so.
820 *
821 * @param sipe_public The handle representing the protocol instance making the call
822 * @param who The name of the user that added this account
823 * @param alias The optional alias of the remote user
824 * @param on_list True if the user is already in our list
825 * @param auth_cb The callback called when the local user accepts
826 * @param deny_cb The callback called when the local user rejects
827 * @param data Data to be passed back to the above callbacks
828 */
829 typedef void (*sipe_backend_buddy_request_authorization_cb)(void *);
830
831 void sipe_backend_buddy_request_add(struct sipe_core_public *sipe_public,
832 const gchar *who,
833 const gchar *alias);
834
835 void sipe_backend_buddy_request_authorization(struct sipe_core_public *sipe_public,
836 const gchar *who,
837 const gchar *alias,
838 gboolean on_list,
839 sipe_backend_buddy_request_authorization_cb auth_cb,
840 sipe_backend_buddy_request_authorization_cb deny_cb,
841 gpointer data);
842
843 gboolean sipe_backend_buddy_is_blocked(struct sipe_core_public *sipe_public,
844 const gchar *who);
845
846 void sipe_backend_buddy_set_blocked_status(struct sipe_core_public *sipe_public,
847 const gchar *who,
848 gboolean blocked);
849
850 void sipe_backend_buddy_set_status(struct sipe_core_public *sipe_public,
851 const gchar *who,
852 const gchar *status_id);
853
854 /**
855 * Called when a new internal group is about to be added. If this returns FALSE,
856 * the group will not be added.
857 *
858 * @param sipe_public The handle representing the protocol instance making the call
859 * @param group The group being added
860 * @return TRUE if everything is ok, FALSE if the group should not be added
861 */
862 gboolean sipe_backend_buddy_group_add(struct sipe_core_public *sipe_public,
863 const gchar *group_name);
864
865 /**
866 * Present requested buddy information to the user
867 */
868 struct sipe_backend_buddy_info;
869 struct sipe_backend_buddy_info *sipe_backend_buddy_info_start(struct sipe_core_public *sipe_public);
870 void sipe_backend_buddy_info_add(struct sipe_core_public *sipe_public,
871 struct sipe_backend_buddy_info *info,
872 const gchar *description,
873 const gchar *value);
874 void sipe_backend_buddy_info_break(struct sipe_core_public *sipe_public,
875 struct sipe_backend_buddy_info *info);
876 void sipe_backend_buddy_info_finalize(struct sipe_core_public *sipe_public,
877 struct sipe_backend_buddy_info *info,
878 const gchar *uri);
879
880 struct sipe_backend_buddy_tooltip;
881 void sipe_backend_buddy_tooltip_add(struct sipe_core_public *sipe_public,
882 struct sipe_backend_buddy_tooltip *tooltip,
883 const gchar *description,
884 const gchar *value);
885
886 /**
887 * Buddy menu creation
888 */
889 enum sipe_buddy_menu_type {
890 SIPE_BUDDY_MENU_MAKE_CHAT_LEADER = 0,
891 SIPE_BUDDY_MENU_REMOVE_FROM_CHAT,
892 SIPE_BUDDY_MENU_INVITE_TO_CHAT,
893 SIPE_BUDDY_MENU_NEW_CHAT,
894 SIPE_BUDDY_MENU_MAKE_CALL,
895 SIPE_BUDDY_MENU_SEND_EMAIL,
896 SIPE_BUDDY_MENU_ACCESS_LEVEL_HELP,
897 SIPE_BUDDY_MENU_CHANGE_ACCESS_LEVEL,
898 SIPE_BUDDY_MENU_ADD_NEW_DOMAIN,
899 SIPE_BUDDY_MENU_TYPES
900 };
901
902 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_start(struct sipe_core_public *sipe_public);
903 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_add(struct sipe_core_public *sipe_public,
904 struct sipe_backend_buddy_menu *menu,
905 const gchar *label,
906 enum sipe_buddy_menu_type type,
907 gpointer parameter);
908 struct sipe_backend_buddy_menu *sipe_backend_buddy_menu_separator(struct sipe_core_public *sipe_public,
909 struct sipe_backend_buddy_menu *menu,
910 const gchar *label);
911 struct sipe_backend_buddy_menu *sipe_backend_buddy_sub_menu_add(struct sipe_core_public *sipe_public,
912 struct sipe_backend_buddy_menu *menu,
913 const gchar *label,
914 struct sipe_backend_buddy_menu *sub);
915
916 #ifdef __cplusplus
917 }
918 #endif
919
920 /*
921 Local Variables:
922 mode: c
923 c-file-style: "bsd"
924 indent-tabs-mode: t
925 tab-width: 8
926 End:
927 */
A third-party Pidgin plugin for Microsoft LCS/OCS