Mercurial > pidgin.yaz
annotate src/network.h @ 12974:7080dfef2077
[gaim-migrate @ 15327]
He wrote the original man page, and designed one of the older prefs pages,
or something.
committer: Tailor Script <tailor@pidgin.im>
author | Stu Tomlinson <stu@nosnilmot.com> |
---|---|
date | Sat, 21 Jan 2006 01:48:52 +0000 |
parents | 8e3b85fe4a55 |
children | b7b31c69ade6 |
rev | line source |
---|---|
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 | |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
37 typedef void (*GaimNetworkListenCallback) (int listenfd, gpointer data); |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
38 |
8231 | 39 /** |
8838 | 40 * Converts a dot-decimal IP address to an array of unsigned |
41 * chars. For example, converts 192.168.0.1 to a 4 byte | |
42 * array containing 192, 168, 0 and 1. | |
43 * | |
44 * @param ip An IP address in dot-decimal notiation. | |
45 * @return An array of 4 bytes containing an IP addresses | |
46 * equivalent to the given parameter, or NULL if | |
47 * the given IP address is invalid. This value | |
48 * is statically allocated and should not be | |
49 * freed. | |
50 */ | |
51 const unsigned char *gaim_network_ip_atoi(const char *ip); | |
52 | |
53 /** | |
8834 | 54 * Sets the IP address of the local system in preferences. This |
55 * is the IP address that should be used for incoming connections | |
56 * (file transfer, direct IM, etc.) and should therefore be | |
57 * publicly accessible. | |
8231 | 58 * |
59 * @param ip The local IP address. | |
60 */ | |
8834 | 61 void gaim_network_set_public_ip(const char *ip); |
8231 | 62 |
63 /** | |
64 * Returns the IP address of the local system set in preferences. | |
65 * | |
8834 | 66 * This returns the value set via gaim_network_set_public_ip(). |
8838 | 67 * You probably want to use gaim_network_get_my_ip() instead. |
8231 | 68 * |
69 * @return The local IP address set in preferences. | |
70 */ | |
8834 | 71 const char *gaim_network_get_public_ip(void); |
8231 | 72 |
73 /** | |
74 * Returns the IP address of the local system. | |
75 * | |
8838 | 76 * You probably want to use gaim_network_get_my_ip() instead. |
8231 | 77 * |
78 * @note The returned string is a pointer to a static buffer. If this | |
79 * function is called twice, it may be important to make a copy | |
80 * of the returned string. | |
81 * | |
82 * @param fd The fd to use to help figure out the IP, or else -1. | |
83 * @return The local IP address. | |
84 */ | |
85 const char *gaim_network_get_local_system_ip(int fd); | |
86 | |
87 /** | |
8834 | 88 * Returns the IP address that should be used anywhere a |
89 * public IP addresses is needed (listening for an incoming | |
90 * file transfer, etc). | |
8231 | 91 * |
8834 | 92 * If the user has manually specified an IP address via |
93 * preferences, then this IP is returned. Otherwise the | |
94 * IP address returned by gaim_network_get_local_system_ip() | |
95 * is returned. | |
8231 | 96 * |
97 * @note The returned string is a pointer to a static buffer. If this | |
98 * function is called twice, it may be important to make a copy | |
99 * of the returned string. | |
100 * | |
101 * @param fd The fd to use to help figure out the IP, or -1. | |
102 * @return The local IP address to be used. | |
103 */ | |
8838 | 104 const char *gaim_network_get_my_ip(int fd); |
8231 | 105 |
106 /** | |
8250 | 107 * Attempts to open a listening port ONLY on the specified port number. |
108 * You probably want to use gaim_network_listen_range() instead of this. | |
109 * This function is useful, for example, if you wanted to write a telnet | |
110 * server as a Gaim plugin, and you HAD to listen on port 23. Why anyone | |
8248 | 111 * would want to do that is beyond me. |
8231 | 112 * |
113 * This opens a listening port. The caller will want to set up a watcher | |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
114 * of type GAIM_INPUT_READ on the fd returned in cb. It will probably call |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
115 * accept in the watcher callback, and then possibly remove the watcher and close |
8231 | 116 * the listening socket, and add a new watcher on the new socket accept |
117 * returned. | |
118 * | |
8250 | 119 * @param port The port number to bind to. Must be greater than 0. |
12730
d5b8f4dc1622
[gaim-migrate @ 15074]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
8915
diff
changeset
|
120 * @param socket_type The type of socket to open for listening. |
d5b8f4dc1622
[gaim-migrate @ 15074]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
8915
diff
changeset
|
121 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
122 * @param cb The callback to be invoked when the port to listen on is available. |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
123 * The file descriptor of the listening socket will be specified in |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
124 * this callback, or -1 if no socket could be established. |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
125 * @param cb_data extra data to be returned when cb is called |
8246 | 126 * |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
127 * @return TRUE if the callback will be invoked, or FALSE if unable to obtain |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
128 * a local socket to listen on. |
8231 | 129 */ |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
130 gboolean gaim_network_listen(unsigned short port, int socket_type, |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
131 GaimNetworkListenCallback cb, gpointer cb_data); |
8246 | 132 |
133 /** | |
8250 | 134 * Opens a listening port selected from a range of ports. The range of |
8248 | 135 * ports used is chosen in the following manner: |
136 * If a range is specified in preferences, these values are used. | |
8250 | 137 * If a non-0 values are passed to the function as parameters, these |
8248 | 138 * values are used. |
139 * Otherwise a port is chosen at random by the kernel. | |
8246 | 140 * |
141 * This opens a listening port. The caller will want to set up a watcher | |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
142 * of type GAIM_INPUT_READ on the fd returned in cb. It will probably call |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
143 * accept in the watcher callback, and then possibly remove the watcher and close |
8246 | 144 * the listening socket, and add a new watcher on the new socket accept |
145 * returned. | |
146 * | |
8248 | 147 * @param start The port number to bind to, or 0 to pick a random port. |
8246 | 148 * Users are allowed to override this arg in prefs. |
149 * @param end The highest possible port in the range of ports to listen on, | |
8248 | 150 * or 0 to pick a random port. Users are allowed to override this |
8246 | 151 * arg in prefs. |
12730
d5b8f4dc1622
[gaim-migrate @ 15074]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
8915
diff
changeset
|
152 * @param socket_type The type of socket to open for listening. |
d5b8f4dc1622
[gaim-migrate @ 15074]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
8915
diff
changeset
|
153 * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
154 * @param cb The callback to be invoked when the port to listen on is available. |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
155 * The file descriptor of the listening socket will be specified in |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
156 * this callback, or -1 if no socket could be established. |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
157 * @param cb_data extra data to be returned when cb is called |
8250 | 158 * |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
159 * @return TRUE if the callback will be invoked, or FALSE if unable to obtain |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
160 * a local socket to listen on. |
8246 | 161 */ |
12909
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
162 gboolean gaim_network_listen_range(unsigned short start, unsigned short end, |
8e3b85fe4a55
[gaim-migrate @ 15262]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
12730
diff
changeset
|
163 int socket_type, GaimNetworkListenCallback cb, gpointer cb_data); |
8231 | 164 |
165 /** | |
166 * Gets a port number from a file descriptor. | |
167 * | |
168 * @param fd The file descriptor. This should be a tcp socket. The current | |
169 * implementation probably dies on anything but IPv4. Perhaps this | |
170 * possible bug will inspire new and valuable contributors to Gaim. | |
171 * @return The port number, in host byte order. | |
172 */ | |
8834 | 173 unsigned short gaim_network_get_port_from_fd(int fd); |
8231 | 174 |
175 /** | |
176 * Initializes the network subsystem. | |
177 */ | |
178 void gaim_network_init(void); | |
179 | |
180 /*@}*/ | |
181 | |
182 #ifdef __cplusplus | |
183 } | |
184 #endif | |
185 | |
186 #endif /* _GAIM_NETWORK_H_ */ |