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 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
 103  */
 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);
 108
 109 /**
 110  * Callback to UPNP_get_external_ip_address_().
 111  *
 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.
 115  *
 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_()
 119  */
 120 typedef void (*UPNP_get_external_ip_address_cb_) (int error,
 121                                                   char *ext_ip_addr,
 122                                                   void *cls);
 123
 124 /**
 125  * Get the IP address associated with the WAN connection of the device.
 126  * See UPNP_get_external_ip_address_cb_.
 127  *
 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
 132  */
 133 void
 134 UPNP_get_external_ip_address_ (const char *control_url,
 135                                const char *service_type,
 136                                UPNP_get_external_ip_address_cb_ caller_cb,
 137                                void *caller_cls);
 138
 139 /**
 140  * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
 141  *
 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
 146  *                                   wild-carded
 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
 151  *                              must be the same
 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
 158  *
 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
 162  *
 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
 171  */
 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);
 178
 179
 180 /**
 181  * Request opening a port on the IGD device.
 182  * (remote_host is usually NULL because IGDs don't support it.)
 183  *
 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
 193  */
 194 void
 195 UPNP_add_port_mapping_ (const char *control_url, const char *service_type,
 196                         const char *ext_port,
 197                         const char *in_port,
 198                         const char *in_client,
 199                         const char *desc,
 200                         const char *proto, const char *remote_host,
 201                         UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
 202
 203 /**
 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.)
 208  *
 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
 217  */
 218 void
 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);
 223
 224
 225 /**
 226  * Callback to UPNP_get_specific_port_mapping_entry _().
 227  *
 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
 236  */
 237 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
 238                                                           const char
 239                                                           *control_url,
 240                                                           const char
 241                                                           *service_type,
 242                                                           const char
 243                                                           *ext_port,
 244                                                           const char *proto,
 245                                                           const char *in_port,
 246                                                           const char
 247                                                           *in_client,
 248                                                           void *cls);
 249
 250 /**
 251  * Check that a port mapping set up with UPNP_add_port_mapping_()
 252  * is alive.
 253  *
 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
 262  */
 263 void
 264 UPNP_get_specific_port_mapping_entry_ (const char *control_url,
 265                                        const char *service_type,
 266                                        const char *ext_port,
 267                                        const char *proto,
 268                                        UPNP_get_specific_port_mapping_entry_cb_
 269                                        caller_cb, void *caller_cls);
 270
 271 #endif