upnp.h 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  1. /*
  2. * Copyright (C) 2022 Teluu Inc. (http://www.teluu.com)
  3. *
  4. * This program is free software; you can redistribute it and/or modify
  5. * it under the terms of the GNU General Public License as published by
  6. * the Free Software Foundation; either version 2 of the License, or
  7. * (at your option) any later version.
  8. *
  9. * This program is distributed in the hope that it will be useful,
  10. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12. * GNU General Public License for more details.
  13. *
  14. * You should have received a copy of the GNU General Public License
  15. * along with this program; if not, write to the Free Software
  16. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  17. */
  18. #ifndef __PJ_UPNP_H__
  19. #define __PJ_UPNP_H__
  20. /**
  21. * @file upnp.h
  22. * @brief UPnP client.
  23. */
  24. #include <pj/sock.h>
  25. PJ_BEGIN_DECL
  26. /**
  27. * @defgroup PJNATH_UPNP Simple UPnP Client
  28. * @brief A simple UPnP client implementation.
  29. * @{
  30. *
  31. * This is a simple implementation of UPnP client. Its main function
  32. * is to request a port mapping from an Internet Gateway Device (IGD),
  33. * which will redirect communication received on a specified external
  34. * port to a local socket.
  35. */
  36. /**
  37. * This structre describes the parameter to initialize UPnP.
  38. */
  39. typedef struct pj_upnp_init_param
  40. {
  41. /**
  42. * The pool factory where memory will be allocated from.
  43. */
  44. pj_pool_factory *factory;
  45. /**
  46. * The interface name to use for all UPnP operations.
  47. *
  48. * If NULL, the library will use the first suitable interface found.
  49. */
  50. const char *if_name;
  51. /**
  52. * The port number to use for all UPnP operations.
  53. *
  54. * If 0, the library will pick an arbitrary free port.
  55. */
  56. unsigned port;
  57. /**
  58. * The time duration to search for IGD devices (in seconds).
  59. *
  60. * If 0, the library will use PJ_UPNP_DEFAULT_SEARCH_TIME.
  61. */
  62. int search_time;
  63. /**
  64. * The callback to notify application when the initialization
  65. * has completed.
  66. *
  67. * @param status The initialization status.
  68. */
  69. void (*upnp_cb)(pj_status_t status);
  70. } pj_upnp_init_param;
  71. /**
  72. * Initialize UPnP library and initiate the search for valid Internet
  73. * Gateway Devices (IGD) in the network.
  74. *
  75. * @param param The UPnP initialization parameter.
  76. *
  77. * @return PJ_SUCCESS on success, or the appropriate error
  78. * status.
  79. */
  80. PJ_DECL(pj_status_t) pj_upnp_init(const pj_upnp_init_param *param);
  81. /**
  82. * Deinitialize UPnP library.
  83. *
  84. * @return PJ_SUCCESS on success, or the appropriate error
  85. * status.
  86. */
  87. PJ_DECL(pj_status_t) pj_upnp_deinit(void);
  88. /**
  89. * This is the main function to request a port mapping. If successful,
  90. * the Internet Gateway Device will redirect communication received on
  91. * the specified external ports to the local sockets.
  92. *
  93. * @param sock_cnt Number of sockets in the socket array.
  94. * @param sock Array of local UDP sockets that will be mapped.
  95. * @param ext_port (Optional) Array of external port numbers. If NULL,
  96. * the external port numbers requested will be identical
  97. * to the sockets' local port numbers.
  98. * @param mapped_addr Array to receive the mapped public addresses and
  99. * ports of the local UDP sockets, when the function
  100. * returns PJ_SUCCESS.
  101. *
  102. * @return PJ_SUCCESS on success, or the appropriate error
  103. * status.
  104. */
  105. PJ_DECL(pj_status_t)pj_upnp_add_port_mapping(unsigned sock_cnt,
  106. const pj_sock_t sock[],
  107. unsigned ext_port[],
  108. pj_sockaddr mapped_addr[]);
  109. /**
  110. * Send request to delete a port mapping.
  111. *
  112. * @param mapped_addr The public address and external port mapping to
  113. * be deleted.
  114. *
  115. * @return PJ_SUCCESS on success, or the appropriate error
  116. * status.
  117. */
  118. PJ_DECL(pj_status_t)pj_upnp_del_port_mapping(const pj_sockaddr *mapped_addr);
  119. PJ_END_DECL
  120. /**
  121. * @}
  122. */
  123. #endif /* __PJ_UPNP_H__ */