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