2 This file is part of GNUnet.
3 (C) 2009, 2010 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * Code in this file is originally based on the miniupnp library.
23 * Copyright (c) 2005-2009, Thomas BERNARD. All rights reserved.
27 * Redistribution and use in source and binary forms, with or without
28 * modification, are permitted provided that the following conditions are met:
30 * * Redistributions of source code must retain the above copyright notice,
31 * this list of conditions and the following disclaimer.
32 * * Redistributions in binary form must reproduce the above copyright notice,
33 * this list of conditions and the following disclaimer in the documentation
34 * and/or other materials provided with the distribution.
35 * * The name of the author may not be used to endorse or promote products
36 * derived from this software without specific prior written permission.
38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
39 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
41 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
42 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
43 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
44 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
45 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
46 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
47 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
48 * POSSIBILITY OF SUCH DAMAGE.
52 * @file nat/upnp-commands.h
53 * @brief Commands to control UPnP IGD devices
55 * @author Milan Bouchet-Valat
57 #ifndef UPNP_COMMANDS_H
58 #define UPNP_COMMANDS_H
61 #include "gnunet_scheduler_lib.h"
64 * Generic UPnP error codes.
66 #define UPNP_COMMAND_SUCCESS (0)
67 #define UPNP_COMMAND_UNKNOWN_ERROR (-1)
68 #define UPNP_COMMAND_INVALID_ARGS (-2)
71 * Size of the buffer used to store anwsers to UPnP commands.
73 #define UPNP_COMMAND_BUFSIZE 4096
76 * Name-value pair containing an argumeny to a UPnP command.
85 * Callback for UPNP_command_().
87 * @param response the buffer passed to UPNP_command_(), filled with
88 * NULL-terminated content (if any)
89 * @param received length of the content received and stored in response
90 * @param cls closure passed to UPNP_command_()
92 typedef void (*UPNP_command_cb_) (char *response, size_t received, void *cls);
95 * Send UPnP command to the device identified by url and service.
97 * @param sched scheduler to use for network tasks
98 * @param url control URL of the device
99 * @param service type of the service corresponding to the command
100 * @param action action to send
101 * @param args arguments for action
102 * @param caller_cb user callback to trigger when done
103 * @param caller_cls closure to pass to caller_cb
105 void UPNP_command_ (struct GNUNET_SCHEDULER_Handle *sched,
106 const char *url, const char *service,
107 const char *action, struct UPNP_Arg_ *args,
108 char *buffer, size_t buf_size,
109 UPNP_command_cb_ caller_cb, void *caller_cls);
112 * Callback to UPNP_get_external_ip_address_().
114 * Possible UPnP Errors :
115 * 402 Invalid Args - See UPnP Device Architecture section on Control.
116 * 501 Action Failed - See UPnP Device Architecture section on Control.
118 * @param error GNUNET_OK on success, another value on error (see above)
119 * @param ext_ip_addr the external IP address reported by the device (IPv4 or v6)
120 * @param cls the closure passed to UPNP_get_external_ip_address_()
122 typedef void (*UPNP_get_external_ip_address_cb_) (int error,
127 * Get the IP address associated with the WAN connection of the device.
128 * See UPNP_get_external_ip_address_cb_.
130 * @param sched the scheduler to use for networking
131 * @param control_url the control URL corresponding to service_type on the device
132 * @param service_type service type to call the command on
133 * @param caller_cb function to call when done
134 * @param cls closure passed to caller_cb
137 UPNP_get_external_ip_address_ (struct GNUNET_SCHEDULER_Handle *sched,
138 const char *control_url,
139 const char *service_type,
140 UPNP_get_external_ip_address_cb_ caller_cb,
144 * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
146 * Possible UPnP Errors with UPNP_add_port_mapping_():
147 * 402 Invalid Args - See UPnP Device Architecture section on Control.
148 * 501 Action Failed - See UPnP Device Architecture section on Control.
149 * 715 WildCardNotPermittedInSrcIP - The source IP address cannot be
151 * 716 WildCardNotPermittedInext_port - The external port cannot be wild-carded
152 * 718 ConflictInMappingEntry - The port mapping entry specified conflicts
153 * with a mapping assigned previously to another client
154 * 724 SamePortValuesRequired - Internal and External port values
156 * 725 OnlyPermanentLeasesSupported - The NAT implementation only supports
157 * permanent lease times on port mappings
158 * 726 RemoteHostOnlySupportsWildcard - RemoteHost must be a wildcard
159 * and cannot be a specific IP address or DNS name
160 * 727 ExternalPortOnlySupportsWildcard - ExternalPort must be a wildcard and
161 * cannot be a specific port value
163 * Possible UPnP Errors with UPNP_delete_port_mapping_():
164 * 402 Invalid Args - See UPnP Device Architecture section on Control.
165 * 714 NoSuchEntryInArray - The specified value does not exist in the array
167 * @param error GNUNET_OK on success, another value on error (see above)
168 * @param control_url the control URL the command was called on
169 * @param service_type service the command was called on
170 * @param in_port port on the gateway on the LAN side which was requested
171 * @param in_client address in the LAN which was requested
172 * @param proto protocol for which port mapping was requested
173 * @param remote_host remote host for which port mapping was requested
174 * @param cls the closure passed to the command function
176 typedef void (*UPNP_port_mapping_cb_) (int error,
177 const char *control_url,
178 const char *service_type,
179 const char *ext_port,
180 const char *inPort, const char *proto,
181 const char *remote_host, void *cls);
185 * Request opening a port on the IGD device.
186 * (remote_host is usually NULL because IGDs don't support it.)
188 * @param sched the scheduler to use for networking
189 * @param control_url the control URL corresponding to service_type on the device
190 * @param service_type service type to call the command on
191 * @param ext_port port that should be opened on the WAN side
192 * @param in_port port on the gateway on the LAN side which should map ext_port
193 * @param in_client address in the LAN to which packets should be redirected
194 * @param proto protocol for which to request port mapping
195 * @param remote_host remote host for which to request port mapping
196 * @param caller_cb function to call when done
197 * @param cls closure passed to caller_cb
200 UPNP_add_port_mapping_ (struct GNUNET_SCHEDULER_Handle *sched,
201 const char *control_url, const char *service_type,
202 const char *ext_port,
204 const char *in_client,
206 const char *proto, const char *remote_host,
207 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
210 * Request closing a a port on the IGD device that was previously opened
211 * using UPNP_add_port_mapping_(). Use the same argument values that were
212 * used when opening the port.
213 * (remote_host is usually NULL because IGDs don't support it.)
215 * @param sched the scheduler to use for networking
216 * @param control_url the control URL the command was called on
217 * @param service_type service the command was called on
218 * @param in_port port on the gateway on the LAN side which was requested
219 * @param in_client address in the LAN which was requested
220 * @param proto protocol for which port mapping was requested
221 * @param remote_host remote host for which port mapping was requested
222 * @param caller_cb function to call when done
223 * @param cls closure passed to caller_cb
226 UPNP_delete_port_mapping_ (struct GNUNET_SCHEDULER_Handle *sched,
227 const char *control_url, const char *service_type,
228 const char *ext_port, const char *proto,
229 const char *remote_host,
230 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
234 * Callback to UPNP_get_specific_port_mapping_entry _().
236 * @param error GNUNET_OK if port is currently mapped, another value on error
237 * @param control_url the control URL the command was called on
238 * @param service_type service the command was called on
239 * @param in_port port on the gateway on the LAN side which was requested
240 * @param in_client address in the LAN which was requested
241 * @param proto protocol for which port mapping was requested
242 * @param remote_host remote host for which port mapping was requested
243 * @param cls the closure passed to the command function
245 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
259 * Check that a port mapping set up with UPNP_add_port_mapping_()
262 * @param sched the scheduler to use for networking
263 * @param control_url the control URL the command was called on
264 * @param service_type service the command was called on
265 * @param in_port port on the gateway on the LAN side which was requested
266 * @param in_client address in the LAN which was requested
267 * @param proto protocol for which port mapping was requested
268 * @param remote_host remote host for which port mapping was requested
269 * @param caller_cb function to call when done
270 * @param cls closure passed to caller_cb
273 UPNP_get_specific_port_mapping_entry_ (struct GNUNET_SCHEDULER_Handle *sched,
274 const char *control_url,
275 const char *service_type,
276 const char *ext_port,
278 UPNP_get_specific_port_mapping_entry_cb_
279 caller_cb, void *caller_cls);