src/nat/upnp-commands.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010 Christian Grothoff (and other contributing authors)
   4
   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.
   9
  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.
  14
  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.
  19 */
  20
  21 /*
  22  * Code in this file is originally based on the miniupnp library.
  23  * Copyright (c) 2005-2009, Thomas BERNARD. All rights reserved.
  24  *
  25  * Original licence:
  26  *
  27  * Redistribution and use in source and binary forms, with or without
  28  * modification, are permitted provided that the following conditions are met:
  29  *
  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.
  37  *
  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.
  49  */
  50
  51 /**
  52  * @file nat/upnp-commands.h
  53  * @brief Commands to control UPnP IGD devices
  54  *
  55  * @author Milan Bouchet-Valat
  56  */
  57 #ifndef UPNP_COMMANDS_H
  58 #define UPNP_COMMANDS_H
  59
  60 #include "platform.h"
  61 #include "gnunet_scheduler_lib.h"
  62
  63 /**
  64  * Generic UPnP error codes.
  65  */
  66 #define UPNP_COMMAND_SUCCESS (0)
  67 #define UPNP_COMMAND_UNKNOWN_ERROR (-1)
  68 #define UPNP_COMMAND_INVALID_ARGS (-2)
  69
  70 /**
  71  * Size of the buffer used to store anwsers to UPnP commands.
  72  */
  73 #define UPNP_COMMAND_BUFSIZE 4096
  74
  75 /**
  76  * Name-value pair containing an argumeny to a UPnP command.
  77  */
  78 struct UPNP_Arg_
  79 {
  80   const char *elt;
  81   const char *val;
  82 };
  83
  84 /**
  85  * Callback for UPNP_command_().
  86  *
  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_()
  91  */
  92 typedef void (*UPNP_command_cb_) (char *response, size_t received, void *cls);
  93
  94 /**
  95  * Send UPnP command to the device identified by url and service.
  96  *
  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
 104  */
 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);
 110
 111 /**
 112  * Callback to UPNP_get_external_ip_address_().
 113  *
 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.
 117  *
 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_()
 121  */
 122 typedef void (*UPNP_get_external_ip_address_cb_) (int error,
 123                                                   char *ext_ip_addr,
 124                                                   void *cls);
 125
 126 /**
 127  * Get the IP address associated with the WAN connection of the device.
 128  * See UPNP_get_external_ip_address_cb_.
 129  *
 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
 135  */
 136 void
 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,
 141                                void *caller_cls);
 142
 143 /**
 144  * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
 145  *
 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
 150  *                                   wild-carded
 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
 155  *                              must be the same
 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
 162  *
 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
 166  *
 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
 175  */
 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);
 182
 183
 184 /**
 185  * Request opening a port on the IGD device.
 186  * (remote_host is usually NULL because IGDs don't support it.)
 187  *
 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
 198  */
 199 void
 200 UPNP_add_port_mapping_ (struct GNUNET_SCHEDULER_Handle *sched,
 201                         const char *control_url, const char *service_type,
 202                         const char *ext_port,
 203                         const char *in_port,
 204                         const char *in_client,
 205                         const char *desc,
 206                         const char *proto, const char *remote_host,
 207                         UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
 208
 209 /**
 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.)
 214  *
 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
 224  */
 225 void
 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);
 231
 232
 233 /**
 234  * Callback to UPNP_get_specific_port_mapping_entry _().
 235  *
 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
 244  */
 245 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
 246                                                           const char
 247                                                           *control_url,
 248                                                           const char
 249                                                           *service_type,
 250                                                           const char
 251                                                           *ext_port,
 252                                                           const char *proto,
 253                                                           const char *in_port,
 254                                                           const char
 255                                                           *in_client,
 256                                                           void *cls);
 257
 258 /**
 259  * Check that a port mapping set up with UPNP_add_port_mapping_()
 260  * is alive.
 261  *
 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
 271  */
 272 void
 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,
 277                                        const char *proto,
 278                                        UPNP_get_specific_port_mapping_entry_cb_
 279                                        caller_cb, void *caller_cls);
 280
 281 #endif