miniupnpc 2.3.0__tar.gz → 2.3.2__tar.gz

miniupnpc-2.3.2/DESCRIPTION

@@ -0,0 +1,6 @@
+MiniUPnPc is a library enabling applications to access the services provided
+by an UPnP "Internet Gateway Device" present on the network. In UPnP
+terminology, MiniUPnPc is a UPnP Control Point.
+
+MiniUPnPc is designed to have low footprint and the libc as unique
+dependency.

{miniupnpc-2.3.0 → miniupnpc-2.3.2}/MANIFEST.in

@@ -1,6 +1,7 @@
 include README
 include VERSION
 include LICENSE
+include DESCRIPTION
 include src/miniupnpcmodule.c
 include setup.py
 include Makefile

{miniupnpc-2.3.0 → miniupnpc-2.3.2}/Makefile

@@ -1,9 +1,9 @@
-# $Id: Makefile,v 1.150 2023/06/15 22:55:24 nanard Exp $
+# $Id: Makefile,v 1.155 2025/03/02 01:17:19 nanard Exp $
 # MiniUPnP Project
 # http://miniupnp.free.fr/
 # https://miniupnp.tuxfamily.org/
 # https://github.com/miniupnp/miniupnp
-# (c) 2005-2024 Thomas Bernard
+# (c) 2005-2025 Thomas Bernard
 # to install use :
 # $ make DESTDIR=/tmp/dummylocation install
 # or
@@ -84,9 +84,10 @@ ifneq (, $(findstring sun, $(OS))$(findstring solaris, $(OS)))
 endif
 
 # APIVERSION is used to build SONAME
