Mercurial > pidgin.yaz
comparison libpurple/media.h @ 32687:02a2e8183b1d
Clean the API documentation in preparation for 3.0.0 by removing all the old @since tags.
author | andrew.victor@mxit.com |
---|---|
date | Sun, 25 Sep 2011 18:56:58 +0000 |
parents | a4ba3b194ce3 |
children |
comparison
equal
deleted
inserted
replaced
32685:9d5b87e1a4d0 | 32687:02a2e8183b1d |
---|---|
55 | 55 |
56 /** | 56 /** |
57 * Gets the media class's GType | 57 * Gets the media class's GType |
58 * | 58 * |
59 * @return The media class's GType. | 59 * @return The media class's GType. |
60 * | |
61 * @since 2.6.0 | |
62 */ | 60 */ |
63 GType purple_media_get_type(void); | 61 GType purple_media_get_type(void); |
64 | 62 |
65 /** | 63 /** |
66 * Gets a list of session IDs. | 64 * Gets a list of session IDs. |
67 * | 65 * |
68 * @param media The media session from which to retrieve session IDs. | 66 * @param media The media session from which to retrieve session IDs. |
69 * | 67 * |
70 * @return GList of session IDs. The caller must free the list. | 68 * @return GList of session IDs. The caller must free the list. |
71 * | |
72 * @since 2.6.0 | |
73 */ | 69 */ |
74 GList *purple_media_get_session_ids(PurpleMedia *media); | 70 GList *purple_media_get_session_ids(PurpleMedia *media); |
75 | 71 |
76 /** | 72 /** |
77 * Gets the PurpleAccount this media session is on. | 73 * Gets the PurpleAccount this media session is on. |
78 * | 74 * |
79 * @param media The media session to retrieve the account from. | 75 * @param media The media session to retrieve the account from. |
80 * | 76 * |
81 * @return The account retrieved. | 77 * @return The account retrieved. |
82 * | |
83 * @since 2.6.0 | |
84 */ | 78 */ |
85 PurpleAccount *purple_media_get_account(PurpleMedia *media); | 79 PurpleAccount *purple_media_get_account(PurpleMedia *media); |
86 | 80 |
87 /** | 81 /** |
88 * Gets the prpl data from the media session. | 82 * Gets the prpl data from the media session. |
89 * | 83 * |
90 * @param media The media session to retrieve the prpl data from. | 84 * @param media The media session to retrieve the prpl data from. |
91 * | 85 * |
92 * @return The prpl data retrieved. | 86 * @return The prpl data retrieved. |
93 * | |
94 * @since 2.6.0 | |
95 */ | 87 */ |
96 gpointer purple_media_get_prpl_data(PurpleMedia *media); | 88 gpointer purple_media_get_prpl_data(PurpleMedia *media); |
97 | 89 |
98 /** | 90 /** |
99 * Sets the prpl data on the media session. | 91 * Sets the prpl data on the media session. |
100 * | 92 * |
101 * @param media The media session to set the prpl data on. | 93 * @param media The media session to set the prpl data on. |
102 * @param prpl_data The data to set on the media session. | 94 * @param prpl_data The data to set on the media session. |
103 * | |
104 * @since 2.6.0 | |
105 */ | 95 */ |
106 void purple_media_set_prpl_data(PurpleMedia *media, gpointer prpl_data); | 96 void purple_media_set_prpl_data(PurpleMedia *media, gpointer prpl_data); |
107 | 97 |
108 /** | 98 /** |
109 * Signals an error in the media session. | 99 * Signals an error in the media session. |
110 * | 100 * |
111 * @param media The media object to set the state on. | 101 * @param media The media object to set the state on. |
112 * @param error The format of the error message to send in the signal. | 102 * @param error The format of the error message to send in the signal. |
113 * @param ... The arguments to plug into the format. | 103 * @param ... The arguments to plug into the format. |
114 * | |
115 * @since 2.6.0 | |
116 */ | 104 */ |
117 void purple_media_error(PurpleMedia *media, const gchar *error, ...); | 105 void purple_media_error(PurpleMedia *media, const gchar *error, ...); |
118 | 106 |
119 /** | 107 /** |
120 * Ends all streams that match the given parameters | 108 * Ends all streams that match the given parameters |
121 * | 109 * |
122 * @param media The media object with which to end streams. | 110 * @param media The media object with which to end streams. |
123 * @param session_id The session to end streams on. | 111 * @param session_id The session to end streams on. |
124 * @param participant The participant to end streams with. | 112 * @param participant The participant to end streams with. |
125 * | |
126 * @since 2.6.0 | |
127 */ | 113 */ |
128 void purple_media_end(PurpleMedia *media, const gchar *session_id, | 114 void purple_media_end(PurpleMedia *media, const gchar *session_id, |
129 const gchar *participant); | 115 const gchar *participant); |
130 | 116 |
131 /** | 117 /** |
134 * @param media The media instance to containing the stream to signal. | 120 * @param media The media instance to containing the stream to signal. |
135 * @param type The type of info being signaled. | 121 * @param type The type of info being signaled. |
136 * @param session_id The id of the session of the stream being signaled. | 122 * @param session_id The id of the session of the stream being signaled. |
137 * @param participant The participant of the stream being signaled. | 123 * @param participant The participant of the stream being signaled. |
138 * @param local TRUE if the info originated locally, FALSE if on the remote end. | 124 * @param local TRUE if the info originated locally, FALSE if on the remote end. |
139 * | |
140 * @since 2.6.0 | |
141 */ | 125 */ |
142 void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type, | 126 void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type, |
143 const gchar *session_id, const gchar *participant, | 127 const gchar *session_id, const gchar *participant, |
144 gboolean local); | 128 gboolean local); |
145 | 129 |
156 * - "sdes-phone" : The PHONE to put in SDES messages | 140 * - "sdes-phone" : The PHONE to put in SDES messages |
157 * | 141 * |
158 * @param media The media object to set the parameters on. | 142 * @param media The media object to set the parameters on. |
159 * @param num_params The number of parameters to pass | 143 * @param num_params The number of parameters to pass |
160 * @param params Array of @c GParameter to pass | 144 * @param params Array of @c GParameter to pass |
161 * | |
162 * @since 2.8.0 | |
163 */ | 145 */ |
164 void purple_media_set_params(PurpleMedia *media, | 146 void purple_media_set_params(PurpleMedia *media, |
165 guint num_params, GParameter *params); | 147 guint num_params, GParameter *params); |
166 | 148 |
167 /** | 149 /** |
170 * The list is owned by the @c PurpleMedia internals and should NOT be freed. | 152 * The list is owned by the @c PurpleMedia internals and should NOT be freed. |
171 * | 153 * |
172 * @param media The media object | 154 * @param media The media object |
173 * | 155 * |
174 * @return NULL-terminated array of names of supported parameters. | 156 * @return NULL-terminated array of names of supported parameters. |
175 * | |
176 * @since 2.8.0 | |
177 */ | 157 */ |
178 const gchar **purple_media_get_available_params(PurpleMedia *media); | 158 const gchar **purple_media_get_available_params(PurpleMedia *media); |
179 | 159 |
180 /** | 160 /** |
181 * Checks if given optional parameter is supported by the media backend. | 161 * Checks if given optional parameter is supported by the media backend. |
182 * | 162 * |
183 * @param media The media object | 163 * @param media The media object |
184 * @param param name of parameter | 164 * @param param name of parameter |
185 * | 165 * |
186 * @return @c TRUE if backend recognizes the parameter, @c FALSE otherwise. | 166 * @return @c TRUE if backend recognizes the parameter, @c FALSE otherwise. |
187 * | |
188 * @since 2.8.0 | |
189 */ | 167 */ |
190 gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param); | 168 gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param); |
191 | 169 |
192 /** | 170 /** |
193 * Adds a stream to a session. | 171 * Adds a stream to a session. |
203 * @param transmitter The transmitter to use for the stream. | 181 * @param transmitter The transmitter to use for the stream. |
204 * @param num_params The number of parameters to pass to Farsight. | 182 * @param num_params The number of parameters to pass to Farsight. |
205 * @param params The parameters to pass to Farsight. | 183 * @param params The parameters to pass to Farsight. |
206 * | 184 * |
207 * @return @c TRUE The stream was added successfully, @c FALSE otherwise. | 185 * @return @c TRUE The stream was added successfully, @c FALSE otherwise. |
208 * | |
209 * @since 2.6.0 | |
210 */ | 186 */ |
211 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id, | 187 gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id, |
212 const gchar *who, PurpleMediaSessionType type, | 188 const gchar *who, PurpleMediaSessionType type, |
213 gboolean initiator, const gchar *transmitter, | 189 gboolean initiator, const gchar *transmitter, |
214 guint num_params, GParameter *params); | 190 guint num_params, GParameter *params); |
218 * | 194 * |
219 * @param media The media object to find the session in. | 195 * @param media The media object to find the session in. |
220 * @param sess_id The session id of the session to get the type from. | 196 * @param sess_id The session id of the session to get the type from. |
221 * | 197 * |
222 * @return The retreived session type. | 198 * @return The retreived session type. |
223 * | |
224 * @since 2.6.0 | |
225 */ | 199 */ |
226 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id); | 200 PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id); |
227 | 201 |
228 /** | 202 /** |
229 * Gets the PurpleMediaManager this media session is a part of. | 203 * Gets the PurpleMediaManager this media session is a part of. |
230 * | 204 * |
231 * @param media The media object to get the manager instance from. | 205 * @param media The media object to get the manager instance from. |
232 * | 206 * |
233 * @return The PurpleMediaManager instance retrieved. | 207 * @return The PurpleMediaManager instance retrieved. |
234 * | |
235 * @since 2.6.0 | |
236 */ | 208 */ |
237 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media); | 209 struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media); |
238 | 210 |
239 /** | 211 /** |
240 * Gets the codecs from a session. | 212 * Gets the codecs from a session. |
241 * | 213 * |
242 * @param media The media object to find the session in. | 214 * @param media The media object to find the session in. |
243 * @param sess_id The session id of the session to get the codecs from. | 215 * @param sess_id The session id of the session to get the codecs from. |
244 * | 216 * |
245 * @return The retreieved codecs. | 217 * @return The retreieved codecs. |
246 * | |
247 * @since 2.6.0 | |
248 */ | 218 */ |
249 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id); | 219 GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id); |
250 | 220 |
251 /** | 221 /** |
252 * Adds remote candidates to the stream. | 222 * Adds remote candidates to the stream. |
253 * | 223 * |
254 * @param media The media object to find the session in. | 224 * @param media The media object to find the session in. |
255 * @param sess_id The session id of the session find the stream in. | 225 * @param sess_id The session id of the session find the stream in. |
256 * @param participant The name of the remote user to add the candidates for. | 226 * @param participant The name of the remote user to add the candidates for. |
257 * @param remote_candidates The remote candidates to add. | 227 * @param remote_candidates The remote candidates to add. |
258 * | |
259 * @since 2.6.0 | |
260 */ | 228 */ |
261 void purple_media_add_remote_candidates(PurpleMedia *media, | 229 void purple_media_add_remote_candidates(PurpleMedia *media, |
262 const gchar *sess_id, | 230 const gchar *sess_id, |
263 const gchar *participant, | 231 const gchar *participant, |
264 GList *remote_candidates); | 232 GList *remote_candidates); |
267 * Gets the local candidates from a stream. | 235 * Gets the local candidates from a stream. |
268 * | 236 * |
269 * @param media The media object to find the session in. | 237 * @param media The media object to find the session in. |
270 * @param sess_id The session id of the session to find the stream in. | 238 * @param sess_id The session id of the session to find the stream in. |
271 * @param participant The name of the remote user to get the candidates from. | 239 * @param participant The name of the remote user to get the candidates from. |
272 * | |
273 * @since 2.6.0 | |
274 */ | 240 */ |
275 GList *purple_media_get_local_candidates(PurpleMedia *media, | 241 GList *purple_media_get_local_candidates(PurpleMedia *media, |
276 const gchar *sess_id, | 242 const gchar *sess_id, |
277 const gchar *participant); | 243 const gchar *participant); |
278 | 244 |
283 * @param sess_id The session id of the session to find the stream in. | 249 * @param sess_id The session id of the session to find the stream in. |
284 * @param participant The name of the remote user to get the active candidate | 250 * @param participant The name of the remote user to get the active candidate |
285 * from. | 251 * from. |
286 * | 252 * |
287 * @return The active candidates retrieved. | 253 * @return The active candidates retrieved. |
288 * | |
289 * @since 2.8.0 | |
290 */ | 254 */ |
291 GList *purple_media_get_active_local_candidates(PurpleMedia *media, | 255 GList *purple_media_get_active_local_candidates(PurpleMedia *media, |
292 const gchar *sess_id, const gchar *participant); | 256 const gchar *sess_id, const gchar *participant); |
293 | 257 |
294 /** | 258 /** |
298 * @param sess_id The session id of the session to find the stream in. | 262 * @param sess_id The session id of the session to find the stream in. |
299 * @param participant The name of the remote user to get the remote candidate | 263 * @param participant The name of the remote user to get the remote candidate |
300 * from. | 264 * from. |
301 * | 265 * |
302 * @return The remote candidates retrieved. | 266 * @return The remote candidates retrieved. |
303 * | |
304 * @since 2.8.0 | |
305 */ | 267 */ |
306 GList *purple_media_get_active_remote_candidates(PurpleMedia *media, | 268 GList *purple_media_get_active_remote_candidates(PurpleMedia *media, |
307 const gchar *sess_id, const gchar *participant); | 269 const gchar *sess_id, const gchar *participant); |
308 | 270 |
309 /** | 271 /** |
313 * @param sess_id The session id of the session find the stream in. | 275 * @param sess_id The session id of the session find the stream in. |
314 * @param participant The name of the remote user to set the candidates from. | 276 * @param participant The name of the remote user to set the candidates from. |
315 * @param codecs The list of remote codecs to set. | 277 * @param codecs The list of remote codecs to set. |
316 * | 278 * |
317 * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise. | 279 * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise. |
318 * | |
319 * @since 2.6.0 | |
320 */ | 280 */ |
321 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id, | 281 gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id, |
322 const gchar *participant, GList *codecs); | 282 const gchar *participant, GList *codecs); |
323 | 283 |
324 /** | 284 /** |
327 * @param media The media object to find the remote user in. | 287 * @param media The media object to find the remote user in. |
328 * @param session_id The session id of the session to check. | 288 * @param session_id The session id of the session to check. |
329 * @param participant The remote user to check for. | 289 * @param participant The remote user to check for. |
330 * | 290 * |
331 * @return @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise. | 291 * @return @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise. |
332 * | |
333 * @since 2.6.0 | |
334 */ | 292 */ |
335 gboolean purple_media_candidates_prepared(PurpleMedia *media, | 293 gboolean purple_media_candidates_prepared(PurpleMedia *media, |
336 const gchar *session_id, const gchar *participant); | 294 const gchar *session_id, const gchar *participant); |
337 | 295 |
338 /** | 296 /** |
341 * @param media The media object to find the session in. | 299 * @param media The media object to find the session in. |
342 * @param sess_id The session id of the session to set the codec for. | 300 * @param sess_id The session id of the session to set the codec for. |
343 * @param codec The codec to set the session to stream. | 301 * @param codec The codec to set the session to stream. |
344 * | 302 * |
345 * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise. | 303 * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise. |
346 * | |
347 * @since 2.6.0 | |
348 */ | 304 */ |
349 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec); | 305 gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec); |
350 | 306 |
351 /** | 307 /** |
352 * Gets whether a session's codecs are ready to be used. | 308 * Gets whether a session's codecs are ready to be used. |
353 * | 309 * |
354 * @param media The media object to find the session in. | 310 * @param media The media object to find the session in. |
355 * @param sess_id The session id of the session to check. | 311 * @param sess_id The session id of the session to check. |
356 * | 312 * |
357 * @return @c TRUE The codecs are ready, or @c FALSE otherwise. | 313 * @return @c TRUE The codecs are ready, or @c FALSE otherwise. |
358 * | |
359 * @since 2.6.0 | |
360 */ | 314 */ |
361 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id); | 315 gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id); |
362 | 316 |
363 /** | 317 /** |
364 * Gets whether the local user is the conference/session/stream's initiator. | 318 * Gets whether the local user is the conference/session/stream's initiator. |
366 * @param media The media instance to find the session in. | 320 * @param media The media instance to find the session in. |
367 * @param sess_id The session id of the session to check. | 321 * @param sess_id The session id of the session to check. |
368 * @param participant The participant of the stream to check. | 322 * @param participant The participant of the stream to check. |
369 * | 323 * |
370 * @return TRUE if the local user is the stream's initator, else FALSE. | 324 * @return TRUE if the local user is the stream's initator, else FALSE. |
371 * | |
372 * @since 2.6.0 | |
373 */ | 325 */ |
374 gboolean purple_media_is_initiator(PurpleMedia *media, | 326 gboolean purple_media_is_initiator(PurpleMedia *media, |
375 const gchar *sess_id, const gchar *participant); | 327 const gchar *sess_id, const gchar *participant); |
376 | 328 |
377 /** | 329 /** |
380 * @param media The media object to find the session in. | 332 * @param media The media object to find the session in. |
381 * @param sess_id The session id of the session to check. | 333 * @param sess_id The session id of the session to check. |
382 * @param participant The participant to check. | 334 * @param participant The participant to check. |
383 * | 335 * |
384 * @return @c TRUE The selected streams have been accepted, or @c FALSE otherwise. | 336 * @return @c TRUE The selected streams have been accepted, or @c FALSE otherwise. |
385 * | |
386 * @since 2.6.0 | |
387 */ | 337 */ |
388 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id, | 338 gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id, |
389 const gchar *participant); | 339 const gchar *participant); |
390 | 340 |
391 /** | 341 /** |
392 * Sets the input volume of all the selected sessions. | 342 * Sets the input volume of all the selected sessions. |
393 * | 343 * |
394 * @param media The media object the sessions are in. | 344 * @param media The media object the sessions are in. |
395 * @param session_id The session to select (if any). | 345 * @param session_id The session to select (if any). |
396 * @param level The level to set the volume to. | 346 * @param level The level to set the volume to. |
397 * | |
398 * @since 2.6.0 | |
399 */ | 347 */ |
400 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level); | 348 void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level); |
401 | 349 |
402 /** | 350 /** |
403 * Sets the output volume of all the selected streams. | 351 * Sets the output volume of all the selected streams. |
404 * | 352 * |
405 * @param media The media object the streams are in. | 353 * @param media The media object the streams are in. |
406 * @param session_id The session to limit the streams to (if any). | 354 * @param session_id The session to limit the streams to (if any). |
407 * @param participant The participant to limit the streams to (if any). | 355 * @param participant The participant to limit the streams to (if any). |
408 * @param level The level to set the volume to. | 356 * @param level The level to set the volume to. |
409 * | |
410 * @since 2.6.0 | |
411 */ | 357 */ |
412 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id, | 358 void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id, |
413 const gchar *participant, double level); | 359 const gchar *participant, double level); |
414 | 360 |
415 /** | 361 /** |
419 * @param session_id The session to set the output window on. | 365 * @param session_id The session to set the output window on. |
420 * @param participant Optionally, the participant to set the output window on. | 366 * @param participant Optionally, the participant to set the output window on. |
421 * @param window_id The window id use for embedding the video in. | 367 * @param window_id The window id use for embedding the video in. |
422 * | 368 * |
423 * @return An id to reference the output window. | 369 * @return An id to reference the output window. |
424 * | |
425 * @since 2.6.0 | |
426 */ | 370 */ |
427 gulong purple_media_set_output_window(PurpleMedia *media, | 371 gulong purple_media_set_output_window(PurpleMedia *media, |
428 const gchar *session_id, const gchar *participant, | 372 const gchar *session_id, const gchar *participant, |
429 gulong window_id); | 373 gulong window_id); |
430 | 374 |
431 /** | 375 /** |
432 * Removes all output windows from a given media session. | 376 * Removes all output windows from a given media session. |
433 * | 377 * |
434 * @param media The instance to remove all output windows from. | 378 * @param media The instance to remove all output windows from. |
435 * | |
436 * @since 2.6.0 | |
437 */ | 379 */ |
438 void purple_media_remove_output_windows(PurpleMedia *media); | 380 void purple_media_remove_output_windows(PurpleMedia *media); |
439 | 381 |
440 #ifdef __cplusplus | 382 #ifdef __cplusplus |
441 } | 383 } |