/soc/2013/ankitkv/gobjectification: 359528e4c828: Convert doxyge...
Ankit Vani
a at nevitus.org
Thu Jan 30 18:51:29 EST 2014
Changeset: 359528e4c828d328a9cf646fbc12e28b25118174
Author: Ankit Vani <a at nevitus.org>
Date: 2014-01-31 05:21 +0530
Branch: soc.2013.gobjectification.gtkdoc
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/359528e4c828
Description:
Convert doxygen comments to gtk-doc format for network.h to proxy.h
diffstat:
libpurple/network.h | 137 ++++++++++++-------
libpurple/notify.h | 342 +++++++++++++++++++++++++++++++-----------------
libpurple/pluginpref.h | 132 ++++++++++++------
libpurple/pounce.h | 192 +++++++++++++++++---------
libpurple/prefs.h | 169 ++++++++++++++++-------
libpurple/presence.h | 149 +++++++++++++--------
libpurple/proxy.h | 142 +++++++++++++-------
7 files changed, 822 insertions(+), 441 deletions(-)
diffs (truncated from 3036 to 300 lines):
diff --git a/libpurple/network.h b/libpurple/network.h
--- a/libpurple/network.h
+++ b/libpurple/network.h
@@ -40,16 +40,19 @@ typedef struct _PurpleNetworkListenData
typedef void (*PurpleNetworkListenCallback) (int listenfd, gpointer data);
/**
+ * purple_network_set_public_ip:
+ * @ip: The local IP address.
+ *
* Sets the IP address of the local system in preferences. This
* is the IP address that should be used for incoming connections
* (file transfer, direct IM, etc.) and should therefore be
* publicly accessible.
- *
- * @ip: The local IP address.
*/
void purple_network_set_public_ip(const char *ip);
/**
+ * purple_network_get_public_ip:
+ *
* Returns the IP address of the local system set in preferences.
*
* This returns the value set via purple_network_set_public_ip().
@@ -60,6 +63,9 @@ void purple_network_set_public_ip(const
const char *purple_network_get_public_ip(void);
/**
+ * purple_network_get_local_system_ip:
+ * @fd: The fd to use to help figure out the IP, or else -1.
+ *
* Returns the IP address of the local system.
*
* You probably want to use purple_network_get_my_ip() instead.
@@ -68,12 +74,13 @@ const char *purple_network_get_public_ip
* function is called twice, it may be important to make a copy
* of the returned string.
*
- * @fd: The fd to use to help figure out the IP, or else -1.
* Returns: The local IP address.
*/
const char *purple_network_get_local_system_ip(int fd);
/**
+ * purple_network_get_all_local_system_ips:
+ *
* Returns all IP addresses of the local system.
*
* Note: The caller must free this list. If libpurple was built with
@@ -84,6 +91,9 @@ const char *purple_network_get_local_sys
GList *purple_network_get_all_local_system_ips(void);
/**
+ * purple_network_get_my_ip:
+ * @fd: The fd to use to help figure out the IP, or -1.
+ *
* Returns the IP address that should be used anywhere a
* public IP addresses is needed (listening for an incoming
* file transfer, etc).
@@ -97,28 +107,12 @@ GList *purple_network_get_all_local_syst
* function is called twice, it may be important to make a copy
* of the returned string.
*
- * @fd: The fd to use to help figure out the IP, or -1.
* Returns: The local IP address to be used.
*/
const char *purple_network_get_my_ip(int fd);
/**
- * Attempts to open a listening port ONLY on the specified port number.
- * You probably want to use purple_network_listen_range() instead of this.
- * This function is useful, for example, if you wanted to write a telnet
- * server as a Purple plugin, and you HAD to listen on port 23. Why anyone
- * would want to do that is beyond me.
- *
- * This opens a listening port. The caller will want to set up a watcher
- * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
- * accept in the watcher callback, and then possibly remove the watcher and
- * close the listening socket, and add a new watcher on the new socket accept
- * returned.
- *
- * Libpurple does not currently do any port mapping (stateful firewall hole
- * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
- * addresses, a mapping is done).
- *
+ * purple_network_listen:
* @port: The port number to bind to. Must be greater than 0.
* @socket_family: The protocol family of the socket. This should be
* AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets
@@ -136,6 +130,22 @@ const char *purple_network_get_my_ip(int
* this callback, or -1 if no socket could be established.
* @cb_data: extra data to be returned when cb is called
*
+ * Attempts to open a listening port ONLY on the specified port number.
+ * You probably want to use purple_network_listen_range() instead of this.
+ * This function is useful, for example, if you wanted to write a telnet
+ * server as a Purple plugin, and you HAD to listen on port 23. Why anyone
+ * would want to do that is beyond me.
+ *
+ * This opens a listening port. The caller will want to set up a watcher
+ * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
+ * accept in the watcher callback, and then possibly remove the watcher and
+ * close the listening socket, and add a new watcher on the new socket accept
+ * returned.
+ *
+ * Libpurple does not currently do any port mapping (stateful firewall hole
+ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
+ * addresses, a mapping is done).
+ *
* Returns: A pointer to a data structure that can be used to cancel
* the pending listener, or NULL if unable to obtain a local
* socket to listen on.
@@ -145,23 +155,7 @@ PurpleNetworkListenData *purple_network_
PurpleNetworkListenCallback cb, gpointer cb_data);
/**
- * Opens a listening port selected from a range of ports. The range of
- * ports used is chosen in the following manner:
- * If a range is specified in preferences, these values are used.
- * If a non-0 values are passed to the function as parameters, these
- * values are used.
- * Otherwise a port is chosen at random by the operating system.
- *
- * This opens a listening port. The caller will want to set up a watcher
- * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
- * accept in the watcher callback, and then possibly remove the watcher and close
- * the listening socket, and add a new watcher on the new socket accept
- * returned.
- *
- * Libpurple does not currently do any port mapping (stateful firewall hole
- * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
- * addresses, a mapping is done).
- *
+ * purple_network_listen_range:
* @start: The port number to bind to, or 0 to pick a random port.
* Users are allowed to override this arg in prefs.
* @end: The highest possible port in the range of ports to listen on,
@@ -183,6 +177,23 @@ PurpleNetworkListenData *purple_network_
* this callback, or -1 if no socket could be established.
* @cb_data: extra data to be returned when cb is called
*
+ * Opens a listening port selected from a range of ports. The range of
+ * ports used is chosen in the following manner:
+ * If a range is specified in preferences, these values are used.
+ * If a non-0 values are passed to the function as parameters, these
+ * values are used.
+ * Otherwise a port is chosen at random by the operating system.
+ *
+ * This opens a listening port. The caller will want to set up a watcher
+ * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
+ * accept in the watcher callback, and then possibly remove the watcher and close
+ * the listening socket, and add a new watcher on the new socket accept
+ * returned.
+ *
+ * Libpurple does not currently do any port mapping (stateful firewall hole
+ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
+ * addresses, a mapping is done).
+ *
* Returns: A pointer to a data structure that can be used to cancel
* the pending listener, or NULL if unable to obtain a local
* socket to listen on.
@@ -193,26 +204,31 @@ PurpleNetworkListenData *purple_network_
PurpleNetworkListenCallback cb, gpointer cb_data);
/**
+ * purple_network_listen_cancel:
+ * @listen_data: This listener attempt will be cancelled and
+ * the struct will be freed.
+ *
* This can be used to cancel any in-progress listener connection
* by passing in the return value from either purple_network_listen()
* or purple_network_listen_range().
- *
- * @listen_data: This listener attempt will be cancelled and
- * the struct will be freed.
*/
void purple_network_listen_cancel(PurpleNetworkListenData *listen_data);
/**
- * Gets a port number from a file descriptor.
- *
+ * purple_network_get_port_from_fd:
* @fd: The file descriptor. This should be a tcp socket. The current
* implementation probably dies on anything but IPv4. Perhaps this
* possible bug will inspire new and valuable contributors to Purple.
+ *
+ * Gets a port number from a file descriptor.
+ *
* Returns: The port number, in host byte order.
*/
unsigned short purple_network_get_port_from_fd(int fd);
/**
+ * purple_network_is_available:
+ *
* Detects if there is an available network connection.
*
* Returns: TRUE if the network is available
@@ -220,6 +236,8 @@ unsigned short purple_network_get_port_f
gboolean purple_network_is_available(void);
/**
+ * purple_network_force_online:
+ *
* Makes purple_network_is_available() always return %TRUE.
*
* This is what backs the --force-online command line argument in Pidgin,
@@ -229,6 +247,8 @@ gboolean purple_network_is_available(voi
void purple_network_force_online(void);
/**
+ * purple_network_get_handle:
+ *
* Get the handle for the network system
*
* Returns: the handle to the network system
@@ -236,14 +256,17 @@ void purple_network_force_online(void);
void *purple_network_get_handle(void);
/**
+ * purple_network_set_stun_server:
+ * @stun_server: The host name of the STUN server to set
+ *
* Update the STUN server IP given the host name
* Will result in a DNS query being executed asynchronous
- *
- * @stun_server: The host name of the STUN server to set
*/
void purple_network_set_stun_server(const gchar *stun_server);
/**
+ * purple_network_get_stun_ip:
+ *
* Get the IP address of the STUN server as a string representation
*
* Returns: the IP address
@@ -251,14 +274,17 @@ void purple_network_set_stun_server(cons
const gchar *purple_network_get_stun_ip(void);
/**
+ * purple_network_set_turn_server:
+ * @turn_server: The host name of the TURN server to set
+ *
* Update the TURN server IP given the host name
* Will result in a DNS query being executed asynchronous
- *
- * @turn_server: The host name of the TURN server to set
*/
void purple_network_set_turn_server(const gchar *turn_server);
/**
+ * purple_network_get_turn_ip:
+ *
* Get the IP address of the TURN server as a string representation
*
* Returns: the IP address
@@ -266,13 +292,19 @@ void purple_network_set_turn_server(cons
const gchar *purple_network_get_turn_ip(void);
/**
+ * purple_network_remove_port_mapping:
+ * @fd: Socket to remove the port mapping for
+ *
* Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
- *
- * @fd: Socket to remove the port mapping for
*/
void purple_network_remove_port_mapping(gint fd);
/**
+ * purple_network_convert_idn_to_ascii:
+ * @in: The hostname to be converted.
+ * @out: The output buffer where an allocated string will be returned.
+ * The caller is responsible for freeing this.
+ *
* Convert a UTF-8 domain name to ASCII in accordance with the IDNA
* specification. If libpurple is compiled without IDN support, this function
* copies the input into the output buffer.
@@ -282,20 +314,21 @@ void purple_network_remove_port_mapping(
*
* In general, a buffer of about 512 bytes is the appropriate size to use.
*
- * @in: The hostname to be converted.
- * @out: The output buffer where an allocated string will be returned.
- * The caller is responsible for freeing this.
- * Returns:s 0 on success, -1 if the out is NULL, or an error code
+ * Returns: 0 on success, -1 if the out is NULL, or an error code
* that currently corresponds to the Idna_rc enum in libidn.
*/
int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
/**
+ * purple_network_init:
+ *
* Initializes the network subsystem.
*/
void purple_network_init(void);
/**
More information about the Commits
mailing list