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 buffer buffer
102 * @param buf_size buffer size
103 * @param caller_cb user callback to trigger when done
104 * @param caller_cls closure to pass to caller_cb
106 void UPNP_command_ (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 control_url the control URL corresponding to service_type on the device
131 * @param service_type service type to call the command on
132 * @param caller_cb function to call when done
133 * @param caller_cls closure passed to caller_cb
136 UPNP_get_external_ip_address_ (const char *control_url,
137 const char *service_type,
138 UPNP_get_external_ip_address_cb_ caller_cb,
142 * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
144 * Possible UPnP Errors with UPNP_add_port_mapping_():
145 * 402 Invalid Args - See UPnP Device Architecture section on Control.
146 * 501 Action Failed - See UPnP Device Architecture section on Control.
147 * 715 WildCardNotPermittedInSrcIP - The source IP address cannot be
149 * 716 WildCardNotPermittedInext_port - The external port cannot be wild-carded
150 * 718 ConflictInMappingEntry - The port mapping entry specified conflicts
151 * with a mapping assigned previously to another client
152 * 724 SamePortValuesRequired - Internal and External port values
154 * 725 OnlyPermanentLeasesSupported - The NAT implementation only supports
155 * permanent lease times on port mappings
156 * 726 RemoteHostOnlySupportsWildcard - RemoteHost must be a wildcard
157 * and cannot be a specific IP address or DNS name
158 * 727 ExternalPortOnlySupportsWildcard - ExternalPort must be a wildcard and
159 * cannot be a specific port value
161 * Possible UPnP Errors with UPNP_delete_port_mapping_():
162 * 402 Invalid Args - See UPnP Device Architecture section on Control.
163 * 714 NoSuchEntryInArray - The specified value does not exist in the array
165 * @param error GNUNET_OK on success, another value on error (see above)
166 * @param control_url the control URL the command was called on
167 * @param service_type service the command was called on
168 * @param ext_port external port
169 * @param inPort port on the gateway on the LAN side which was requested
170 * @param proto protocol for which port mapping was requested
171 * @param remote_host remote host for which port mapping was requested
172 * @param cls the closure passed to the command function
174 typedef void (*UPNP_port_mapping_cb_) (int error,
175 const char *control_url,
176 const char *service_type,
177 const char *ext_port,
178 const char *inPort, const char *proto,
179 const char *remote_host, void *cls);
183 * Request opening a port on the IGD device.
184 * (remote_host is usually NULL because IGDs don't support it.)
186 * @param control_url the control URL corresponding to service_type on the device
187 * @param service_type service type to call the command on
188 * @param ext_port port that should be opened on the WAN side
189 * @param in_port port on the gateway on the LAN side which should map ext_port
190 * @param in_client address in the LAN to which packets should be redirected
191 * @param desc description
192 * @param proto protocol for which to request port mapping
193 * @param remote_host remote host for which to request port mapping
194 * @param caller_cb function to call when done
195 * @param caller_cls closure passed to caller_cb
198 UPNP_add_port_mapping_ (const char *control_url, const char *service_type,
199 const char *ext_port,
201 const char *in_client,
203 const char *proto, const char *remote_host,
204 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
207 * Request closing a a port on the IGD device that was previously opened
208 * using UPNP_add_port_mapping_(). Use the same argument values that were
209 * used when opening the port.
210 * (remote_host is usually NULL because IGDs don't support it.)
212 * @param control_url the control URL the command was called on
213 * @param service_type service the command was called on
214 * @param ext_port external port
215 * @param proto protocol for which port mapping was requested
216 * @param remote_host remote host for which port mapping was requested
217 * @param caller_cb function to call when done
218 * @param cls closure passed to caller_cb
221 UPNP_delete_port_mapping_ (const char *control_url, const char *service_type,
222 const char *ext_port, const char *proto,
223 const char *remote_host,
224 UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
228 * Callback to UPNP_get_specific_port_mapping_entry _().
230 * @param error GNUNET_OK if port is currently mapped, another value on error
231 * @param control_url the control URL the command was called on
232 * @param service_type service the command was called on
233 * @param ext_port external port
234 * @param proto protocol for which port mapping was requested
235 * @param in_port port on the gateway on the LAN side which was requested
236 * @param in_client address in the LAN which was requested
237 * @param cls the closure passed to the command function
239 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
253 * Check that a port mapping set up with UPNP_add_port_mapping_()
256 * @param control_url the control URL the command was called on
257 * @param service_type service the command was called on
258 * @param ext_port external port
259 * @param proto protocol for which port mapping was requested
260 * @param caller_cb function to call when done
261 * @param callers_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);