1 /** 2 * @file candidate.h Candidate for Media API 3 * @ingroup core 4 */ 5 6 /* purple 7 * 8 * Purple is the legal property of its developers, whose names are too numerous 9 * to list here. Please refer to the COPYRIGHT file distributed with this 10 * source distribution. 11 * 12 * This program is free software; you can redistribute it and/or modify 13 * it under the terms of the GNU General Public License as published by 14 * the Free Software Foundation; either version 2 of the License, or 15 * (at your option) any later version. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU General Public License for more details. 21 * 22 * You should have received a copy of the GNU General Public License 23 * along with this program; if not, write to the Free Software 24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 25 */ 26 27 #ifndef _PURPLE_MEDIA_CANDIDATE_H_ 28 #define _PURPLE_MEDIA_CANDIDATE_H_ 29 30 #include "enum-types.h" 31 32 #include <glib-object.h> 33 34 G_BEGIN_DECLS 35 36 #define PURPLE_TYPE_MEDIA_CANDIDATE (purple_media_candidate_get_type()) 37 #define PURPLE_IS_MEDIA_CANDIDATE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_CANDIDATE)) 38 #define PURPLE_IS_MEDIA_CANDIDATE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_CANDIDATE)) 39 #define PURPLE_MEDIA_CANDIDATE(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate)) 40 #define PURPLE_MEDIA_CANDIDATE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate)) 41 #define PURPLE_MEDIA_CANDIDATE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_CANDIDATE, PurpleMediaCandidate)) 42 43 /** An opaque structure representing a network candidate (IP Address and port pair). */ 44 typedef struct _PurpleMediaCandidate PurpleMediaCandidate; 45 46 /** 47 * Gets the type of the media candidate structure. 48 * 49 * @return The media canditate's GType 50 * 51 * @since 2.6.0 52 */ 53 GType purple_media_candidate_get_type(void); 54 55 /** 56 * Creates a PurpleMediaCandidate instance. 57 * 58 * @param foundation The foundation of the candidate. 59 * @param component_id The component this candidate is for. 60 * @param type The type of candidate. 61 * @param proto The protocol this component is for. 62 * @param ip The IP address of this component. 63 * @param port The network port. 64 * 65 * @return The newly created PurpleMediaCandidate instance. 66 * 67 * @since 2.6.0 68 */ 69 PurpleMediaCandidate *purple_media_candidate_new( 70 const gchar *foundation, guint component_id, 71 PurpleMediaCandidateType type, 72 PurpleMediaNetworkProtocol proto, 73 const gchar *ip, guint port); 74 75 /** 76 * Copies a PurpleMediaCandidate. 77 * 78 * @param candidate The candidate to copy. 79 * 80 * @return The copy of the PurpleMediaCandidate. 81 * 82 * @since 2.7.0 83 */ 84 PurpleMediaCandidate *purple_media_candidate_copy( 85 PurpleMediaCandidate *candidate); 86 87 /** 88 * Copies a GList of PurpleMediaCandidate and its contents. 89 * 90 * @param candidates The list of candidates to be copied. 91 * 92 * @return The copy of the GList. 93 * 94 * @since 2.6.0 95 */ 96 GList *purple_media_candidate_list_copy(GList *candidates); 97 98 /** 99 * Frees a GList of PurpleMediaCandidate and its contents. 100 * 101 * @param candidates The list of candidates to be freed. 102 * 103 * @since 2.6.0 104 */ 105 void purple_media_candidate_list_free(GList *candidates); 106 107 /** 108 * Gets the foundation (identifier) from the candidate. 109 * 110 * @param candidate The candidate to get the foundation from. 111 * 112 * @return The foundation. 113 * 114 * @since 2.6.0 115 */ 116 gchar *purple_media_candidate_get_foundation(PurpleMediaCandidate *candidate); 117 118 /** 119 * Gets the component id (rtp or rtcp) 120 * 121 * @param candidate The candidate to get the compnent id from. 122 * 123 * @return The component id. 124 * 125 * @since 2.6.0 126 */ 127 guint purple_media_candidate_get_component_id(PurpleMediaCandidate *candidate); 128 129 /** 130 * Gets the IP address. 131 * 132 * @param candidate The candidate to get the IP address from. 133 * 134 * @return The IP address. 135 * 136 * @since 2.6.0 137 */ 138 gchar *purple_media_candidate_get_ip(PurpleMediaCandidate *candidate); 139 140 /** 141 * Gets the port. 142 * 143 * @param candidate The candidate to get the port from. 144 * 145 * @return The port. 146 * 147 * @since 2.6.0 148 */ 149 guint16 purple_media_candidate_get_port(PurpleMediaCandidate *candidate); 150 151 /** 152 * Gets the base (internal) IP address. 153 * 154 * This can be NULL. 155 * 156 * @param candidate The candidate to get the base IP address from. 157 * 158 * @return The base IP address. 159 * 160 * @since 2.6.0 161 */ 162 gchar *purple_media_candidate_get_base_ip(PurpleMediaCandidate *candidate); 163 164 /** 165 * Gets the base (internal) port. 166 * 167 * Invalid if the base IP is NULL. 168 * 169 * @param candidate The candidate to get the base port. 170 * 171 * @return The base port. 172 * 173 * @since 2.6.0 174 */ 175 guint16 purple_media_candidate_get_base_port(PurpleMediaCandidate *candidate); 176 177 /** 178 * Gets the protocol (TCP or UDP). 179 * 180 * @param candidate The candidate to get the protocol from. 181 * 182 * @return The protocol. 183 * 184 * @since 2.6.0 185 */ 186 PurpleMediaNetworkProtocol purple_media_candidate_get_protocol( 187 PurpleMediaCandidate *candidate); 188 189 /** 190 * Gets the priority. 191 * 192 * @param candidate The candidate to get the priority from. 193 * 194 * @return The priority. 195 * 196 * @since 2.6.0 197 */ 198 guint32 purple_media_candidate_get_priority(PurpleMediaCandidate *candidate); 199 200 /** 201 * Gets the candidate type. 202 * 203 * @param candidate The candidate to get the candidate type from. 204 * 205 * @return The candidate type. 206 * 207 * @since 2.6.0 208 */ 209 PurpleMediaCandidateType purple_media_candidate_get_candidate_type( 210 PurpleMediaCandidate *candidate); 211 212 /** 213 * Gets the username. 214 * 215 * This can be NULL. It depends on the transmission type. 216 * 217 * @param The candidate to get the username from. 218 * 219 * @return The username. 220 * 221 * @since 2.6.0 222 */ 223 gchar *purple_media_candidate_get_username(PurpleMediaCandidate *candidate); 224 225 /** 226 * Gets the password. 227 * 228 * This can be NULL. It depends on the transmission type. 229 * 230 * @param The candidate to get the password from. 231 * 232 * @return The password. 233 * 234 * @since 2.6.0 235 */ 236 gchar *purple_media_candidate_get_password(PurpleMediaCandidate *candidate); 237 238 /** 239 * Gets the TTL. 240 * 241 * @param The candidate to get the TTL from. 242 * 243 * @return The TTL. 244 * 245 * @since 2.6.0 246 */ 247 guint purple_media_candidate_get_ttl(PurpleMediaCandidate *candidate); 248 249 G_END_DECLS 250 251 #endif /* _PURPLE_MEDIA_CANDIDATE_H_ */ 252 253