Mercurial > pidgin3 / file comparison

comparison: libpurple/network.h

libpurple/network.h

branch
soc.2013.gobjectification.plugins
changeset 37017
8e2b68c79fa1
parent 36637
9b0109ae118d
child 37021
04c99b24db84
equal deleted inserted replaced
37016:48f85579cc4c 37017:8e2b68c79fa1
43 * Sets the IP address of the local system in preferences. This 43 * Sets the IP address of the local system in preferences. This
44 * is the IP address that should be used for incoming connections 44 * is the IP address that should be used for incoming connections
45 * (file transfer, direct IM, etc.) and should therefore be 45 * (file transfer, direct IM, etc.) and should therefore be
46 * publicly accessible. 46 * publicly accessible.
47 * 47 *
48 * @param ip The local IP address. 48 * @ip: The local IP address.
49 */ 49 */
50 void purple_network_set_public_ip(const char *ip); 50 void purple_network_set_public_ip(const char *ip);
51 51
52 /** 52 /**
53 * Returns the IP address of the local system set in preferences. 53 * Returns the IP address of the local system set in preferences.
54 * 54 *
55 * This returns the value set via purple_network_set_public_ip(). 55 * This returns the value set via purple_network_set_public_ip().
56 * You probably want to use purple_network_get_my_ip() instead. 56 * You probably want to use purple_network_get_my_ip() instead.
57 * 57 *
58 * @return The local IP address set in preferences. 58 * Returns: The local IP address set in preferences.
59 */ 59 */
60 const char *purple_network_get_public_ip(void); 60 const char *purple_network_get_public_ip(void);
61 61
62 /** 62 /**
63 * Returns the IP address of the local system. 63 * Returns the IP address of the local system.
66 * 66 *
67 * @note The returned string is a pointer to a static buffer. If this 67 * @note The returned string is a pointer to a static buffer. If this
68 * function is called twice, it may be important to make a copy 68 * function is called twice, it may be important to make a copy
69 * of the returned string. 69 * of the returned string.
70 * 70 *
71 * @param fd The fd to use to help figure out the IP, or else -1. 71 * @fd: The fd to use to help figure out the IP, or else -1.
72 * @return The local IP address. 72 * Returns: The local IP address.
73 */ 73 */
74 const char *purple_network_get_local_system_ip(int fd); 74 const char *purple_network_get_local_system_ip(int fd);
75 75
76 /** 76 /**
77 * Returns all IP addresses of the local system. 77 * Returns all IP addresses of the local system.
78 * 78 *
79 * @note The caller must free this list. If libpurple was built with 79 * @note The caller must free this list. If libpurple was built with
80 * support for it, this function also enumerates IPv6 addresses. 80 * support for it, this function also enumerates IPv6 addresses.
81 * 81 *
82 * @return A list of local IP addresses. 82 * Returns: A list of local IP addresses.
83 */ 83 */
84 GList *purple_network_get_all_local_system_ips(void); 84 GList *purple_network_get_all_local_system_ips(void);
85 85
86 /** 86 /**
87 * Returns the IP address that should be used anywhere a 87 * Returns the IP address that should be used anywhere a
95 * 95 *
96 * @note The returned string is a pointer to a static buffer. If this 96 * @note The returned string is a pointer to a static buffer. If this
97 * function is called twice, it may be important to make a copy 97 * function is called twice, it may be important to make a copy
98 * of the returned string. 98 * of the returned string.
99 * 99 *
100 * @param fd The fd to use to help figure out the IP, or -1. 100 * @fd: The fd to use to help figure out the IP, or -1.
101 * @return The local IP address to be used. 101 * Returns: The local IP address to be used.
102 */ 102 */
103 const char *purple_network_get_my_ip(int fd); 103 const char *purple_network_get_my_ip(int fd);
104 104
105 /** 105 /**
106 * Attempts to open a listening port ONLY on the specified port number. 106 * Attempts to open a listening port ONLY on the specified port number.
117 * 117 *
118 * Libpurple does not currently do any port mapping (stateful firewall hole 118 * Libpurple does not currently do any port mapping (stateful firewall hole
119 * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped 119 * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
120 * addresses, a mapping is done). 120 * addresses, a mapping is done).
121 * 121 *
122 * @param port The port number to bind to. Must be greater than 0. 122 * @port: The port number to bind to. Must be greater than 0.
123 * @param socket_family The protocol family of the socket. This should be 123 * @socket_family: The protocol family of the socket. This should be
124 * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets 124 * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets
125 * may or may not be able to accept IPv4 connections 125 * may or may not be able to accept IPv4 connections
126 * based on the system configuration (use 126 * based on the system configuration (use
127 * purple_socket_speaks_ipv4 to check). If an IPv6 127 * purple_socket_speaks_ipv4 to check). If an IPv6
128 * socket doesn't accept V4-mapped addresses, you will 128 * socket doesn't accept V4-mapped addresses, you will
129 * need a second listener to support both v4 and v6. 129 * need a second listener to support both v4 and v6.
130 * @param socket_type The type of socket to open for listening. 130 * @socket_type: The type of socket to open for listening.
131 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. 131 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
132 * @param map_external Should the open port be mapped externally using 132 * @map_external: Should the open port be mapped externally using
133 * NAT-PNP or UPnP? (default should be TRUE) 133 * NAT-PNP or UPnP? (default should be TRUE)
134 * @param cb The callback to be invoked when the port to listen on is available. 134 * @cb: The callback to be invoked when the port to listen on is available.
135 * The file descriptor of the listening socket will be specified in 135 * The file descriptor of the listening socket will be specified in
136 * this callback, or -1 if no socket could be established. 136 * this callback, or -1 if no socket could be established.
137 * @param cb_data extra data to be returned when cb is called 137 * @cb_data: extra data to be returned when cb is called
138 * 138 *
139 * @return A pointer to a data structure that can be used to cancel 139 * Returns: A pointer to a data structure that can be used to cancel
140 * the pending listener, or NULL if unable to obtain a local 140 * the pending listener, or NULL if unable to obtain a local
141 * socket to listen on. 141 * socket to listen on.
142 */ 142 */
143 PurpleNetworkListenData *purple_network_listen(unsigned short port, 143 PurpleNetworkListenData *purple_network_listen(unsigned short port,
144 int socket_family, int socket_type, gboolean map_external, 144 int socket_family, int socket_type, gboolean map_external,
160 * 160 *
161 * Libpurple does not currently do any port mapping (stateful firewall hole 161 * Libpurple does not currently do any port mapping (stateful firewall hole
162 * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped 162 * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
163 * addresses, a mapping is done). 163 * addresses, a mapping is done).
164 * 164 *
165 * @param start The port number to bind to, or 0 to pick a random port. 165 * @start: The port number to bind to, or 0 to pick a random port.
166 * Users are allowed to override this arg in prefs. 166 * Users are allowed to override this arg in prefs.
167 * @param end The highest possible port in the range of ports to listen on, 167 * @end: The highest possible port in the range of ports to listen on,
168 * or 0 to pick a random port. Users are allowed to override this 168 * or 0 to pick a random port. Users are allowed to override this
169 * arg in prefs. 169 * arg in prefs.
170 * @param socket_family The protocol family of the socket. This should be 170 * @socket_family: The protocol family of the socket. This should be
171 * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets 171 * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets
172 * may or may not be able to accept IPv4 connections 172 * may or may not be able to accept IPv4 connections
173 * based on the system configuration (use 173 * based on the system configuration (use
174 * purple_socket_speaks_ipv4 to check). If an IPv6 174 * purple_socket_speaks_ipv4 to check). If an IPv6
175 * socket doesn't accept V4-mapped addresses, you will 175 * socket doesn't accept V4-mapped addresses, you will
176 * need a second listener to support both v4 and v6. 176 * need a second listener to support both v4 and v6.
177 * @param socket_type The type of socket to open for listening. 177 * @socket_type: The type of socket to open for listening.
178 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. 178 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
179 * @param map_external Should the open port be mapped externally using 179 * @map_external: Should the open port be mapped externally using
180 * NAT-PNP or UPnP? (default should be TRUE) 180 * NAT-PNP or UPnP? (default should be TRUE)
181 * @param cb The callback to be invoked when the port to listen on is available. 181 * @cb: The callback to be invoked when the port to listen on is available.
182 * The file descriptor of the listening socket will be specified in 182 * The file descriptor of the listening socket will be specified in
183 * this callback, or -1 if no socket could be established. 183 * this callback, or -1 if no socket could be established.
184 * @param cb_data extra data to be returned when cb is called 184 * @cb_data: extra data to be returned when cb is called
185 * 185 *
186 * @return A pointer to a data structure that can be used to cancel 186 * Returns: A pointer to a data structure that can be used to cancel
187 * the pending listener, or NULL if unable to obtain a local 187 * the pending listener, or NULL if unable to obtain a local
188 * socket to listen on. 188 * socket to listen on.
189 */ 189 */
190 PurpleNetworkListenData *purple_network_listen_range( 190 PurpleNetworkListenData *purple_network_listen_range(
191 unsigned short start, unsigned short end, int socket_family, 191 unsigned short start, unsigned short end, int socket_family,
195 /** 195 /**
196 * This can be used to cancel any in-progress listener connection 196 * This can be used to cancel any in-progress listener connection
197 * by passing in the return value from either purple_network_listen() 197 * by passing in the return value from either purple_network_listen()
198 * or purple_network_listen_range(). 198 * or purple_network_listen_range().
199 * 199 *
200 * @param listen_data This listener attempt will be cancelled and 200 * @listen_data: This listener attempt will be cancelled and
201 * the struct will be freed. 201 * the struct will be freed.
202 */ 202 */
203 void purple_network_listen_cancel(PurpleNetworkListenData *listen_data); 203 void purple_network_listen_cancel(PurpleNetworkListenData *listen_data);
204 204
205 /** 205 /**
206 * Gets a port number from a file descriptor. 206 * Gets a port number from a file descriptor.
207 * 207 *
208 * @param fd The file descriptor. This should be a tcp socket. The current 208 * @fd: The file descriptor. This should be a tcp socket. The current
209 * implementation probably dies on anything but IPv4. Perhaps this 209 * implementation probably dies on anything but IPv4. Perhaps this
210 * possible bug will inspire new and valuable contributors to Purple. 210 * possible bug will inspire new and valuable contributors to Purple.
211 * @return The port number, in host byte order. 211 * Returns: The port number, in host byte order.
212 */ 212 */
213 unsigned short purple_network_get_port_from_fd(int fd); 213 unsigned short purple_network_get_port_from_fd(int fd);
214 214
215 /** 215 /**
216 * Detects if there is an available network connection. 216 * Detects if there is an available network connection.
217 * 217 *
218 * @return TRUE if the network is available 218 * Returns: TRUE if the network is available
219 */ 219 */
220 gboolean purple_network_is_available(void); 220 gboolean purple_network_is_available(void);
221 221
222 /** 222 /**
223 * Makes purple_network_is_available() always return @c TRUE. 223 * Makes purple_network_is_available() always return @c TRUE.
229 void purple_network_force_online(void); 229 void purple_network_force_online(void);
230 230
231 /** 231 /**
232 * Get the handle for the network system 232 * Get the handle for the network system
233 * 233 *
234 * @return the handle to the network system 234 * Returns: the handle to the network system
235 */ 235 */
236 void *purple_network_get_handle(void); 236 void *purple_network_get_handle(void);
237 237
238 /** 238 /**
239 * Update the STUN server IP given the host name 239 * Update the STUN server IP given the host name
240 * Will result in a DNS query being executed asynchronous 240 * Will result in a DNS query being executed asynchronous
241 * 241 *
242 * @param stun_server The host name of the STUN server to set 242 * @stun_server: The host name of the STUN server to set
243 */ 243 */
244 void purple_network_set_stun_server(const gchar *stun_server); 244 void purple_network_set_stun_server(const gchar *stun_server);
245 245
246 /** 246 /**
247 * Get the IP address of the STUN server as a string representation 247 * Get the IP address of the STUN server as a string representation
248 * 248 *
249 * @return the IP address 249 * Returns: the IP address
250 */ 250 */
251 const gchar *purple_network_get_stun_ip(void); 251 const gchar *purple_network_get_stun_ip(void);
252 252
253 /** 253 /**
254 * Update the TURN server IP given the host name 254 * Update the TURN server IP given the host name
255 * Will result in a DNS query being executed asynchronous 255 * Will result in a DNS query being executed asynchronous
256 * 256 *
257 * @param turn_server The host name of the TURN server to set 257 * @turn_server: The host name of the TURN server to set
258 */ 258 */
259 void purple_network_set_turn_server(const gchar *turn_server); 259 void purple_network_set_turn_server(const gchar *turn_server);
260 260
261 /** 261 /**
262 * Get the IP address of the TURN server as a string representation 262 * Get the IP address of the TURN server as a string representation
263 * 263 *
264 * @return the IP address 264 * Returns: the IP address
265 */ 265 */
266 const gchar *purple_network_get_turn_ip(void); 266 const gchar *purple_network_get_turn_ip(void);
267 267
268 /** 268 /**
269 * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket 269 * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
270 * 270 *
271 * @param fd Socket to remove the port mapping for 271 * @fd: Socket to remove the port mapping for
272 */ 272 */
273 void purple_network_remove_port_mapping(gint fd); 273 void purple_network_remove_port_mapping(gint fd);
274 274
275 /** 275 /**
276 * Convert a UTF-8 domain name to ASCII in accordance with the IDNA 276 * Convert a UTF-8 domain name to ASCII in accordance with the IDNA
280 * Because this function is used by DNS resolver child/threads, it uses no 280 * Because this function is used by DNS resolver child/threads, it uses no
281 * other libpurple API and is threadsafe. 281 * other libpurple API and is threadsafe.
282 * 282 *
283 * In general, a buffer of about 512 bytes is the appropriate size to use. 283 * In general, a buffer of about 512 bytes is the appropriate size to use.
284 * 284 *
285 * @param in The hostname to be converted. 285 * @in: The hostname to be converted.
286 * @param out The output buffer where an allocated string will be returned. 286 * @out: The output buffer where an allocated string will be returned.
287 * The caller is responsible for freeing this. 287 * The caller is responsible for freeing this.
288 * @returns 0 on success, -1 if the out is NULL, or an error code 288 * Returns:s 0 on success, -1 if the out is NULL, or an error code
289 * that currently corresponds to the Idna_rc enum in libidn. 289 * that currently corresponds to the Idna_rc enum in libidn.
290 */ 290 */
291 int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out); 291 int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
292 292
293 /** 293 /**

Mercurial Repository: pidgin3

mercurial