-APIVERSION = 19
+APIVERSION = 20
 
 SRCS = $(wildcard $(SRCDIR)/*.c)
+PRIVATE_HEADERS = $(wildcard $(SRCDIR)/*.h)
 
 LIBOBJS = $(addprefix $(BUILD)/,miniwget.o minixml.o igd_desc_parse.o minisoap.o \
           miniupnpc.o upnpreplyparse.o upnpcommands.o upnperrors.o \
@@ -167,7 +168,7 @@ endif
 
 
 .PHONY:	install clean depend all check test everything \
-	installpythonmodule updateversion
+	installpythonmodule updateversion doc
 
 all:	$(LIBRARY) $(EXECUTABLES)
 
@@ -178,6 +179,8 @@ check:	validateminixml validateminiwget validateupnpreplyparse \
 
 everything:	all $(EXECUTABLES_ADDTESTS)
 
+doc:	doxygen/html/index.html
+
 # note : the python module "wheel" is required for bdist_wheel
 pythonmodule:	$(LIBRARY) $(SRCDIR)/miniupnpcmodule.c setup.py
 	MAKE=$(MAKE) python setup.py build
@@ -397,6 +400,9 @@ ideb:
 
 minihttptestserver:	minihttptestserver.o
 
+doxygen/html/index.html: Doxyfile $(SRCS) $(HEADERS) $(PRIVATE_HEADERS)
+	doxygen
+
 print-%:
 	@echo "$* = $($*)"
 

{miniupnpc-2.3.0/miniupnpc.egg-info → miniupnpc-2.3.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: miniupnpc
-Version: 2.3.0
+Version: 2.3.2
 Summary: MiniUPnP IGD client
 Home-page: https://miniupnp.tuxfamily.org/
 Author: Thomas BERNARD
 Author-email: miniupnp@free.fr
 License: BSD 3-Clause License
         
-        Copyright (c) 2005-2024, Thomas BERNARD
+        Copyright (c) 2005-2025, Thomas BERNARD
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without

{miniupnpc-2.3.0 → miniupnpc-2.3.2}/README

@@ -2,7 +2,7 @@ Project: miniupnp
 Project web page: http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/
 github: https://github.com/miniupnp/miniupnp
 Author: Thomas Bernard
-Copyright (c) 2005-2023 Thomas Bernard
+Copyright (c) 2005-2025 Thomas Bernard
 This software is subject to the conditions detailed in the
 LICENSE file provided within this distribution.
 

miniupnpc-2.3.2/VERSION

@@ -0,0 +1 @@
+2.3.2

miniupnpc-2.3.2/include/igd_desc_parse.h

@@ -0,0 +1,75 @@
+/* $Id: igd_desc_parse.h,v 1.14 2025/02/08 23:15:16 nanard Exp $ */
+/* Project : miniupnp
+ * http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/
+ * Author : Thomas Bernard
+ * Copyright (c) 2005-2025 Thomas Bernard
+ * This software is subject to the conditions detailed in the
+ * LICENCE file provided in this distribution.
+ * */
+#ifndef IGD_DESC_PARSE_H_INCLUDED
+#define IGD_DESC_PARSE_H_INCLUDED
+
+/*! \file igd_desc_parse.h
+ * \brief API to parse UPNP device description XML
+ * \todo should not be exposed in the public API
+ */
+
+/*! \brief maximum lenght of URLs */
+#define MINIUPNPC_URL_MAXSIZE (128)
+
+/*! \brief Structure to store the result of the parsing of UPnP
+ * descriptions of Internet Gateway Devices services */
+struct IGDdatas_service {
+	/*! \brief controlURL for the service */
+	char controlurl[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief eventSubURL for the service */
+	char eventsuburl[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief SCPDURL for the service */
+	char scpdurl[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief serviceType */
+	char servicetype[MINIUPNPC_URL_MAXSIZE];
+	/*char devicetype[MINIUPNPC_URL_MAXSIZE];*/
+};
+
+/*! \brief Structure to store the result of the parsing of UPnP
+ * descriptions of Internet Gateway Devices */
+struct IGDdatas {
+	/*! \brief current element name */
+	char cureltname[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief URLBase */
+	char urlbase[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief presentationURL */
+	char presentationurl[MINIUPNPC_URL_MAXSIZE];
+	/*! \brief depth into the XML tree */
+	int level;
+	/*! \brief "urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1" */
+	struct IGDdatas_service CIF;
+	/*! \brief first of "urn:schemas-upnp-org:service:WANIPConnection:1"
+	 * or "urn:schemas-upnp-org:service:WANPPPConnection:1" */
+	struct IGDdatas_service first;
+	/*! \brief second of "urn:schemas-upnp-org:service:WANIPConnection:1"
+	 * or "urn:schemas-upnp-org:service:WANPPPConnection:1" */
+	struct IGDdatas_service second;
+	/*! \brief "urn:schemas-upnp-org:service:WANIPv6FirewallControl:1" */
+	struct IGDdatas_service IPv6FC;
+	/*! \brief currently parsed service */
+	struct IGDdatas_service tmp;
+};
+
+/*!
+ * \brief XML start element handler
+ */
+void IGDstartelt(void *, const char *, int);
+/*!
+ * \brief XML end element handler
+ */
+void IGDendelt(void *, const char *, int);
+/*!
+ * \brief XML characted data handler
+ */
+void IGDdata(void *, const char *, int);
+#ifdef DEBUG
+void printIGD(struct IGDdatas *);
+#endif /* DEBUG */
+
+#endif /* IGD_DESC_PARSE_H_INCLUDED */

miniupnpc-2.3.2/include/miniupnpc.h

@@ -0,0 +1,303 @@
+/* $Id: miniupnpc.h,v 1.76 2025/03/05 10:35:57 nanard Exp $ */
+/* vim: tabstop=4 shiftwidth=4 noexpandtab
+ * Project: miniupnp
+ * http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/
+ * Author: Thomas Bernard
+ * Copyright (c) 2005-2025 Thomas Bernard
+ * This software is subjects to the conditions detailed
+ * in the LICENCE file provided within this distribution */
+#ifndef MINIUPNPC_H_INCLUDED
+#define MINIUPNPC_H_INCLUDED
+
+/*! \file miniupnpc.h
+ * \brief Main C API for MiniUPnPc
+ *
+ * Contains functions to discover devices and check for device validity
+ * or connectivity.
+ *
+ * \mainpage MiniUPnPc API documentation
+ * MiniUPnPc (MiniUPnP client) is a library implementing a UPnP
+ * Internet Gateway Device (IGD) control point.
+ *
+ * It should be used by applications that needs to listen to incoming
+ * traffic from the internet which are running on a LAN where a
+ * UPnP IGD is running on the router (or gateway).
+ *
+ * See more documentation on the website http://miniupnp.free.fr
+ * or https://miniupnp.tuxfamily.org/ or GitHub :
+ * https://github.com/miniupnp/miniupnp/tree/master/miniupnpc
+ */
+#include "miniupnpc_declspec.h"
+#include "igd_desc_parse.h"
+#include "upnpdev.h"
+
+/* error codes : */
+/*! \brief value for success */
+#define UPNPDISCOVER_SUCCESS (0)
+/*! \brief value for unknown error */
+#define UPNPDISCOVER_UNKNOWN_ERROR (-1)
+/*! \brief value for a socket error */
+#define UPNPDISCOVER_SOCKET_ERROR (-101)
+/*! \brief value for a memory allocation error */
+#define UPNPDISCOVER_MEMORY_ERROR (-102)
+
+/*! \brief software version */
+#define MINIUPNPC_VERSION	"2.3.2"
+/*! \brief C API version */
+#define MINIUPNPC_API_VERSION	20
+
+/*! \brief any (ie system chosen) port */
+#define UPNP_LOCAL_PORT_ANY     0
+/*! \brief Use as an alias for 1900 for backwards compatibility */
+#define UPNP_LOCAL_PORT_SAME    1
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Structures definitions : */
+
+/*!
+ * \brief UPnP method argument
+ */
+struct UPNParg {
+	const char * elt;	/*!< \brief UPnP argument name */
+	const char * val;	/*!< \brief UPnP argument value */
+};
+
+/*!
+ * \brief execute a UPnP method (SOAP action)
+ *
+ * \param[in] url Control URL for the service
+ * \param[in] service service to use
+ * \param[in] action action to call
+ * \param[in] args action arguments
+ * \param[out] bufsize the size of the returned buffer
+ * \return NULL in case of error or the raw XML response
+ */
+char *
+simpleUPnPcommand(const char * url, const char * service,
+                  const char * action, const struct UPNParg * args,
+                  int * bufsize);
+
+/*!
+ * \brief Discover UPnP IGD on the network.
+ *
+ * The discovered devices are returned as a chained list.
+ * It is up to the caller to free the list with freeUPNPDevlist().
+ * If available, device list will be obtained from MiniSSDPd.
+ *
+ * \param[in] delay (in millisecond) maximum time for waiting any device
+ *            response
+ * \param[in] multicastif If not NULL, used instead of the default
+ *            multicast interface for sending SSDP discover packets
+ * \param[in] minissdpdsock Path to minissdpd socket, default is used if
+ *            NULL
+ * \param[in] localport Source port to send SSDP packets.
+ *            #UPNP_LOCAL_PORT_SAME for 1900 (same as destination port)
+ *            #UPNP_LOCAL_PORT_ANY to let system assign a source port
+ * \param[in] ipv6 0 for IPv4, 1 of IPv6
+ * \param[in] ttl should default to 2 as advised by UDA 1.1
+ * \param[out] error error code when NULL is returned
+ * \return NULL or a linked list
+ */
+MINIUPNP_LIBSPEC struct UPNPDev *
+upnpDiscover(int delay, const char * multicastif,
+             const char * minissdpdsock, int localport,
+             int ipv6, unsigned char ttl,
+             int * error);
+
+/*!
+ * \brief Discover all UPnP devices on the network
+ *
+ * search for "ssdp:all"
+ * \param[in] delay (in millisecond) maximum time for waiting any device
+ *            response
+ * \param[in] multicastif If not NULL, used instead of the default
+ *            multicast interface for sending SSDP discover packets
+ * \param[in] minissdpdsock Path to minissdpd socket, default is used if
+ *            NULL
+ * \param[in] localport Source port to send SSDP packets.
+ *            #UPNP_LOCAL_PORT_SAME for 1900 (same as destination port)
+ *            #UPNP_LOCAL_PORT_ANY to let system assign a source port
+ * \param[in] ipv6 0 for IPv4, 1 of IPv6
+ * \param[in] ttl should default to 2 as advised by UDA 1.1
+ * \param[out] error error code when NULL is returned
+ * \return NULL or a linked list
+ */
+MINIUPNP_LIBSPEC struct UPNPDev *
+upnpDiscoverAll(int delay, const char * multicastif,
+                const char * minissdpdsock, int localport,
+                int ipv6, unsigned char ttl,
+                int * error);
+
+/*!
+ * \brief Discover one type of UPnP devices
+ *
+ * \param[in] device device type to search
+ * \param[in] delay (in millisecond) maximum time for waiting any device
+ *            response
+ * \param[in] multicastif If not NULL, used instead of the default
+ *            multicast interface for sending SSDP discover packets
+ * \param[in] minissdpdsock Path to minissdpd socket, default is used if
+ *            NULL
+ * \param[in] localport Source port to send SSDP packets.
+ *            #UPNP_LOCAL_PORT_SAME for 1900 (same as destination port)
+ *            #UPNP_LOCAL_PORT_ANY to let system assign a source port
+ * \param[in] ipv6 0 for IPv4, 1 of IPv6
+ * \param[in] ttl should default to 2 as advised by UDA 1.1
+ * \param[out] error error code when NULL is returned
+ * \return NULL or a linked list
+ */
+MINIUPNP_LIBSPEC struct UPNPDev *
+upnpDiscoverDevice(const char * device, int delay, const char * multicastif,
+                const char * minissdpdsock, int localport,
+                int ipv6, unsigned char ttl,
+                int * error);
+
+/*!
+ * \brief Discover one or several type of UPnP devices
+ *
+ * \param[in] deviceTypes array of device types to search (ending with NULL)
+ * \param[in] delay (in millisecond) maximum time for waiting any device
+ *            response
+ * \param[in] multicastif If not NULL, used instead of the default
+ *            multicast interface for sending SSDP discover packets
+ * \param[in] minissdpdsock Path to minissdpd socket, default is used if
+ *            NULL
+ * \param[in] localport Source port to send SSDP packets.
+ *            #UPNP_LOCAL_PORT_SAME for 1900 (same as destination port)
+ *            #UPNP_LOCAL_PORT_ANY to let system assign a source port
+ * \param[in] ipv6 0 for IPv4, 1 of IPv6
+ * \param[in] ttl should default to 2 as advised by UDA 1.1
+ * \param[out] error error code when NULL is returned
+ * \param[in] searchalltypes 0 to stop with the first type returning results
+ * \return NULL or a linked list
+ */
+MINIUPNP_LIBSPEC struct UPNPDev *
+upnpDiscoverDevices(const char * const deviceTypes[],
+                    int delay, const char * multicastif,
+                    const char * minissdpdsock, int localport,
+                    int ipv6, unsigned char ttl,
+                    int * error,
+                    int searchalltypes);
+
+/*!
+ * \brief parse root XML description of a UPnP device
+ *
+ * fill the IGDdatas structure.
+ * \param[in] buffer character buffer containing the XML description
+ * \param[in] bufsize size in bytes of the buffer
+ * \param[out] data IGDdatas structure to fill
+ */
+MINIUPNP_LIBSPEC void parserootdesc(const char * buffer, int bufsize, struct IGDdatas * data);
+
+/*!
+ * \brief structure used to get fast access to urls
+ */
+struct UPNPUrls {
+	/*! \brief controlURL of the WANIPConnection */
+	char * controlURL;
+	/*! \brief url of the description of the WANIPConnection */
+	char * ipcondescURL;
+	/*! \brief controlURL of the WANCommonInterfaceConfig */
+	char * controlURL_CIF;
+	/*! \brief controlURL of the WANIPv6FirewallControl */
+	char * controlURL_6FC;
+	/*! \brief url of the root description */
+	char * rootdescURL;
+};
+
+/*! \brief NO IGD found */
+#define UPNP_NO_IGD (0)
+/*! \brief valid and connected IGD */
+#define UPNP_CONNECTED_IGD (1)
+/*! \brief valid and connected IGD but with a reserved address
+ * (non routable) */
+#define UPNP_PRIVATEIP_IGD (2)
+/*! \brief valid but not connected IGD */
+#define UPNP_DISCONNECTED_IGD (3)
+/*! \brief UPnP device not recognized as an IGD */
+#define UPNP_UNKNOWN_DEVICE (4)
+
+/*!
+ * \brief look for a valid and possibly connected IGD in the list
+ *
+ * In any non zero return case, the urls and data structures
+ * passed as parameters are set. Donc forget to call FreeUPNPUrls(urls) to
+ * free allocated memory.
+ * \param[in] devlist A device list obtained with upnpDiscover() /
+ *            upnpDiscoverAll() / upnpDiscoverDevice() / upnpDiscoverDevices()
+ * \param[out] urls Urls for the IGD found
+ * \param[out] data datas for the IGD found
+ * \param[out] lanaddr buffer to copy the local address of the host to reach the IGD
+ * \param[in] lanaddrlen size of the lanaddr buffer
+ * \param[out] wanaddr buffer to copy the public address of the IGD
+ * \param[in] wanaddrlen size of the wanaddr buffer
+ * \return #UPNP_NO_IGD / #UPNP_CONNECTED_IGD / #UPNP_PRIVATEIP_IGD /
+ *         #UPNP_DISCONNECTED_IGD / #UPNP_UNKNOWN_DEVICE
+ */
+MINIUPNP_LIBSPEC int
+UPNP_GetValidIGD(struct UPNPDev * devlist,
+                 struct UPNPUrls * urls,
+                 struct IGDdatas * data,
+                 char * lanaddr, int lanaddrlen,
+                 char * wanaddr, int wanaddrlen);
+
+/*!
+ * \brief Get IGD URLs and data for URL
+ *
+ * Used when skipping the discovery process.
+ * \param[in] rootdescurl Root description URL of the device
+ * \param[out] urls Urls for the IGD found
+ * \param[out] data datas for the IGD found
+ * \param[out] lanaddr buffer to copy the local address of the host to reach the IGD
+ * \param[in] lanaddrlen size of the lanaddr buffer
+ * \return 0 Not ok / 1 OK
+ */
+MINIUPNP_LIBSPEC int
+UPNP_GetIGDFromUrl(const char * rootdescurl,
+                   struct UPNPUrls * urls,
+                   struct IGDdatas * data,
+                   char * lanaddr, int lanaddrlen);
+
+/*!
+ * \brief Prepare the URLs for usage
+ *
+ * build absolute URLs from the root description
+ * \param[out] urls URL structure to initialize
+ * \param[in] data datas for the IGD
+ * \param[in] descURL root description URL for the IGD
+ * \param[in] scope_id if not 0, add the scope to the linklocal IPv6
+ *            addresses in URLs
+ */
+MINIUPNP_LIBSPEC void
+GetUPNPUrls(struct UPNPUrls * urls, struct IGDdatas * data,
+            const char * descURL, unsigned int scope_id);
+
+/*!
+ * \brief free the members of a UPNPUrls struct
+ *
+ * All URLs buffers are freed and zeroed
+ * \param[out] urls
+ */
+MINIUPNP_LIBSPEC void
+FreeUPNPUrls(struct UPNPUrls * urls);
+
+/*!
+ * \brief check the current connection status of an IGD
+ *
+ * it uses UPNP_GetStatusInfo()
+ * \param[in] urls IGD URLs
+ * \param[in] data IGD data
+ * \return 1 Connected / 0 Disconnected
+ */
+MINIUPNP_LIBSPEC int UPNPIGD_IsConnected(struct UPNPUrls * urls, struct IGDdatas * data);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+

{miniupnpc-2.3.0 → miniupnpc-2.3.2}/include/miniupnpc_declspec.h

@@ -1,6 +1,8 @@
 #ifndef MINIUPNPC_DECLSPEC_H_INCLUDED
 #define MINIUPNPC_DECLSPEC_H_INCLUDED
 
+/*! \file miniupnpc_declspec.h
+ * \brief define #MINIUPNP_LIBSPEC for dll exports and imports */
 #if defined(_WIN32) && !defined(MINIUPNP_STATICLIB)
 	/* for windows dll */
 	#ifdef MINIUPNP_EXPORTS
@@ -18,4 +20,3 @@
 #endif
 
 #endif /* MINIUPNPC_DECLSPEC_H_INCLUDED */
-

miniupnpc-2.3.2/include/miniupnpctypes.h

@@ -0,0 +1,27 @@
+/* $Id: miniupnpctypes.h,v 1.4 2025/02/08 23:15:16 nanard Exp $ */
+/* Project: miniupnp
+ * http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org
+ * Author: Thomas Bernard
+ * Copyright (c) 2021-2025 Thomas Bernard
+ * This software is subject to the conditions detailed in the
+ * LICENCE file provided within this distribution */
+#ifndef MINIUPNPCTYPES_H_INCLUDED
+#define MINIUPNPCTYPES_H_INCLUDED
+
+/*! \file miniupnpctypes.h
+ * \brief type definitions
+ *
+ * Use unsigned long long when available :
+ * strtoull is C99
+ *
+ * \def UNSIGNED_INTEGER
+ * \brief `unsigned long long` or `unsigned int`
+ * \todo int can be 16 bits, so it should be `unsigned long`
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define UNSIGNED_INTEGER unsigned long long
+#else
+#define UNSIGNED_INTEGER unsigned int
+#endif
+
+#endif

miniupnpc-2.3.2/include/miniwget.h

@@ -0,0 +1,54 @@
+/* $Id: miniwget.h,v 1.14 2025/02/08 23:15:17 nanard Exp $ */
+/* Project : miniupnp
+ * Author : Thomas Bernard
+ * http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/
+ * Copyright (c) 2005-2025 Thomas Bernard
+ * This software is subject to the conditions detailed in the
+ * LICENCE file provided in this distribution.
+ * */
+#ifndef MINIWGET_H_INCLUDED
+#define MINIWGET_H_INCLUDED
+
+/*! \file miniwget.h
+ * \brief Lightweight HTTP client API
+ */
+#include "miniupnpc_declspec.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*! \brief perform HTTP GET on an URL
+ *
+ * \param[in] url HTTP URL to GET
+ * \param[out] size length of the returned buffer. -1 in case of memory
+ *             allocation error
+ * \param[in] scope_id interface id for IPv6 to use if not specified in the URL
+ * \param[out] status_code HTTP response status code (200, 404, etc.)
+ * \return the body of the HTTP response
+ */
+MINIUPNP_LIBSPEC void * miniwget(const char * url, int * size,
+                                 unsigned int scope_id, int * status_code);
+
+/*! \brief perform HTTP GET on an URL
+ *
+ * Also get the local address used to reach the HTTP server
+ *
+ * \param[in] url HTTP URL to GET
+ * \param[out] size length of the returned buffer. -1 in case of memory
+ *             allocation error
+ * \param[out] addr local address used to connect to the server
+ * \param[in] addrlen size of the addr buffer
+ * \param[in] scope_id interface id for IPv6 to use if not specified in the URL
+ * \param[out] status_code HTTP response status code (200, 404, etc.)
+ * \return the body of the HTTP response
+ */
+MINIUPNP_LIBSPEC void * miniwget_getaddr(const char * url, int * size,
+                                         char * addr, int addrlen,
+                                         unsigned int scope_id, int * status_code);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

miniupnpc-2.3.2/include/portlistingparse.h

@@ -0,0 +1,91 @@
+/* $Id: portlistingparse.h,v 1.12 2025/02/08 23:15:17 nanard Exp $ */
+/* MiniUPnP project
+ * http://miniupnp.free.fr/ or http://miniupnp.tuxfamily.org/
+ * (c) 2011-2025 Thomas Bernard
+ * This software is subject to the conditions detailed
+ * in the LICENCE file provided within the distribution */
+#ifndef PORTLISTINGPARSE_H_INCLUDED
+#define PORTLISTINGPARSE_H_INCLUDED
+
+/*! \file portlistingparse.h
+ * \brief Parsing of the list of port mappings
+ *
+ * As returned by GetListOfPortMappings.
+ * Sample of PortMappingEntry :
+ *
+ *     <p:PortMappingEntry>
+ *       <p:NewRemoteHost>202.233.2.1</p:NewRemoteHost>
+ *       <p:NewExternalPort>2345</p:NewExternalPort>
+ *       <p:NewProtocol>TCP</p:NewProtocol>
+ *       <p:NewInternalPort>2345</p:NewInternalPort>
+ *       <p:NewInternalClient>192.168.1.137</p:NewInternalClient>
+ *       <p:NewEnabled>1</p:NewEnabled>
+ *       <p:NewDescription>dooom</p:NewDescription>
+ *       <p:NewLeaseTime>345</p:NewLeaseTime>
+ *     </p:PortMappingEntry>
+ */
+#include "miniupnpc_declspec.h"
+/* for the definition of UNSIGNED_INTEGER */
+#include "miniupnpctypes.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+ * \brief enum of all XML elements
+ */
+typedef enum { PortMappingEltNone,
+       PortMappingEntry, NewRemoteHost,
+       NewExternalPort, NewProtocol,
+       NewInternalPort, NewInternalClient,
+       NewEnabled, NewDescription,
+       NewLeaseTime } portMappingElt;
+
+/*!
+ * \brief linked list of port mappings
+ */
+struct PortMapping {
+	struct PortMapping * l_next;	/*!< \brief next list element */
+	UNSIGNED_INTEGER leaseTime;	/*!< \brief in seconds */
+	unsigned short externalPort;	/*!< \brief external port */
+	unsigned short internalPort;	/*!< \brief internal port */
+	char remoteHost[64];	/*!< \brief empty for wildcard */
+	char internalClient[64];	/*!< \brief internal IP address */
+	char description[64];	/*!< \brief description */
+	char protocol[4];		/*!< \brief `TCP` or `UDP` */
+	unsigned char enabled;	/*!< \brief 0 (false) or 1 (true) */
+};
+
+/*!
+ * \brief structure for ParsePortListing()
+ */
+struct PortMappingParserData {
+	struct PortMapping * l_head;	/*!< \brief list head */
+	portMappingElt curelt;			/*!< \brief currently parsed element */
+};
+
+/*!
+ * \brief parse the NewPortListing part of GetListOfPortMappings response
+ *
+ * \param[in] buffer XML data
+ * \param[in] bufsize length of XML data
+ * \param[out] pdata Parsed data
+ */
+MINIUPNP_LIBSPEC void
+ParsePortListing(const char * buffer, int bufsize,
+                 struct PortMappingParserData * pdata);
+
+/*!
+ * \brief free parsed data structure
+ *
+ * \param[in] pdata Parsed data to free
+ */
+MINIUPNP_LIBSPEC void
+FreePortListing(struct PortMappingParserData * pdata);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif