6 * Copyright (C) 2010 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_session
;
46 struct sipe_core_public
;
47 struct sipe_transport_connection
;
48 struct sipe_file_transfer
;
49 struct sipe_media_call
;
52 /** MISC. STUFF **************************************************************/
54 * Get the version of the backend suitable for e.g. UserAgent
56 * @return backend version string. Will be g_free()'d.by the core.
58 gchar
*sipe_backend_version(void);
60 /** DEBUGGING ****************************************************************/
63 SIPE_DEBUG_LEVEL_INFO
,
64 SIPE_DEBUG_LEVEL_WARNING
,
65 SIPE_DEBUG_LEVEL_ERROR
,
66 SIPE_DEBUG_LEVEL_FATAL
,
70 * Output debug information without formatting
72 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
74 * @param level debug level
75 * @param msg debug message "\n" will be automatically appended.
77 void sipe_backend_debug_literal(sipe_debug_level level
,
81 * Output debug information
83 * Shouldn't be used directly. Instead use SIPE_DEBUG_xxx() macros
85 * @param level debug level
86 * @param format format string. "\n" will be automatically appended.
88 void sipe_backend_debug(sipe_debug_level level
,
90 ...) G_GNUC_PRINTF(2, 3);
92 /* Convenience macros */
93 #define SIPE_DEBUG_INFO(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_INFO, fmt, __VA_ARGS__)
94 #define SIPE_DEBUG_INFO_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_INFO, msg)
95 #define SIPE_DEBUG_WARNING(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_WARNING, fmt, __VA_ARGS__)
96 #define SIPE_DEBUG_WARNING_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_WARNING, msg)
97 #define SIPE_DEBUG_ERROR(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_ERROR, fmt, __VA_ARGS__)
98 #define SIPE_DEBUG_ERROR_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_ERROR, msg)
99 #define SIPE_DEBUG_FATAL(fmt, ...) sipe_backend_debug(SIPE_DEBUG_LEVEL_FATAL, fmt, __VA_ARGS__)
100 #define SIPE_DEBUG_FATAL_NOFORMAT(msg) sipe_backend_debug_literal(SIPE_DEBUG_LEVEL_FATAL, msg)
103 * Check backend debugging status
105 * @return TRUE if debugging is enabled
107 gboolean
sipe_backend_debug_enabled(void);
109 /** CHAT *********************************************************************/
111 //void sipe_backend_chat_(struct sipe_backend_session *backend_session, );
112 void sipe_backend_chat_add(struct sipe_backend_session
*backend_session
,
115 void sipe_backend_chat_close(struct sipe_backend_session
*backend_session
);
116 struct sipe_backend_session
*sipe_backend_chat_create(struct sipe_core_public
*sipe_public
,
121 gboolean
sipe_backend_chat_find(struct sipe_backend_session
*backend_session
,
123 gboolean
sipe_backend_chat_is_operator(struct sipe_backend_session
*backend_session
,
125 void sipe_backend_chat_message(struct sipe_core_public
*sipe_public
,
129 void sipe_backend_chat_operator(struct sipe_backend_session
*backend_session
,
131 void sipe_backend_chat_rejoin_all(struct sipe_core_public
*sipe_public
);
132 void sipe_backend_chat_remove(struct sipe_backend_session
*backend_session
,
134 void sipe_backend_chat_topic(struct sipe_backend_session
*backend_session
,
137 /** CONNECTION ***************************************************************/
139 void sipe_backend_connection_completed(struct sipe_core_public
*sipe_public
);
142 SIPE_CONNECTION_ERROR_NETWORK
= 0,
143 SIPE_CONNECTION_ERROR_INVALID_USERNAME
,
144 SIPE_CONNECTION_ERROR_INVALID_SETTINGS
,
145 SIPE_CONNECTION_ERROR_AUTHENTICATION_FAILED
,
146 SIPE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE
,
147 SIPE_CONNECTION_ERROR_LAST
148 } sipe_connection_error
;
149 void sipe_backend_connection_error(struct sipe_core_public
*sipe_public
,
150 sipe_connection_error error
,
153 gboolean
sipe_backend_connection_is_disconnecting(struct sipe_core_public
*sipe_public
);
154 gboolean
sipe_backend_connection_is_valid(struct sipe_core_public
*sipe_public
);
156 /** DNS QUERY ****************************************************************/
158 void sipe_backend_dns_query(struct sipe_core_public
*sipe_public
,
159 const gchar
*protocol
,
160 const gchar
*transport
,
161 const gchar
*domain
);
163 /** FILE TRANSFER ************************************************************/
164 void sipe_backend_ft_error(struct sipe_file_transfer
*ft
,
165 const gchar
*errmsg
);
166 const gchar
*sipe_backend_ft_get_error(struct sipe_file_transfer
*ft
);
167 void sipe_backend_ft_deallocate(struct sipe_file_transfer
*ft
);
170 * Try to read up to @c size bytes from file transfer connection
172 * @param backend_ft backend private file transfer data.
173 * @param data buffer to read data into.
174 * @param size buffer size in bytes.
176 * @return number of bytes read or negative on failure.
177 * EAGAIN should return 0 bytes read.
179 gssize
sipe_backend_ft_read(struct sipe_file_transfer
*ft
,
184 * Try to write up to @c size bytes to file transfer connection
186 * @param backend_ft backend private file transfer data.
187 * @param data data to write
188 * @param size buffer size in bytes.
190 * @return number of bytes read or negative on failure.
191 * EAGAIN should return 0 bytes written.
193 gssize
sipe_backend_ft_write(struct sipe_file_transfer
*ft
,
198 void sipe_backend_ft_cancel_local(struct sipe_file_transfer
*ft
);
199 void sipe_backend_ft_cancel_remote(struct sipe_file_transfer
*ft
);
201 void sipe_backend_ft_incoming(struct sipe_core_public
*sipe_public
,
202 struct sipe_file_transfer
*ft
,
204 const gchar
*file_name
,
206 gboolean
sipe_backend_ft_incoming_accept(struct sipe_file_transfer
*ft
,
208 unsigned short port_min
,
209 unsigned short port_max
);
211 /** IM ***********************************************************************/
213 void sipe_backend_im_message(struct sipe_core_public
*sipe_public
,
217 /** MARKUP *******************************************************************/
219 gchar
*sipe_backend_markup_css_property(const gchar
*style
,
220 const gchar
*option
);
221 gchar
*sipe_backend_markup_strip_html(const gchar
*html
);
223 /** MEDIA ********************************************************************/
226 SIPE_CANDIDATE_TYPE_HOST
,
227 SIPE_CANDIDATE_TYPE_RELAY
,
228 SIPE_CANDIDATE_TYPE_SRFLX
,
229 SIPE_CANDIDATE_TYPE_PRFLX
233 SIPE_COMPONENT_NONE
= 0,
234 SIPE_COMPONENT_RTP
= 1,
235 SIPE_COMPONENT_RTCP
= 2
244 SIPE_NETWORK_PROTOCOL_TCP
,
245 SIPE_NETWORK_PROTOCOL_UDP
246 } SipeNetworkProtocol
;
248 struct sipe_media_call
;
249 struct sipe_backend_media
;
250 struct sipe_backend_codec
;
251 struct sipe_backend_candidate
;
252 struct sipe_backend_stream
;
254 struct sipe_media_call
{
255 struct sipe_backend_media
*backend_private
;
257 void (*candidates_prepared_cb
)(struct sipe_media_call
*);
258 void (*media_connected_cb
)();
259 void (*call_accept_cb
)(struct sipe_media_call
*, gboolean local
);
260 void (*call_reject_cb
)(struct sipe_media_call
*, gboolean local
);
261 void (*call_hold_cb
) (struct sipe_media_call
*, gboolean local
,
263 void (*call_hangup_cb
)(struct sipe_media_call
*, gboolean local
);
265 gboolean local_on_hold
;
266 gboolean remote_on_hold
;
270 struct sipe_backend_media
*sipe_backend_media_new(struct sipe_core_public
*sipe_public
,
271 struct sipe_media_call
*call
,
272 const gchar
*participant
,
274 void sipe_backend_media_free(struct sipe_backend_media
*media
);
275 struct sipe_backend_stream
*sipe_backend_media_add_stream(struct sipe_backend_media
*media
,
276 const gchar
*participant
,
277 SipeMediaType type
, gboolean use_nice
,
279 void sipe_backend_media_remove_stream(struct sipe_backend_media
*media
,
280 struct sipe_backend_stream
*stream
);
281 void sipe_backend_media_add_remote_candidates(struct sipe_backend_media
*media
,
282 struct sipe_backend_stream
*stream
,
284 gboolean
sipe_backend_media_is_initiator(struct sipe_backend_media
*media
,
285 struct sipe_backend_stream
*stream
);
286 GList
*sipe_backend_media_get_active_local_candidates(struct sipe_backend_media
*media
,
287 struct sipe_backend_stream
*stream
);
288 GList
*sipe_backend_media_get_active_remote_candidates(struct sipe_backend_media
*media
,
289 struct sipe_backend_stream
*stream
);
292 struct sipe_backend_codec
*sipe_backend_codec_new(int id
,
294 SipeMediaType type
, guint clock_rate
);
295 void sipe_backend_codec_free(struct sipe_backend_codec
*codec
);
296 int sipe_backend_codec_get_id(struct sipe_backend_codec
*codec
);
298 * @return codec name. Will be g_free'd() by the core.
300 gchar
*sipe_backend_codec_get_name(struct sipe_backend_codec
*codec
);
301 guint
sipe_backend_codec_get_clock_rate(struct sipe_backend_codec
*codec
);
302 void sipe_backend_codec_add_optional_parameter(struct sipe_backend_codec
*codec
,
305 GList
*sipe_backend_codec_get_optional_parameters(struct sipe_backend_codec
*codec
);
306 gboolean
sipe_backend_set_remote_codecs(struct sipe_backend_media
*media
,
307 struct sipe_backend_stream
*stream
,
309 GList
* sipe_backend_get_local_codecs(struct sipe_media_call
*call
,
310 struct sipe_backend_stream
*stream
);
312 /* Candidate handling */
313 struct sipe_backend_candidate
* sipe_backend_candidate_new(const gchar
*foundation
,
314 SipeComponentType component
,
315 SipeCandidateType type
,
316 SipeNetworkProtocol proto
,
317 const gchar
*ip
, guint port
);
318 void sipe_backend_candidate_free(struct sipe_backend_candidate
*candidate
);
320 * @return user name. Will be g_free'd() by the core.
322 gchar
*sipe_backend_candidate_get_username(struct sipe_backend_candidate
*candidate
);
324 * @return password. Will be g_free'd() by the core.
326 gchar
*sipe_backend_candidate_get_password(struct sipe_backend_candidate
*candidate
);
328 * @return foundation. Will be g_free'd() by the core.
330 gchar
*sipe_backend_candidate_get_foundation(struct sipe_backend_candidate
*candidate
);
332 * @return IP address string. Will be g_free'd() by the core.
334 gchar
*sipe_backend_candidate_get_ip(struct sipe_backend_candidate
*candidate
);
335 guint
sipe_backend_candidate_get_port(struct sipe_backend_candidate
*candidate
);
337 * @return IP address string. Will be g_free'd() by the core.
339 gchar
*sipe_backend_candidate_get_base_ip(struct sipe_backend_candidate
*candidate
);
340 guint
sipe_backend_candidate_get_base_port(struct sipe_backend_candidate
*candidate
);
341 guint32
sipe_backend_candidate_get_priority(struct sipe_backend_candidate
*candidate
);
342 void sipe_backend_candidate_set_priority(struct sipe_backend_candidate
*candidate
, guint32 priority
);
343 SipeComponentType
sipe_backend_candidate_get_component_type(struct sipe_backend_candidate
*candidate
);
344 SipeCandidateType
sipe_backend_candidate_get_type(struct sipe_backend_candidate
*candidate
);
345 SipeNetworkProtocol
sipe_backend_candidate_get_protocol(struct sipe_backend_candidate
*candidate
);
346 void sipe_backend_candidate_set_username_and_pwd(struct sipe_backend_candidate
*candidate
,
347 const gchar
*username
,
348 const gchar
*password
);
349 GList
* sipe_backend_get_local_candidates(struct sipe_backend_media
*media
,
350 struct sipe_backend_stream
*stream
);
351 void sipe_backend_media_hold(struct sipe_backend_media
*media
, gboolean local
);
352 void sipe_backend_media_unhold(struct sipe_backend_media
*media
, gboolean local
);
353 void sipe_backend_media_hangup(struct sipe_backend_media
*media
, gboolean local
);
354 void sipe_backend_media_reject(struct sipe_backend_media
*media
, gboolean local
);
356 /** NETWORK ******************************************************************/
358 const gchar
*sipe_backend_network_ip_address(void);
360 /** SCHEDULE *****************************************************************/
362 gpointer
sipe_backend_schedule_seconds(struct sipe_core_public
*sipe_public
,
365 gpointer
sipe_backend_schedule_mseconds(struct sipe_core_public
*sipe_public
,
368 void sipe_backend_schedule_cancel(struct sipe_core_public
*sipe_public
,
371 /** SETTINGS *****************************************************************/
374 SIPE_SETTING_EMAIL_URL
= 0,
375 SIPE_SETTING_EMAIL_LOGIN
,
376 SIPE_SETTING_EMAIL_PASSWORD
,
377 SIPE_SETTING_USER_AGENT
,
380 const gchar
*sipe_backend_setting(struct sipe_core_public
*sipe_public
,
383 /** TRANSPORT ****************************************************************/
385 typedef void transport_connected_cb(struct sipe_transport_connection
*conn
);
386 typedef void transport_input_cb(struct sipe_transport_connection
*conn
);
387 typedef void transport_error_cb(struct sipe_transport_connection
*conn
,
392 const gchar
*server_name
;
395 transport_connected_cb
*connected
;
396 transport_input_cb
*input
;
397 transport_error_cb
*error
;
398 } sipe_connect_setup
;
399 struct sipe_transport_connection
*sipe_backend_transport_connect(struct sipe_core_public
*sipe_public
,
400 const sipe_connect_setup
*setup
);
401 void sipe_backend_transport_disconnect(struct sipe_transport_connection
*conn
);
402 void sipe_backend_transport_message(struct sipe_transport_connection
*conn
,
403 const gchar
*buffer
);
404 void sipe_backend_transport_flush(struct sipe_transport_connection
*conn
);
406 /** USER *********************************************************************/
408 void sipe_backend_user_feedback_typing(struct sipe_core_public
*sipe_public
,
410 void sipe_backend_user_feedback_typing_stop(struct sipe_core_public
*sipe_public
,
413 /** NOTIFICATIONS *************************************************************/
415 void sipe_backend_notify_error(const gchar
*title
, const gchar
*msg
);