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 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
 105  */
 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);
 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 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
 134  */
 135 void
 136 UPNP_get_external_ip_address_ (const char *control_url,
 137                                const char *service_type,
 138                                UPNP_get_external_ip_address_cb_ caller_cb,
 139                                void *caller_cls);
 140
 141 /**
 142  * Callback to UPNP_add_port_mapping_() and UPNP_delete_port_mapping_().
 143  *
 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
 148  *                                   wild-carded
 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
 153  *                              must be the same
 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
 160  *
 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
 164  *
 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
 173  */
 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);
 180
 181
 182 /**
 183  * Request opening a port on the IGD device.
 184  * (remote_host is usually NULL because IGDs don't support it.)
 185  *
 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
 196  */
 197 void
 198 UPNP_add_port_mapping_ (const char *control_url, const char *service_type,
 199                         const char *ext_port,
 200                         const char *in_port,
 201                         const char *in_client,
 202                         const char *desc,
 203                         const char *proto, const char *remote_host,
 204                         UPNP_port_mapping_cb_ caller_cb, void *caller_cls);
 205
 206 /**
 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.)
 211  *
 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 caller_cls closure passed to caller_cb
 219  */
 220 void
 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);
 225
 226
 227 /**
 228  * Callback to UPNP_get_specific_port_mapping_entry _().
 229  *
 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
 238  */
 239 typedef void (*UPNP_get_specific_port_mapping_entry_cb_) (int error,
 240                                                           const char
 241                                                           *control_url,
 242                                                           const char
 243                                                           *service_type,
 244                                                           const char
 245                                                           *ext_port,
 246                                                           const char *proto,
 247                                                           const char *in_port,
 248                                                           const char
 249                                                           *in_client,
 250                                                           void *cls);
 251
 252 /**
 253  * Check that a port mapping set up with UPNP_add_port_mapping_()
 254  * is alive.
 255  *
 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 caller_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