comparison libpurple/media/backend-iface.h @ 29243:510f4c50b3d7

Add documentation to backend-iface.h.
author maiku@pidgin.im
date Fri, 13 Nov 2009 21:46:43 +0000
parents f351e87b7af0
children 44f53d3fc54f
comparison
equal deleted inserted replaced
29242:ad765bf47e23 29243:510f4c50b3d7
37 #define PURPLE_TYPE_MEDIA_BACKEND (purple_media_backend_get_type()) 37 #define PURPLE_TYPE_MEDIA_BACKEND (purple_media_backend_get_type())
38 #define PURPLE_IS_MEDIA_BACKEND(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_BACKEND)) 38 #define PURPLE_IS_MEDIA_BACKEND(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_BACKEND))
39 #define PURPLE_MEDIA_BACKEND(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackend)) 39 #define PURPLE_MEDIA_BACKEND(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackend))
40 #define PURPLE_MEDIA_BACKEND_GET_INTERFACE(inst)(G_TYPE_INSTANCE_GET_INTERFACE((inst), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackendIface)) 40 #define PURPLE_MEDIA_BACKEND_GET_INTERFACE(inst)(G_TYPE_INSTANCE_GET_INTERFACE((inst), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackendIface))
41 41
42 /** A placeholder to represent any media backend */
42 typedef struct _PurpleMediaBackend PurpleMediaBackend; 43 typedef struct _PurpleMediaBackend PurpleMediaBackend;
44 /** A structure to derive media backends from. */
43 typedef struct _PurpleMediaBackendIface PurpleMediaBackendIface; 45 typedef struct _PurpleMediaBackendIface PurpleMediaBackendIface;
44 46
45 struct _PurpleMediaBackendIface 47 struct _PurpleMediaBackendIface
46 { 48 {
47 GTypeInterface parent_iface; 49 GTypeInterface parent_iface; /**< The parent iface class */
48 50
51 /** Implementable functions called with purple_media_backend_* */
49 gboolean (*add_stream) (PurpleMediaBackend *self, 52 gboolean (*add_stream) (PurpleMediaBackend *self,
50 const gchar *sess_id, const gchar *who, 53 const gchar *sess_id, const gchar *who,
51 PurpleMediaSessionType type, gboolean initiator, 54 PurpleMediaSessionType type, gboolean initiator,
52 const gchar *transmitter, 55 const gchar *transmitter,
53 guint num_params, GParameter *params); 56 guint num_params, GParameter *params);
65 GList *codecs); 68 GList *codecs);
66 gboolean (*set_send_codec) (PurpleMediaBackend *self, 69 gboolean (*set_send_codec) (PurpleMediaBackend *self,
67 const gchar *sess_id, PurpleMediaCodec *codec); 70 const gchar *sess_id, PurpleMediaCodec *codec);
68 }; 71 };
69 72
73 /**
74 * Gets the media backend's GType.
75 *
76 * @return The media backend's GType.
77 *
78 * @since 2.7.0
79 */
70 GType purple_media_backend_get_type(void); 80 GType purple_media_backend_get_type(void);
71 81
82 /**
83 * Creates and adds a stream to the media backend.
84 *
85 * @param self The backend to add the stream to.
86 * @param sess_id The session id of the stream to add.
87 * @param who The remote participant of the stream to add.
88 * @param type The media type and direction of the stream to add.
89 * @param initiator True if the local user initiated the stream.
90 * @param transmitter The string id of the tranmsitter to use.
91 * @param num_params The number of parameters in the param parameter.
92 * @param params The additional parameters to pass when creating the stream.
93 *
94 * @return True if the stream was successfully created, othewise False.
95 *
96 * @since 2.7.0
97 */
72 gboolean purple_media_backend_add_stream(PurpleMediaBackend *self, 98 gboolean purple_media_backend_add_stream(PurpleMediaBackend *self,
73 const gchar *sess_id, const gchar *who, 99 const gchar *sess_id, const gchar *who,
74 PurpleMediaSessionType type, gboolean initiator, 100 PurpleMediaSessionType type, gboolean initiator,
75 const gchar *transmitter, 101 const gchar *transmitter,
76 guint num_params, GParameter *params); 102 guint num_params, GParameter *params);
103
104 /**
105 * Add remote candidates to a stream.
106 *
107 * @param self The backend the stream is in.
108 * @param sess_id The session id associated with the stream.
109 * @param participant The participant associated with the stream.
110 * @param remote_candidates The list of remote candidates to add.
111 *
112 * @since 2.7.0
113 */
77 void purple_media_backend_add_remote_candidates(PurpleMediaBackend *self, 114 void purple_media_backend_add_remote_candidates(PurpleMediaBackend *self,
78 const gchar *sess_id, const gchar *participant, 115 const gchar *sess_id, const gchar *participant,
79 GList *remote_candidates); 116 GList *remote_candidates);
117
118 /**
119 * Get whether or not a session's codecs are ready.
120 *
121 * A codec is ready if all of the attributes and additional
122 * parameters have been collected.
123 *
124 * @param self The media backend the session is in.
125 * @param sess_id The session id of the session to check.
126 *
127 * @return True if the codecs are ready, otherwise False.
128 *
129 * @since 2.7.0
130 */
80 gboolean purple_media_backend_codecs_ready(PurpleMediaBackend *self, 131 gboolean purple_media_backend_codecs_ready(PurpleMediaBackend *self,
81 const gchar *sess_id); 132 const gchar *sess_id);
133
134 /**
135 * Gets the codec intersection list for a session.
136 *
137 * The intersection list consists of all codecs that are compatible
138 * between the local and remote software.
139 *
140 * @param self The media backend the session is in.
141 * @param sess_id The session id of the session to use.
142 *
143 * @return The codec intersection list.
144 *
145 * @since 2.7.0
146 */
82 GList *purple_media_backend_get_codecs(PurpleMediaBackend *self, 147 GList *purple_media_backend_get_codecs(PurpleMediaBackend *self,
83 const gchar *sess_id); 148 const gchar *sess_id);
149
150 /**
151 * Gets the list of local candidates for a stream.
152 *
153 * @param self The media backend the stream is in.
154 * @param sess_id The session id associated with the stream.
155 * @param particilant The participant associated with the stream.
156 *
157 * @return The list of local candidates.
158 *
159 * @since 2.7.0
160 */
84 GList *purple_media_backend_get_local_candidates(PurpleMediaBackend *self, 161 GList *purple_media_backend_get_local_candidates(PurpleMediaBackend *self,
85 const gchar *sess_id, const gchar *participant); 162 const gchar *sess_id, const gchar *participant);
163
164 /**
165 * Sets the remote codecs on a stream.
166 *
167 * @param self The media backend the stream is in.
168 * @param sess_id The session id the stream is associated with.
169 * @param participant The participant the stream is associated with.
170 * @param codecs The list of remote codecs to set.
171 *
172 * @return True if the remote codecs were set successfully, otherwise False.
173 *
174 * @since 2.7.0
175 */
86 gboolean purple_media_backend_set_remote_codecs(PurpleMediaBackend *self, 176 gboolean purple_media_backend_set_remote_codecs(PurpleMediaBackend *self,
87 const gchar *sess_id, const gchar *participant, 177 const gchar *sess_id, const gchar *participant,
88 GList *codecs); 178 GList *codecs);
179
180 /**
181 * Sets which codec format to send media content in for a session.
182 *
183 * @param self The media backend the session is in.
184 * @param sess_id The session id of the session to set the codec for.
185 * @param codec The codec to set.
186 *
187 * @return True if set successfully, otherwise False.
188 *
189 * @since 2.7.0
190 */
89 gboolean purple_media_backend_set_send_codec(PurpleMediaBackend *self, 191 gboolean purple_media_backend_set_send_codec(PurpleMediaBackend *self,
90 const gchar *sess_id, PurpleMediaCodec *codec); 192 const gchar *sess_id, PurpleMediaCodec *codec);
91 193
92 G_END_DECLS 194 G_END_DECLS
93 195