1/* $Id: upnpcommands.h,v 1.36 2025/03/18 23:40:15 nanard Exp $ */
2/* vim: tabstop=4 shiftwidth=4 noexpandtab
3 * Project: miniupnp
4 * http://miniupnp.free.fr/ or https://miniupnp.tuxfamily.org/
5 * Author: Thomas Bernard
6 * Copyright (c) 2005-2025 Thomas Bernard
7 * This software is subject to the conditions detailed in the
8 * LICENCE file provided within this distribution */
9#ifndef UPNPCOMMANDS_H_INCLUDED
10#define UPNPCOMMANDS_H_INCLUDED
11
12/*! \file upnpcommands.h
13 * \brief Internet Gateway Device methods
14 *
15 * See the documentation for both IGD v1 and IGD v2 :
16 * - https://upnp.org/specs/gw/UPnP-gw-InternetGatewayDevice-v1-Device.pdf
17 * - https://upnp.org/specs/gw/UPnP-gw-InternetGatewayDevice-v2-Device.pdf
18 *
19 * The methods are from WANIPConnection:1 or 2, WANCommonInterfaceConfig:1,
20 * and WANIPv6FirewallControl:1
21 *
22 */
23
24#include "miniupnpc_declspec.h"
25#include "miniupnpctypes.h"
26
27/* MiniUPnPc return codes : */
28/*! \brief value for success */
29#define UPNPCOMMAND_SUCCESS (0)
30/*! \brief value for unknown error */
31#define UPNPCOMMAND_UNKNOWN_ERROR (-1)
32/*! \brief error while checking the arguments */
33#define UPNPCOMMAND_INVALID_ARGS (-2)
34/*! \brief HTTP communication error */
35#define UPNPCOMMAND_HTTP_ERROR (-3)
36/*! \brief The response contains invalid values */
37#define UPNPCOMMAND_INVALID_RESPONSE (-4)
38/*! \brief Memory allocation error */
39#define UPNPCOMMAND_MEM_ALLOC_ERROR (-5)
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45struct PortMappingParserData;
46
47/*! \brief WANCommonInterfaceConfig:GetTotalBytesSent
48 *
49 * Note: this is a 32bits unsigned value and rolls over to 0 after reaching
50 * the maximum value
51 *
52 * \param[in] controlURL controlURL of the WANCommonInterfaceConfig of
53 * a WANDevice
54 * \param[in] servicetype urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
55 */
56MINIUPNP_LIBSPEC UNSIGNED_INTEGER
57UPNP_GetTotalBytesSent(const char * controlURL,
58 const char * servicetype);
59
60/*! \brief WANCommonInterfaceConfig:GetTotalBytesReceived
61 *
62 * Note: this is a 32bits unsigned value and rolls over to 0 after reaching
63 * the maximum value
64 *
65 * \param[in] controlURL controlURL of the WANCommonInterfaceConfig of a WANDevice
66 * \param[in] servicetype urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
67 */
68MINIUPNP_LIBSPEC UNSIGNED_INTEGER
69UPNP_GetTotalBytesReceived(const char * controlURL,
70 const char * servicetype);
71
72/*! \brief WANCommonInterfaceConfig:GetTotalPacketsSent
73 *
74 * Note: this is a 32bits unsigned value and rolls over to 0 after reaching
75 * the maximum value
76 *
77 * \param[in] controlURL controlURL of the WANCommonInterfaceConfig of a WANDevice
78 * \param[in] servicetype urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
79 */
80MINIUPNP_LIBSPEC UNSIGNED_INTEGER
81UPNP_GetTotalPacketsSent(const char * controlURL,
82 const char * servicetype);
83
84/*! \brief WANCommonInterfaceConfig:GetTotalBytesReceived
85 *
86 * Note: this is a 32bits unsigned value and rolls over to 0 after reaching
87 * the maximum value
88 *
89 * \param[in] controlURL controlURL of the WANCommonInterfaceConfig of a WANDevice
90 * \param[in] servicetype urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
91 */
92MINIUPNP_LIBSPEC UNSIGNED_INTEGER
93UPNP_GetTotalPacketsReceived(const char * controlURL,
94 const char * servicetype);
95
96/*! \brief WANIPConnection:GetStatusInfo()
97 *
98 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
99 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
100 * \param[out] status 64 bytes buffer : `Unconfigured`, `Connecting`,
101 * `Connected`, `PendingDisconnect`, `Disconnecting`, `Disconnected`
102 * \param[out] uptime time in seconds
103 * \param[out] lastconnerror 64 bytes buffer : `ERROR_NONE`,
104 * `ERROR_COMMAND_ABORTED`, `ERROR_NOT_ENABLED_FOR_INTERNET`,
105 * `ERROR_USER_DISCONNECT`, `ERROR_ISP_DISCONNECT`,
106 * `ERROR_IDLE_DISCONNECT`, `ERROR_FORCED_DISCONNECT`,
107 * `ERROR_NO_CARRIER`, `ERROR_IP_CONFIGURATION`, `ERROR_UNKNOWN`
108 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
109 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error code
110 */
111MINIUPNP_LIBSPEC int
112UPNP_GetStatusInfo(const char * controlURL,
113 const char * servicetype,
114 char * status,
115 unsigned int * uptime,
116 char * lastconnerror);
117
118/*! \brief WANIPConnection:GetConnectionTypeInfo()
119 *
120 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
121 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
122 * \param[out] connectionType 64 characters buffer : `Unconfigured`,
123 * `IP_Routed`, `IP_Bridged`
124 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
125 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error code
126 */
127MINIUPNP_LIBSPEC int
128UPNP_GetConnectionTypeInfo(const char * controlURL,
129 const char * servicetype,
130 char * connectionType);
131
132/*! \brief WANIPConnection:GetExternalIPAddress()
133 *
134 * possible UPnP Errors :
135 * - 402 Invalid Args - See UPnP Device Architecture section on Control.
136 * - 501 Action Failed - See UPnP Device Architecture section on Control.
137 *
138 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
139 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
140 * \param[out] extIpAdd 16 bytes buffer
141 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_UNKNOWN_ERROR,
142 * #UPNPCOMMAND_INVALID_ARGS, #UPNPCOMMAND_HTTP_ERROR or an
143 * UPnP error code
144 */
145MINIUPNP_LIBSPEC int
146UPNP_GetExternalIPAddress(const char * controlURL,
147 const char * servicetype,
148 char * extIpAdd);
149
150/*! \brief UPNP_GetLinkLayerMaxBitRates()
151 * call `WANCommonInterfaceConfig:GetCommonLinkProperties`
152 *
153 * \param[in] controlURL controlURL of the WANCommonInterfaceConfig of a WANDevice
154 * \param[in] servicetype urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
155 * \param[out] bitrateDown bits per second
156 * \param[out] bitrateUp bits per second
157 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
158 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error Code.
159 */
160MINIUPNP_LIBSPEC int
161UPNP_GetLinkLayerMaxBitRates(const char* controlURL,
162 const char* servicetype,
163 unsigned int * bitrateDown,
164 unsigned int * bitrateUp);
165
166/*! \brief WANIPConnection:AddPortMapping()
167 *
168 * List of possible UPnP errors for AddPortMapping :
169 * errorCode errorDescription (short) | Description (long)
170 * ---------------------------------- | -----------------
171 * 402 Invalid Args | See UPnP Device Architecture section on Control.
172 * 501 Action Failed | See UPnP Device Architecture section on Control.
173 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
174 * 715 WildCardNotPermittedInSrcIP | The source IP address cannot be wild-carded
175 * 716 WildCardNotPermittedInExtPort | The external port cannot be wild-carded
176 * 718 ConflictInMappingEntry | The port mapping entry specified conflicts with a mapping assigned previously to another client
177 * 724 SamePortValuesRequired | Internal and External port values must be the same
178 * 725 OnlyPermanentLeasesSupported | The NAT implementation only supports permanent lease times on port mappings
179 * 726 RemoteHostOnlySupportsWildcard | RemoteHost must be a wildcard and cannot be a specific IP address or DNS name
180 * 727 ExternalPortOnlySupportsWildcard | ExternalPort must be a wildcard and cannot be a specific port value
181 * 728 NoPortMapsAvailable | There are not enough free ports available to complete port mapping.
182 * 729 ConflictWithOtherMechanisms | Attempted port mapping is not allowed due to conflict with other mechanisms.
183 * 732 WildCardNotPermittedInIntPort | The internal port cannot be wild-carded
184 *
185 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
186 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
187 * \param[in] extPort External port
188 * \param[in] inPort Internal port
189 * \param[in] inClient IP of Internal client.
190 * \param[in] desc Port Mapping description. if NULL, defaults to
191 * "libminiupnpc"
192 * \param[in] proto `TCP` or `UDP`
193 * \param[in] remoteHost IP or empty string for wildcard. Most IGD don't
194 * support it
195 * \param[in] leaseDuration between 0 and 604800
196 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
197 * #UPNPCOMMAND_MEM_ALLOC_ERROR, #UPNPCOMMAND_HTTP_ERROR,
198 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP error code.
199 */
200MINIUPNP_LIBSPEC int
201UPNP_AddPortMapping(const char * controlURL, const char * servicetype,
202 const char * extPort,
203 const char * inPort,
204 const char * inClient,
205 const char * desc,
206 const char * proto,
207 const char * remoteHost,
208 const char * leaseDuration);
209
210/*! \brief WANIPConnection:AddAnyPortMapping()
211 *
212 * Only in WANIPConnection:2
213 *
214 * List of possible UPnP errors for AddPortMapping :
215 * errorCode errorDescription (short) | Description (long)
216 * ---------------------------------- | ------------------
217 * 402 Invalid Args | See UPnP Device Architecture section on Control.
218 * 501 Action Failed | See UPnP Device Architecture section on Control.
219 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
220 * 715 WildCardNotPermittedInSrcIP | The source IP address cannot be wild-carded
221 * 716 WildCardNotPermittedInExtPort | The external port cannot be wild-carded
222 * 728 NoPortMapsAvailable | There are not enough free ports available to complete port mapping.
223 * 729 ConflictWithOtherMechanisms | Attempted port mapping is not allowed due to conflict with other mechanisms.
224 * 732 WildCardNotPermittedInIntPort | The internal port cannot be wild-carded
225 *
226 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
227 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:2
228 * \param[in] extPort External port
229 * \param[in] inPort Internal port
230 * \param[in] inClient IP of Internal client.
231 * \param[in] desc Port Mapping description. if NULL, defaults to
232 * "libminiupnpc"
233 * \param[in] proto `TCP` or `UDP`
234 * \param[in] remoteHost IP or empty string for wildcard. Most IGD don't
235 * support it
236 * \param[in] leaseDuration between 0 and 604800
237 * \param[out] reservedPort 6 bytes buffer
238 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
239 * #UPNPCOMMAND_MEM_ALLOC_ERROR, #UPNPCOMMAND_HTTP_ERROR,
240 * #UPNPCOMMAND_INVALID_RESPONSE, #UPNPCOMMAND_UNKNOWN_ERROR
241 * or a UPnP error code.
242 */
243MINIUPNP_LIBSPEC int
244UPNP_AddAnyPortMapping(const char * controlURL, const char * servicetype,
245 const char * extPort,
246 const char * inPort,
247 const char * inClient,
248 const char * desc,
249 const char * proto,
250 const char * remoteHost,
251 const char * leaseDuration,
252 char * reservedPort);
253
254/*! \brief WANIPConnection:DeletePortMapping()
255 *
256 * Use same argument values as what was used for UPNP_AddPortMapping()
257 *
258 * List of possible UPnP errors for UPNP_DeletePortMapping() :
259 * errorCode errorDescription (short) | Description (long)
260 * ---------------------------------- | ------------------
261 * 402 Invalid Args | See UPnP Device Architecture section on Control.
262 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
263 * 714 NoSuchEntryInArray | The specified value does not exist in the array
264 *
265 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
266 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
267 * \param[in] extPort External port
268 * \param[in] proto `TCP` or `UDP`
269 * \param[in] remoteHost IP or empty string for wildcard. Most IGD don't
270 * support it
271 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
272 * #UPNPCOMMAND_MEM_ALLOC_ERROR, #UPNPCOMMAND_HTTP_ERROR,
273 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP error code.
274 */
275MINIUPNP_LIBSPEC int
276UPNP_DeletePortMapping(const char * controlURL, const char * servicetype,
277 const char * extPort, const char * proto,
278 const char * remoteHost);
279
280/*! \brief WANIPConnection:DeletePortRangeMapping()
281 *
282 * Only in WANIPConnection:2
283 * Use same argument values as what was used for AddPortMapping().
284 * remoteHost is usually NULL because IGD don't support it.
285 * Return Values :
286 * 0 : SUCCESS
287 * NON ZERO : error. Either an UPnP error code or an undefined error.
288 *
289 * List of possible UPnP errors for DeletePortMapping :
290 * errorCode errorDescription (short) | Description (long)
291 * ---------------------------------- | ------------------
292 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
293 * 730 PortMappingNotFound | This error message is returned if no port mapping is found in the specified range.
294 * 733 InconsistentParameters | NewStartPort and NewEndPort values are not consistent.
295 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
296 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:2
297 * \param[in] extPortStart External port range start
298 * \param[in] extPortEnd External port range end
299 * \param[in] proto `TCP` or `UDP`
300 * \param[in] manage `0` to remove only the port mappings of this IGD,
301 * `1` to remove port mappings also for other clients
302 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
303 * #UPNPCOMMAND_MEM_ALLOC_ERROR, #UPNPCOMMAND_HTTP_ERROR,
304 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP error code.
305 */
306MINIUPNP_LIBSPEC int
307UPNP_DeletePortMappingRange(const char * controlURL, const char * servicetype,
308 const char * extPortStart, const char * extPortEnd,
309 const char * proto,
310 const char * manage);
311
312/*! \brief WANIPConnection:GetPortMappingNumberOfEntries()
313 *
314 * not supported by all routers
315 *
316 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
317 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
318 * \param[out] numEntries Port mappings count
319 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_HTTP_ERROR,
320 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP error code.
321 */
322MINIUPNP_LIBSPEC int
323UPNP_GetPortMappingNumberOfEntries(const char * controlURL,
324 const char * servicetype,
325 unsigned int * numEntries);
326
327/*! \brief retrieves an existing port mapping for a port:protocol
328 *
329 * List of possible UPnP errors for UPNP_GetSpecificPortMappingEntry() :
330 * errorCode errorDescription (short) | Description (long)
331 * ---------------------------------- | ------------------
332 * 402 Invalid Args | See UPnP Device Architecture section on Control.
333 * 501 Action Failed | See UPnP Device Architecture section on Control.
334 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
335 * 714 NoSuchEntryInArray | The specified value does not exist in the array.
336 *
337 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
338 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
339 * \param[in] extPort External port
340 * \param[in] proto `TCP` or `UDP`
341 * \param[in] remoteHost IP or empty string for wildcard. Most IGD don't
342 * support it
343 * \param[out] intClient 16 bytes buffer
344 * \param[out] intPort 6 bytes buffer
345 * \param[out] desc 80 bytes buffer
346 * \param[out] enabled 4 bytes buffer
347 * \param[out] leaseDuration 16 bytes
348 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
349 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error Code.
350 */
351MINIUPNP_LIBSPEC int
352UPNP_GetSpecificPortMappingEntry(const char * controlURL,
353 const char * servicetype,
354 const char * extPort,
355 const char * proto,
356 const char * remoteHost,
357 char * intClient,
358 char * intPort,
359 char * desc,
360 char * enabled,
361 char * leaseDuration);
362
363/*! \brief retrieves an existing port mapping for a port:protocol
364 *
365 * List of possible UPnP errors for UPNP_GetSpecificPortMappingEntry() :
366 * errorCode errorDescription (short) | Description (long)
367 * ---------------------------------- | ------------------
368 * 402 Invalid Args | See UPnP Device Architecture section on Control.
369 * 501 Action Failed | See UPnP Device Architecture section on Control.
370 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
371 * 714 NoSuchEntryInArray | The specified value does not exist in the array.
372 *
373 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
374 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
375 * \param[in] extPort External port
376 * \param[in] proto `TCP` or `UDP`
377 * \param[in] remoteHost IP or empty string for wildcard. Most IGD don't
378 * support it
379 * \param[out] intClient 16 bytes buffer
380 * \param[out] intPort 6 bytes buffer
381 * \param[out] desc desclen bytes buffer
382 * \param[in] desclen desc buffer length
383 * \param[out] enabled 4 bytes buffer
384 * \param[out] leaseDuration 16 bytes
385 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
386 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error Code.
387 */
388MINIUPNP_LIBSPEC int
389UPNP_GetSpecificPortMappingEntryExt(const char * controlURL,
390 const char * servicetype,
391 const char * extPort,
392 const char * proto,
393 const char * remoteHost,
394 char * intClient,
395 char * intPort,
396 char * desc,
397 size_t desclen,
398 char * enabled,
399 char * leaseDuration);
400
401/*! \brief WANIPConnection:GetGenericPortMappingEntry()
402 *
403 * errorCode errorDescription (short) | Description (long)
404 * ---------------------------------- | ------------------
405 * 402 Invalid Args | See UPnP Device Architecture section on Control.
406 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
407 * 713 SpecifiedArrayIndexInvalid | The specified array index is out of bounds
408 *
409 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
410 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
411 * \param[in] index
412 * \param[out] extPort 6 bytes buffer
413 * \param[out] intClient 16 bytes buffer
414 * \param[out] intPort 6 bytes buffer
415 * \param[out] protocol 4 bytes buffer
416 * \param[out] desc 80 bytes buffer
417 * \param[out] enabled 4 bytes buffer
418 * \param[out] rHost 64 bytes buffer
419 * \param[out] duration 16 bytes buffer
420 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
421 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error Code.
422 */
423MINIUPNP_LIBSPEC int
424UPNP_GetGenericPortMappingEntry(const char * controlURL,
425 const char * servicetype,
426 const char * index,
427 char * extPort,
428 char * intClient,
429 char * intPort,
430 char * protocol,
431 char * desc,
432 char * enabled,
433 char * rHost,
434 char * duration);
435
436/*! \brief WANIPConnection:GetGenericPortMappingEntry()
437 *
438 * errorCode errorDescription (short) | Description (long)
439 * ---------------------------------- | ------------------
440 * 402 Invalid Args | See UPnP Device Architecture section on Control.
441 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
442 * 713 SpecifiedArrayIndexInvalid | The specified array index is out of bounds
443 *
444 * \param[in] controlURL controlURL of the WANIPConnection of a WANConnectionDevice
445 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:1
446 * \param[in] index
447 * \param[out] extPort 6 bytes buffer
448 * \param[out] intClient 16 bytes buffer
449 * \param[out] intPort 6 bytes buffer
450 * \param[out] protocol 4 bytes buffer
451 * \param[out] desc desclen bytes buffer
452 * \param[in] desclen desc buffer length
453 * \param[out] enabled 4 bytes buffer
454 * \param[out] rHost desclen bytes buffer
455 * \param[in] rHostlen rHost buffer length
456 * \param[out] duration 16 bytes buffer
457 * \return #UPNPCOMMAND_SUCCESS, #UPNPCOMMAND_INVALID_ARGS,
458 * #UPNPCOMMAND_UNKNOWN_ERROR or a UPnP Error Code.
459 */
460MINIUPNP_LIBSPEC int
461UPNP_GetGenericPortMappingEntryExt(const char * controlURL,
462 const char * servicetype,
463 const char * index,
464 char * extPort,
465 char * intClient,
466 char * intPort,
467 char * protocol,
468 char * desc,
469 size_t desclen,
470 char * enabled,
471 char * rHost,
472 size_t rHostlen,
473 char * duration);
474
475/*! \brief retrieval of a list of existing port mappings
476 *
477 * Available in IGD v2 : WANIPConnection:GetListOfPortMappings()
478 *
479 * errorCode errorDescription (short) | Description (long)
480 * ---------------------------------- | ------------------
481 * 606 Action not authorized | The action requested REQUIRES authorization and the sender was not authorized.
482 * 730 PortMappingNotFound | no port mapping is found in the specified range.
483 * 733 InconsistantParameters | NewStartPort and NewEndPort values are not consistent.
484 *
485 * \param[in] controlURL controlURL of the WANIPConnection of a
486 * WANConnectionDevice
487 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPConnection:2
488 * \param[in] startPort port interval start
489 * \param[in] endPort port interval end
490 * \param[in] protocol `TCP` or `UDP`
491 * \param[in] numberOfPorts size limit of the list returned. `0` to request
492 * all port mappings
493 * \param[out] data port mappings list
494 */
495MINIUPNP_LIBSPEC int
496UPNP_GetListOfPortMappings(const char * controlURL,
497 const char * servicetype,
498 const char * startPort,
499 const char * endPort,
500 const char * protocol,
501 const char * numberOfPorts,
502 struct PortMappingParserData * data);
503
504/*! \brief GetFirewallStatus() retrieves whether the firewall is enabled
505 * and pinhole can be created through UPnP
506 *
507 * IGD:2, functions for service WANIPv6FirewallControl:1
508 *
509 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
510 * WANConnectionDevice
511 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
512 * \param[out] firewallEnabled false (0) or true (1)
513 * \param[out] inboundPinholeAllowed false (0) or true (1)
514 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
515 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
516 */
517MINIUPNP_LIBSPEC int
518UPNP_GetFirewallStatus(const char * controlURL,
519 const char * servicetype,
520 int * firewallEnabled,
521 int * inboundPinholeAllowed);
522
523/*! \brief retrieve default value after which automatically created pinholes
524 * expire
525 *
526 * The returned value may be specific to the \p proto, \p remoteHost,
527 * \p remotePort, \p intClient and \p intPort, but this behavior depends
528 * on the implementation of the firewall.
529 *
530 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
531 * WANConnectionDevice
532 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
533 * \param[in] remoteHost
534 * \param[in] remotePort
535 * \param[in] intClient
536 * \param[in] intPort
537 * \param[in] proto `TCP` or `UDP`
538 * \param[out] opTimeout lifetime in seconds of an inbound "automatic"
539 * firewall pinhole created by an outbound traffic initiation.
540 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
541 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
542 */
543MINIUPNP_LIBSPEC int
544UPNP_GetOutboundPinholeTimeout(const char * controlURL,
545 const char * servicetype,
546 const char * remoteHost,
547 const char * remotePort,
548 const char * intClient,
549 const char * intPort,
550 const char * proto,
551 int * opTimeout);
552
553/*! \brief create a new pinhole that allows incoming traffic to pass
554 * through the firewall
555 *
556 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
557 * WANConnectionDevice
558 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
559 * \param[in] remoteHost literal presentation of IPv6 address or domain name.
560 * empty string for wildcard
561 * \param[in] remotePort remote host port. Likely 0 (for wildcard)
562 * \param[in] intClient IP address of internal client. cannot be wildcarded
563 * \param[in] intPort client port. 0 for wildcard
564 * \param[in] proto IP protocol integer (6 for TCP, 17 for UDP, etc.)
565 * 65535 for wildcard.
566 * \param[in] leaseTime in seconds
567 * \param[out] uniqueID 8 bytes buffer
568 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
569 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
570 */
571MINIUPNP_LIBSPEC int
572UPNP_AddPinhole(const char * controlURL, const char * servicetype,
573 const char * remoteHost,
574 const char * remotePort,
575 const char * intClient,
576 const char * intPort,
577 const char * proto,
578 const char * leaseTime,
579 char * uniqueID);
580
581/*! \brief update a pinhole’s lease time
582 *
583 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
584 * WANConnectionDevice
585 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
586 * \param[in] uniqueID value obtained through UPNP_AddPinhole()
587 * \param[in] leaseTime in seconds
588 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
589 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
590 */
591MINIUPNP_LIBSPEC int
592UPNP_UpdatePinhole(const char * controlURL, const char * servicetype,
593 const char * uniqueID,
594 const char * leaseTime);
595
596/*! \brief remove a pinhole
597 *
598 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
599 * WANConnectionDevice
600 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
601 * \param[in] uniqueID value obtained through UPNP_AddPinhole()
602 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
603 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
604 */
605MINIUPNP_LIBSPEC int
606UPNP_DeletePinhole(const char * controlURL,
607 const char * servicetype,
608 const char * uniqueID);
609
610/*! \brief checking if a certain pinhole allows traffic to pass through the firewall
611 *
612 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
613 * WANConnectionDevice
614 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
615 * \param[in] uniqueID value obtained through UPNP_AddPinhole()
616 * \param[out] isWorking `0` for false, `1` for true
617 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
618 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
619 */
620MINIUPNP_LIBSPEC int
621UPNP_CheckPinholeWorking(const char * controlURL, const char * servicetype,
622 const char * uniqueID, int * isWorking);
623
624/*! \brief get the total number of IP packets which have been going through
625 * the specified pinhole
626 * \todo \p packets should be #UNSIGNED_INTEGER
627 * \param[in] controlURL controlURL of the WANIPv6FirewallControl of a
628 * WANConnectionDevice
629 * \param[in] servicetype urn:schemas-upnp-org:service:WANIPv6FirewallControl:1
630 * \param[in] uniqueID value obtained through UPNP_AddPinhole()
631 * \param[out] packets how many IP packets have been going through the
632 * specified pinhole
633 * \return #UPNPCOMMAND_UNKNOWN_ERROR, #UPNPCOMMAND_INVALID_ARGS,
634 * #UPNPCOMMAND_HTTP_ERROR, #UPNPCOMMAND_SUCCESS or an UPnP error code
635 */
636MINIUPNP_LIBSPEC int
637UPNP_GetPinholePackets(const char * controlURL, const char * servicetype,
638 const char * uniqueID, int * packets);
639
640#ifdef __cplusplus
641}
642#endif
643
644#endif
645
646