libpurple/media/candidate.h

   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