annotate src/upnp.h @ 11400:62db025d3eb0

[gaim-migrate @ 13635] sf patch #1277824, from Will Thompson (resiak) Fix C99isms in gtkstatusbox.c Although, I'm not conviced these ARE C99isms committer: Tailor Script <tailor@pidgin.im>
author Mark Doliner <mark@kingant.net>
date Thu, 01 Sep 2005 02:22:03 +0000
parents d3755a7ddd82
children 9563b768e8e2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
1 /**
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
2 * @file upnp.h Universal Plug N Play API
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
3 * @ingroup core
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
4 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
5 * gaim
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
6 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
7 * Gaim is the legal property of its developers, whose names are too numerous
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
8 * to list here. Please refer to the COPYRIGHT file distributed with this
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
9 * source distribution.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
10 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
11 * This program is free software; you can redistribute it and/or modify
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
12 * it under the terms of the GNU General Public License as published by
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
13 * the Free Software Foundation; either version 2 of the License, or
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
14 * (at your option) any later version.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
15 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
16 * This program is distributed in the hope that it will be useful,
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
19 * GNU General Public License for more details.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
20 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
21 * You should have received a copy of the GNU General Public License
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
22 * along with this program; if not, write to the Free Software
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
24 */
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
25
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
26 #ifndef _GAIM_UPNP_H_
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
27 #define _GAIM_UPNP_H_
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
28
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
29
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
30 typedef struct
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
31 {
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
32 gchar* controlURL;
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
33 gchar* serviceType;
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
34 } GaimUPnPControlInfo;
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
35
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
36
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
37 #ifdef __cplusplus
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
38 extern "C" {
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
39 #endif
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
40
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
41 /**************************************************************************/
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
42 /** @name UPnP API */
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
43 /**************************************************************************/
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
44 /*@{*/
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
45
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
46 /**
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
47 * Sends a discovery request to search for a UPnP enabled IGD that
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
48 * contains the WANIPConnection service that will allow us to recieve the
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
49 * public IP address of the IGD, and control it for forwarding ports.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
50 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
51 * @param void
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
52 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
53 * @return The control URL for the IGD we'll use to use the IGD services
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
54 */
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
55 GaimUPnPControlInfo* gaim_upnp_discover(void);
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
56
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
57
11213
ff728e84d59a [gaim-migrate @ 13344]
Thomas Butter <tbutter>
parents: 11208
diff changeset
58
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
59 /**
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
60 * Gets the IP address from a UPnP enabled IGD that sits on the local
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
61 * network, so when getting the network IP, instead of returning the
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
62 * local network IP, the public IP is retrieved.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
63 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
64 * @param controlURL The control URL retrieved from gaim_upnp_discover.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
65 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
66 * @return The IP address of the network, or NULL if something went wrong
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
67 */
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
68 gchar* gaim_upnp_get_public_ip(const GaimUPnPControlInfo* controlInfo);
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
69
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
70
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
71 /**
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
72 * Maps Ports in a UPnP enabled IGD that sits on the local network to
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
73 * this gaim client. Essentially, this function takes care of the port
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
74 * forwarding so things like file transfers can work behind NAT firewalls
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
75 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
76 * @param controlURL The control URL retrieved from gaim_upnp_discover.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
77 * @param portMap The port to map to this client
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
78 * @param protocol The protocol to map, either "TCP" or "UDP"
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
79 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
80 * @return TRUE if success, FALSE if something went wrong.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
81 */
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
82 gboolean gaim_upnp_set_port_mapping(const GaimUPnPControlInfo* controlInfo,
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
83 unsigned short portMap,
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
84 const gchar* protocol);
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
85
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
86 /**
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
87 * Deletes a port mapping in a UPnP enabled IGD that sits on the local network
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
88 * to this gaim client. Essentially, this function takes care of deleting the
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
89 * port forwarding after they have completed a connection so another client on
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
90 * the local network can take advantage of the port forwarding
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
91 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
92 * @param controlURL The control URL retrieved from gaim_upnp_discover.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
93 * @param portMap The port to delete the mapping for
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
94 * @param protocol The protocol to map to. Either "TCP" or "UDP"
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
95 *
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
96 * @return TRUE if success, FALSE if something went wrong.
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
97 */
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
98 gboolean
11391
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
99 gaim_upnp_remove_port_mapping(const GaimUPnPControlInfo* controlURL,
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
100 unsigned short portMap,
d3755a7ddd82 [gaim-migrate @ 13620]
Adam Warrington <awarring>
parents: 11213
diff changeset
101 const gchar* protocol);
11195
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
102 /*@}*/
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
103
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
104
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
105 #ifdef __cplusplus
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
106 }
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
107 #endif
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
108
3aeb85cc9cda [gaim-migrate @ 13319]
Adam Warrington <awarring>
parents:
diff changeset
109 #endif /* _GAIM_UPNP_H_ */