Re-resolve the STUN address if a STUN poll fails for res_stun_monitor.

The STUN socket must remain open between polls or the external address
seen by the STUN server is likely to change.  However, if the STUN request
poll fails then the STUN server address needs to be re-resolved and the
STUN socket needs to be closed and reopened.

* Re-resolve the STUN server address and create a new socket if the STUN
request poll fails.

* Fix ast_stun_request() return value consistency.

* Fix ast_stun_request() to check the received packet for expected message
type and transaction ID.

* Fix ast_stun_request() to read packets until timeout or an associated
response packet is found.  The stun_purge_socket() hack is no longer
required.

* Reduce ast_stun_request() error messages to debug output.

* No longer pass in the destination address to ast_stun_request() if the
socket is already bound or connected to the destination.

(closes issue ASTERISK-18327)
Reported by: Wolfram Joost
Tested by: rmudgett

Review: https://reviewboard.asterisk.org/r/1595/
........

Merged revisions 346700 from http://svn.asterisk.org/svn/asterisk/branches/1.8
........

Merged revisions 346701 from http://svn.asterisk.org/svn/asterisk/branches/10


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@346709 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 34 insertions, 9 deletions

diff --git a/include/asterisk/stun.h b/include/asterisk/stun.h
index 1fda0c33d..f0f9d0e34 100644
--- a/include/asterisk/stun.h
+++ b/include/asterisk/stun.h
@@ -41,28 +41,53 @@ enum ast_stun_result {
 
 struct stun_attr;
 
-/*! \brief Generic STUN request
- * send a generic stun request to the server specified.
- * \param s the socket used to send the request
- * \param dst the address of the STUN server
- * \param username if non null, add the username in the request
- * \param answer if non null, the function waits for a response and
+/*!
+ * \brief Generic STUN request.
+ *
+ * \param s The socket used to send the request.
+ * \param dst If non null, the address of the STUN server.
+ *    Only needed if the socket is not bound or connected.
+ * \param username If non null, add the username in the request.
+ * \param answer If non null, the function waits for a response and
  *    puts here the externally visible address.
- * \return 0 on success, other values on error.
- * The interface it may change in the future.
+ *
+ * \details
+ * Send a generic STUN request to the server specified, possibly
+ * waiting for a reply and filling the answer parameter with the
+ * externally visible address.  Note that in this case the
+ * request will be blocking.
+ *
+ * \note The interface may change slightly in the future.
+ *
+ * \retval 0 on success.
+ * \retval <0 on error.
+ * \retval >0 on timeout.
  */
 int ast_stun_request(int s, struct sockaddr_in *dst, const char *username, struct sockaddr_in *answer);
 
 /*! \brief callback type to be invoked on stun responses. */
 typedef int (stun_cb_f)(struct stun_attr *attr, void *arg);
 
-/*! \brief handle an incoming STUN message.
+/*!
+ * \brief handle an incoming STUN message.
  *
+ * \param s Socket to send any response to.
+ * \param src Address where packet came from.
+ * \param data STUN packet buffer to process.
+ * \param len Length of packet
+ * \param stun_cb If not NULL, callback for each STUN attribute.
+ * \param arg Arg to pass to callback.
+ *
+ * \details
  * Do some basic sanity checks on packet size and content,
  * try to extract a bit of information, and possibly reply.
  * At the moment this only processes BIND requests, and returns
  * the externally visible address of the request.
  * If a callback is specified, invoke it with the attribute.
+ *
+ * \retval AST_STUN_ACCEPT if responed to a STUN request
+ * \retval AST_STUN_IGNORE
+ * \retval -1 on error
  */
 int ast_stun_handle_packet(int s, struct sockaddr_in *src, unsigned char *data, size_t len, stun_cb_f *stun_cb, void *arg);