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 url control URL of the device
98 * @param service type of the service corresponding to the command
99 * @param action action to send
100 * @param args arguments for action
101 * @param caller_cb user callback to trigger when done
102 * @param caller_cls closure to pass to caller_cb
104 void UPNP_command_ (const char *url, const char *service,
105 const char *action, struct UPNP_Arg_ *args,
106 char *buffer, size_t buf_size,
107 UPNP_command_cb_ caller_cb, void *caller_cls);
110 * Callback to UPNP_get_external_ip_address_().
112 * Possible UPnP Errors :
113 * 402 Invalid Args - See UPnP Device Architecture section on Control.
114 * 501 Action Failed - See UPnP Device Architecture section on Control.
116 * @param error GNUNET_OK on success, another value on error (see above)
117 * @param ext_ip_addr the external IP address reported by the device (IPv4 or v6)
118 * @param cls the closure passed to UPNP_get_external_ip_address_()
120 typedef void (*UPNP_get_external_ip_address_cb_) (int error,
125 * Get the IP address associated with the WAN connection of the device.
126 * See UPNP_get_external_ip_address_cb_.
128 * @param control_url the control URL corresponding to service_type on the device
129 * @param service_type service type to call the command on
130 * @param caller_cb function to call when done
131 * @param cls closure passed to caller_cb
134 UPNP_get_external_ip_address_ (const char *control_url,
135 const char *service_type,
136 UPNP_get_external_ip_address_cb_ caller_cb,
140 * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
142 * Possible UPnP Errors with UPNP_add_port_mapping_():
143 * 402 Invalid Args - See UPnP Device Architecture section on Control.
144 * 501 Action Failed - See UPnP Device Architecture section on Control.
145 * 715 WildCardNotPermittedInSrcIP - The source IP address cannot be
147 * 716 WildCardNotPermittedInext_port - The external port cannot be wild-carded
148 * 718 ConflictInMappingEntry - The port mapping entry specified conflicts
149 * with a mapping assigned previously to another client
150 * 724 SamePortValuesRequired - Internal and External port values
152 * 725 OnlyPermanentLeasesSupported - The NAT implementation only supports
153 * permanent lease times on port mappings
154 * 726 RemoteHostOnlySupportsWildcard - RemoteHost must be a wildcard
155 * and cannot be a specific IP address or DNS name
156 * 727 ExternalPortOnlySupportsWildcard - ExternalPort must be a wildcard and
157 * cannot be a specific port value
159 * Possible UPnP Errors with UPNP_delete_port_mapping_():
160 * 402 Invalid Args - See UPnP Device Architecture section on Control.
161 * 714 NoSuchEntryInArray - The specified value does not exist in the array
163 * @param error GNUNET_OK on success, another value on error (see above)
164 * @param control_url the control URL the command was called on
165 * @param service_type service the command was called on
166 * @param in_port port on the gateway on the LAN side which was requested
167 * @param in_client address in the LAN which was requested
168 * @param proto protocol for which port mapping was requested
169 * @param remote_host remote host for which port mapping was requested
170 * @param cls the closure passed to the command function
172 typedef void (*UPNP_port_mapping_cb_) (int error,
173 const char *control_url,
174 const char *service_type,
175 const char *ext_port,
176 const char *inPort, const char *proto,
177 const char *remote_host, void *cls);
181 * Request opening a port on the IGD device.
182 * (remote_host is usually NULL because IGDs don't support it.)
184 * @param control_url the control URL corresponding to service_type on the device
185 * @param service_type service type to call the command on
186 * @param ext_port port that should be opened on the WAN side
187 * @param in_port port on the gateway on the LAN side which should map ext_port
188 * @param in_client address in the LAN to which packets should be redirected
189 * @param proto protocol for which to request port mapping
190 * @param remote_host remote host for which to request port mapping
191 * @param caller_cb function to call when done
192 * @param cls closure passed to caller_cb
195 UPNP_add_port_mapping_ (const char *control_url, const char *service_type,
196 const char *ext_port,
198 const char *in_client,
200 const char *proto, const char *remote_host,
201 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
204 * Request closing a a port on the IGD device that was previously opened
205 * using UPNP_add_port_mapping_(). Use the same argument values that were
206 * used when opening the port.
207 * (remote_host is usually NULL because IGDs don't support it.)
209 * @param control_url the control URL the command was called on
210 * @param service_type service the command was called on
211 * @param in_port port on the gateway on the LAN side which was requested
212 * @param in_client address in the LAN which was requested
213 * @param proto protocol for which port mapping was requested
214 * @param remote_host remote host for which port mapping was requested
215 * @param caller_cb function to call when done
216 * @param cls closure passed to caller_cb
219 UPNP_delete_port_mapping_ (const char *control_url, const char *service_type,
220 const char *ext_port, const char *proto,
221 const char *remote_host,
222 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
226 * Callback to UPNP_get_specific_port_mapping_entry _().
228 * @param error GNUNET_OK if port is currently mapped, another value on error
229 * @param control_url the control URL the command was called on
230 * @param service_type service the command was called on
231 * @param in_port port on the gateway on the LAN side which was requested
232 * @param in_client address in the LAN which was requested
233 * @param proto protocol for which port mapping was requested
234 * @param remote_host remote host for which port mapping was requested
235 * @param cls the closure passed to the command function
237 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
251 * Check that a port mapping set up with UPNP_add_port_mapping_()
254 * @param control_url the control URL the command was called on
255 * @param service_type service the command was called on
256 * @param in_port port on the gateway on the LAN side which was requested
257 * @param in_client address in the LAN which was requested
258 * @param proto protocol for which port mapping was requested
259 * @param remote_host remote host for which port mapping was requested
260 * @param caller_cb function to call when done
261 * @param cls closure passed to caller_cb
264 UPNP_get_specific_port_mapping_entry_ (const char *control_url,
265 const char *service_type,
266 const char *ext_port,
268 UPNP_get_specific_port_mapping_entry_cb_
269 caller_cb, void *caller_cls);