8231
|
1 /**
|
|
2 * @file network.h Network API
|
|
3 * @ingroup core
|
|
4 *
|
|
5 * gaim
|
|
6 *
|
|
7 * Gaim is the legal property of its developers, whose names are too numerous
|
|
8 * to list here. Please refer to the COPYRIGHT file distributed with this
|
|
9 * source distribution.
|
|
10 *
|
|
11 * This program is free software; you can redistribute it and/or modify
|
|
12 * it under the terms of the GNU General Public License as published by
|
|
13 * the Free Software Foundation; either version 2 of the License, or
|
|
14 * (at your option) any later version.
|
|
15 *
|
|
16 * This program is distributed in the hope that it will be useful,
|
|
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
19 * GNU General Public License for more details.
|
|
20 *
|
|
21 * You should have received a copy of the GNU General Public License
|
|
22 * along with this program; if not, write to the Free Software
|
|
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
24 */
|
|
25 #ifndef _GAIM_NETWORK_H_
|
|
26 #define _GAIM_NETWORK_H_
|
|
27
|
|
28 #ifdef __cplusplus
|
|
29 extern "C" {
|
|
30 #endif
|
|
31
|
|
32 /**************************************************************************/
|
8834
|
33 /** @name Network API */
|
8231
|
34 /**************************************************************************/
|
|
35 /*@{*/
|
|
36
|
|
37 /**
|
8834
|
38 * Sets the IP address of the local system in preferences. This
|
|
39 * is the IP address that should be used for incoming connections
|
|
40 * (file transfer, direct IM, etc.) and should therefore be
|
|
41 * publicly accessible.
|
8231
|
42 *
|
|
43 * @param ip The local IP address.
|
|
44 */
|
8834
|
45 void gaim_network_set_public_ip(const char *ip);
|
8231
|
46
|
|
47 /**
|
|
48 * Returns the IP address of the local system set in preferences.
|
|
49 *
|
8834
|
50 * This returns the value set via gaim_network_set_public_ip().
|
8231
|
51 * You probably want to use gaim_network_get_ip_for_account() instead.
|
|
52 *
|
|
53 * @return The local IP address set in preferences.
|
|
54 */
|
8834
|
55 const char *gaim_network_get_public_ip(void);
|
8231
|
56
|
|
57 /**
|
|
58 * Returns the IP address of the local system.
|
|
59 *
|
|
60 * You probably want to use gaim_network_get_ip_for_account() instead.
|
|
61 *
|
|
62 * @note The returned string is a pointer to a static buffer. If this
|
|
63 * function is called twice, it may be important to make a copy
|
|
64 * of the returned string.
|
|
65 *
|
|
66 * @param fd The fd to use to help figure out the IP, or else -1.
|
|
67 * @return The local IP address.
|
|
68 */
|
|
69 const char *gaim_network_get_local_system_ip(int fd);
|
|
70
|
|
71 /**
|
8834
|
72 * Returns the IP address that should be used anywhere a
|
|
73 * public IP addresses is needed (listening for an incoming
|
|
74 * file transfer, etc).
|
8231
|
75 *
|
8834
|
76 * If the user has manually specified an IP address via
|
|
77 * preferences, then this IP is returned. Otherwise the
|
|
78 * IP address returned by gaim_network_get_local_system_ip()
|
|
79 * is returned.
|
8231
|
80 *
|
|
81 * @note The returned string is a pointer to a static buffer. If this
|
|
82 * function is called twice, it may be important to make a copy
|
|
83 * of the returned string.
|
|
84 *
|
|
85 * @param account The account to use. This may be @c NULL, and if so
|
|
86 * the first step listed above is skipped.
|
|
87 * @param fd The fd to use to help figure out the IP, or -1.
|
|
88 * @return The local IP address to be used.
|
|
89 */
|
|
90 const char *gaim_network_get_ip_for_account(const GaimAccount *account, int fd);
|
|
91
|
|
92 /**
|
8250
|
93 * Attempts to open a listening port ONLY on the specified port number.
|
|
94 * You probably want to use gaim_network_listen_range() instead of this.
|
|
95 * This function is useful, for example, if you wanted to write a telnet
|
|
96 * server as a Gaim plugin, and you HAD to listen on port 23. Why anyone
|
8248
|
97 * would want to do that is beyond me.
|
8231
|
98 *
|
|
99 * This opens a listening port. The caller will want to set up a watcher
|
|
100 * of type GAIM_INPUT_READ on the returned fd. It will probably call
|
|
101 * accept in the callback, and then possibly remove the watcher and close
|
|
102 * the listening socket, and add a new watcher on the new socket accept
|
|
103 * returned.
|
|
104 *
|
8250
|
105 * @param port The port number to bind to. Must be greater than 0.
|
8246
|
106 *
|
|
107 * @return The file descriptor of the listening socket, or -1 if
|
8240
|
108 * no socket could be established.
|
8231
|
109 */
|
8250
|
110 int gaim_network_listen(unsigned short port);
|
8246
|
111
|
|
112 /**
|
8250
|
113 * Opens a listening port selected from a range of ports. The range of
|
8248
|
114 * ports used is chosen in the following manner:
|
|
115 * If a range is specified in preferences, these values are used.
|
8250
|
116 * If a non-0 values are passed to the function as parameters, these
|
8248
|
117 * values are used.
|
|
118 * Otherwise a port is chosen at random by the kernel.
|
8246
|
119 *
|
|
120 * This opens a listening port. The caller will want to set up a watcher
|
|
121 * of type GAIM_INPUT_READ on the returned fd. It will probably call
|
|
122 * accept in the callback, and then possibly remove the watcher and close
|
|
123 * the listening socket, and add a new watcher on the new socket accept
|
|
124 * returned.
|
|
125 *
|
8248
|
126 * @param start The port number to bind to, or 0 to pick a random port.
|
8246
|
127 * Users are allowed to override this arg in prefs.
|
|
128 * @param end The highest possible port in the range of ports to listen on,
|
8248
|
129 * or 0 to pick a random port. Users are allowed to override this
|
8246
|
130 * arg in prefs.
|
8250
|
131 *
|
8246
|
132 * @return The file descriptor of the listening socket, or -1 if
|
|
133 * no socket could be established.
|
|
134 */
|
8250
|
135 int gaim_network_listen_range(unsigned short start, unsigned short end);
|
8231
|
136
|
|
137 /**
|
|
138 * Gets a port number from a file descriptor.
|
|
139 *
|
|
140 * @param fd The file descriptor. This should be a tcp socket. The current
|
|
141 * implementation probably dies on anything but IPv4. Perhaps this
|
|
142 * possible bug will inspire new and valuable contributors to Gaim.
|
|
143 * @return The port number, in host byte order.
|
|
144 */
|
8834
|
145 unsigned short gaim_network_get_port_from_fd(int fd);
|
8231
|
146
|
|
147 /**
|
|
148 * Initializes the network subsystem.
|
|
149 */
|
|
150 void gaim_network_init(void);
|
|
151
|
|
152 /*@}*/
|
|
153
|
|
154 #ifdef __cplusplus
|
|
155 }
|
|
156 #endif
|
|
157
|
|
158 #endif /* _GAIM_NETWORK_H_ */
|