diff options
Diffstat (limited to 'pjlib-util/include')
-rw-r--r-- | pjlib-util/include/pjlib-util.h | 9 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/config.h | 15 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/errno.h | 55 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_doc.h | 100 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_endpoint.h | 85 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_msg.h | 1338 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_server.h | 109 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_simple.h (renamed from pjlib-util/include/pjlib-util/stun.h) | 140 | ||||
-rw-r--r-- | pjlib-util/include/pjlib-util/stun_transaction.h | 205 |
9 files changed, 1984 insertions, 72 deletions
diff --git a/pjlib-util/include/pjlib-util.h b/pjlib-util/include/pjlib-util.h index 38f4ea1a..0f7848a8 100644 --- a/pjlib-util/include/pjlib-util.h +++ b/pjlib-util/include/pjlib-util.h @@ -30,9 +30,16 @@ #include <pjlib-util/md5.h> #include <pjlib-util/resolver.h> #include <pjlib-util/scanner.h> -#include <pjlib-util/stun.h> #include <pjlib-util/xml.h> +/* New STUN */ +#include <pjlib-util/stun_endpoint.h> +#include <pjlib-util/stun_msg.h> +#include <pjlib-util/stun_server.h> +#include <pjlib-util/stun_transaction.h> + +/* Old STUN */ +#include <pjlib-util/stun_simple.h> /** * @addtogroup PJLIB_UTIL diff --git a/pjlib-util/include/pjlib-util/config.h b/pjlib-util/include/pjlib-util/config.h index 7abba3c1..3127a415 100644 --- a/pjlib-util/include/pjlib-util/config.h +++ b/pjlib-util/include/pjlib-util/config.h @@ -191,7 +191,19 @@ */ /** - * Maximum number of attributes in the STUN packet. + * Maximum number of attributes in the STUN packet (for the old STUN + * library). + * + * Default: 16 + */ +#ifndef PJSTUN_MAX_ATTR +# define PJSTUN_MAX_ATTR 16 +#endif + + +/** + * Maximum number of attributes in the STUN packet (for the new STUN + * library). * * Default: 16 */ @@ -199,7 +211,6 @@ # define PJ_STUN_MAX_ATTR 16 #endif - /** * @} */ diff --git a/pjlib-util/include/pjlib-util/errno.h b/pjlib-util/include/pjlib-util/errno.h index fd12d7e7..6d8c0b1f 100644 --- a/pjlib-util/include/pjlib-util/errno.h +++ b/pjlib-util/include/pjlib-util/errno.h @@ -50,12 +50,12 @@ #define PJLIB_UTIL_ESTUNINMSGTYPE (PJLIB_UTIL_ERRNO_START+2) /* 320002 */ /** * @hideinitializer - * Invalid STUN message length. + * Invalid STUN message length */ #define PJLIB_UTIL_ESTUNINMSGLEN (PJLIB_UTIL_ERRNO_START+3) /* 320003 */ /** * @hideinitializer - * STUN attribute length error. + * Invalid STUN attribute length */ #define PJLIB_UTIL_ESTUNINATTRLEN (PJLIB_UTIL_ERRNO_START+4) /* 320004 */ /** @@ -245,6 +245,57 @@ #define PJLIB_UTIL_EDNS_NOTZONE PJ_STATUS_FROM_DNS_RCODE(10)/* 320060 */ +/************************************************************ + * NEW STUN ERROR + ***********************************************************/ +/* Messaging errors */ +/** + * @hideinitializer + * Invalid STUN attribute + */ +#define PJLIB_UTIL_ESTUNINATTR (PJLIB_UTIL_ERRNO_START+110)/* 320110 */ +/** + * @hideinitializer + * Too many STUN attributes. + */ +#define PJLIB_UTIL_ESTUNTOOMANYATTR (PJLIB_UTIL_ERRNO_START+111)/* 320111 */ +/** + * @hideinitializer + * Unknown STUN attribute. + */ +#define PJLIB_UTIL_ESTUNUNKNOWNATTR (PJLIB_UTIL_ERRNO_START+112)/* 320112 */ +/** + * @hideinitializer + * Invalid socket address length. + */ +#define PJLIB_UTIL_ESTUNINADDRLEN (PJLIB_UTIL_ERRNO_START+113)/* 320113 */ +/** + * @hideinitializer + * IPv6 attribute not supported + */ +#define PJLIB_UTIL_ESTUNIPV6NOTSUPP (PJLIB_UTIL_ERRNO_START+113)/* 320113 */ +/** + * @hideinitializer + * Expecting STUN response message. + */ +#define PJLIB_UTIL_ESTUNNOTRESPONSE (PJLIB_UTIL_ERRNO_START+114)/* 320114 */ +/** + * @hideinitializer + * Transaction ID mismatch. + */ +#define PJLIB_UTIL_ESTUNINVALIDID (PJLIB_UTIL_ERRNO_START+115)/* 320115 */ +/** + * @hideinitializer + * Unable to find handler for the request. + */ +#define PJLIB_UTIL_ESTUNNOHANDLER (PJLIB_UTIL_ERRNO_START+116)/* 320116 */ + + +#define PJ_STATUS_FROM_STUN_CODE(code) -1 + + + + /** * @} */ diff --git a/pjlib-util/include/pjlib-util/stun_doc.h b/pjlib-util/include/pjlib-util/stun_doc.h new file mode 100644 index 00000000..612bf1a7 --- /dev/null +++ b/pjlib-util/include/pjlib-util/stun_doc.h @@ -0,0 +1,100 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJ_STUN_SERVER_H__ +#define __PJ_STUN_SERVER_H__ + +/* + * STUN documentation. There is no code here. + */ + +/** + * @defgroup PJLIB_UTIL_STUN STUN and TURN + * @ingroup PJLIB_UTIL + + This is the implementation of STUN/TURN in PJLIB-UTIL library. + + The STUN/TURN implementation in PJLIB-UTIL has the following objectives: + - standard based (of course) + - supports both client and server side STUN/TURN services + - independent (that is, only dependent to pjlib), and general purpose + enough to be used not only by pjsip applications but also by other + types of applications + - must be able to support ICE. + + The STUN/TURN implementation is based on the following standards: + - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-rfc3489bis-05.txt"> + draft-ietf-behave-rfc3489bis-05.txt</A> + - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-02.txt"> + draft-ietf-behave-turn-02.txt</A> + + But as STUN standards are currently defined as work in progress at IETF, + the implementation will be updated as these standards are updated. + + + + @section stun_org_sec Organization + + The implementation consists of the following components. + + @subsection stun_msg_sec Messaging and Parsing + + The lowest layer of the STUN implementation is the @ref PJLIB_UTIL_STUN_MSG + component. This part is responsible for encoding and decoding STUN messages. + + This layer only implements message representation and parsing. In particular, + it does not provide any transport functionalities, therefore it can be used + by different types of applications. + + + + @subsection stun_endpt_sec Endpoint + + The @ref PJLIB_UTIL_STUN_ENDPOINT is used by the library to put together + common settings for all STUN objects. For example, the STUN endpoint has a + reference of timer heap to poll all STUN timers, reference to ioqueue to + poll network events for STUN servers, and some common settings used by + various STUN objects. + + + @subsection stun_clt_tsx_sec Client Transaction + + The @ref PJLIB_UTIL_STUN_TRANSACTION is used to manage outgoing STUN request, + for example to retransmit the request and to notify application about the + completion of the request. + + The @ref PJLIB_UTIL_STUN_TRANSACTION does not use any networking operations, + but instead application must supply the transaction with a callback to + be used by the transaction to send outgoing requests. This way the STUN + transaction is made more generic and can work with different types of + networking codes in application. + + + + @subsection stun_srv_sec Server Components + + The @ref PJLIB_UTIL_STUN_SERVER is used for: + - implementing STUN servers, and/or + - implementing server side STUN handling (for example for ICE). + + */ + + + +#endif /* __PJ_STUN_SERVER_H__ */ + diff --git a/pjlib-util/include/pjlib-util/stun_endpoint.h b/pjlib-util/include/pjlib-util/stun_endpoint.h new file mode 100644 index 00000000..59bcdee1 --- /dev/null +++ b/pjlib-util/include/pjlib-util/stun_endpoint.h @@ -0,0 +1,85 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJ_STUN_ENDPOINT_H__ +#define __PJ_STUN_ENDPOINT_H__ + +/** + * @file stun_endpoint.h + * @brief STUN endpoint. + */ + +#include <pjlib-util/stun_msg.h> + + +PJ_BEGIN_DECL + + +/* **************************************************************************/ +/** + * @defgroup PJLIB_UTIL_STUN_ENDPOINT STUN Endpoint + * @brief Management of incoming and outgoing STUN transactions. + * @ingroup PJLIB_UTIL_STUN + * @{ + */ + +/** + * Opaque declaration for STUN endpoint. STUN endpoint manages client and + * server STUN transactions, and it needs to be initialized before application + * can send or receive STUN messages. + */ +typedef struct pj_stun_endpoint +{ + pj_pool_factory *pf; + pj_ioqueue_t *ioqueue; + pj_timer_heap_t *timer_heap; + unsigned options; + + unsigned rto_msec; + + pj_pool_t *pool; + +} pj_stun_endpoint; + + + +/** + * Create a STUN endpoint instance. + */ +PJ_DECL(pj_status_t) pj_stun_endpt_create(pj_pool_factory *factory, + unsigned options, + pj_ioqueue_t *ioqueue, + pj_timer_heap_t *timer_heap, + pj_stun_endpoint **p_endpt); + +/** + * Destroy STUN endpoint instance. + */ +PJ_DECL(pj_status_t) pj_stun_endpt_destroy(pj_stun_endpoint *endpt); + + +/** + * @} + */ + + +PJ_END_DECL + + +#endif /* __PJ_STUN_ENDPOINT_H__ */ + diff --git a/pjlib-util/include/pjlib-util/stun_msg.h b/pjlib-util/include/pjlib-util/stun_msg.h new file mode 100644 index 00000000..e8a4f1af --- /dev/null +++ b/pjlib-util/include/pjlib-util/stun_msg.h @@ -0,0 +1,1338 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJ_STUN_MSG_H__ +#define __PJ_STUN_MSG_H__ + +/** + * @file stun_msg.h + * @brief STUN message components. + */ + +#include <pjlib-util/types.h> +#include <pj/sock.h> + + +PJ_BEGIN_DECL + + +/* **************************************************************************/ +/** + * @defgroup PJLIB_UTIL_STUN_MSG STUN Message Representation and Parsing + * @brief Low-level representation and parsing of STUN messages. + * @ingroup PJLIB_UTIL_STUN + * @{ + */ + + +/** + * The default initial STUN round-trip time estimation (the RTO value + * in RFC 3489-bis), in miliseconds. + * This value is used to control the STUN request + * retransmit time. The initial value of retransmission interval + * would be set to this value, and will be doubled after each + * retransmission. + */ +#ifndef PJ_STUN_RTO_VALUE +# define PJ_STUN_RTO_VALUE 100 +#endif + + +/** + * The STUN transaction timeout value, in miliseconds. + * After the last retransmission is sent and if no response is received + * after this time, the STUN transaction will be considered to have failed. + * + * The default value is 1600 miliseconds (as per RFC 3489-bis). + */ +#ifndef PJ_STUN_TIMEOUT_VALUE +# define PJ_STUN_TIMEOUT_VALUE 1600 +#endif + + +/** + * Maximum number of STUN retransmission count. + * + * Default: 7 (as per RFC 3489-bis) + */ +#ifndef PJ_STUN_MAX_RETRANSMIT_COUNT +# define PJ_STUN_MAX_RETRANSMIT_COUNT 7 +#endif + + +/** + * Maximum size of STUN message. + */ +#ifndef PJ_STUN_MAX_PKT_LEN +# define PJ_STUN_MAX_PKT_LEN 512 +#endif + + +/** + * Default STUN port as defined by RFC 3489. + */ +#define PJ_STUN_PORT 3478 + +/** + * STUN magic cookie. + */ +#define PJ_STUN_MAGIC 0x2112A442 + + +/** + * STUN method constants. + */ +enum pj_stun_method_e +{ + /** + * STUN Binding method as defined by RFC 3489-bis. + */ + PJ_STUN_BINDING_METHOD = 1, + + /** + * STUN Shared Secret method as defined by RFC 3489-bis. + */ + PJ_STUN_SHARED_SECRET_METHOD = 2, + + /** + * STUN/TURN Allocate method as defined by draft-ietf-behave-turn + */ + PJ_STUN_ALLOCATE_METHOD = 3, + + /** + * STUN/TURN Send Indication as defined by draft-ietf-behave-turn + */ + PJ_STUN_SEND_INDICATION_METHOD = 4, + + /** + * STUN/TURN Data Indication as defined by draft-ietf-behave-turn + */ + PJ_STUN_DATA_INDICATION_METHOD = 5, + + /** + * STUN/TURN Set Active Destination as defined by draft-ietf-behave-turn + */ + PJ_STUN_SET_ACTIVE_DESTINATION_METHOD = 6, + + /** + * STUN/TURN Connect method as defined by draft-ietf-behave-turn + */ + PJ_STUN_CONNECT_METHOD = 7, + + /** + * STUN/TURN Connect Status indication method. + */ + PJ_STUN_CONNECT_STATUS_METHOD = 8 +}; + + +/** + * Retrieve the STUN method from the message-type field of the STUN + * message. + */ +#define PJ_STUN_GET_METHOD(msg_type) ((msg_type) & 0xFEEF) + + +/** + * STUN message classes constants. + */ +enum pj_stun_msg_class_e +{ + /** + * This specifies that the message type is a STUN request message. + */ + PJ_STUN_REQUEST_CLASS = 0, + + /** + * This specifies that the message type is a STUN indication message. + */ + PJ_STUN_INDICATION_CLASS = 1, + + /** + * This specifies that the message type is a STUN successful response. + */ + PJ_STUN_SUCCESS_CLASS = 2, + + /** + * This specifies that the message type is a STUN error response. + */ + PJ_STUN_ERROR_CLASS = 3 +}; + + +/** + * Determine if the message type is a request. + */ +#define PJ_STUN_IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000) + + +/** + * Determine if the message type is a response. + */ +#define PJ_STUN_IS_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0100) + + +/** + * The response bit in the message type. + */ +#define PJ_STUN_RESPONSE_BIT (0x0100) + +/** + * Determine if the message type is an error response. + */ +#define PJ_STUN_IS_ERROR_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0110) + + +/** + * The error response bit in the message type. + */ +#define PJ_STUN_ERROR_RESPONSE_BIT (0x0110) + + +/** + * Determine if the message type is an indication message. + */ +#define PJ_STUN_IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010) + + +/** + * The error response bit in the message type. + */ +#define PJ_STUN_INDICATION_BIT (0x0010) + + +/** + * This enumeration describes STUN message types. + */ +typedef enum pj_stun_msg_type +{ + /** + * STUN BINDING request. + */ + PJ_STUN_BINDING_REQUEST = 0x0001, + + /** + * Successful response to STUN BINDING-REQUEST. + */ + PJ_STUN_BINDING_RESPONSE = 0x0101, + + /** + * Error response to STUN BINDING-REQUEST. + */ + PJ_STUN_BINDING_ERROR_RESPONSE = 0x0111, + + /** + * STUN SHARED-SECRET reqeust. + */ + PJ_STUN_SHARED_SECRET_REQUEST = 0x0002, + + /** + * Successful response to STUN SHARED-SECRET reqeust. + */ + PJ_STUN_SHARED_SECRET_RESPONSE = 0x0102, + + /** + * Error response to STUN SHARED-SECRET reqeust. + */ + PJ_STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112, + + /** + * STUN/TURN Allocate Request + */ + PJ_STUN_ALLOCATE_REQUEST = 0x0003, + + /** + * Successful response to STUN/TURN Allocate Request + */ + PJ_STUN_ALLOCATE_RESPONSE = 0x0103, + + /** + * Failure response to STUN/TURN Allocate Request + */ + PJ_STUN_ALLOCATE_ERROR_RESPONSE = 0x0113, + + /** + * STUN/TURN Send Indication + */ + PJ_STUN_SEND_INDICATION = 0x0004, + + /** + * STUN/TURN Data Indication + */ + PJ_STUN_DATA_INDICATION = 0x0115, + + /** + * STUN/TURN Set Active Destination Request + */ + PJ_STUN_SET_ACTIVE_DESTINATION_REQUEST = 0x0006, + + /** + * STUN/TURN Set Active Destination Response + */ + PJ_STUN_SET_ACTIVE_DESTINATION_RESPONSE = 0x0106, + + /** + * STUN/TURN Set Active Destination Error Response + */ + PJ_STUN_SET_ACTIVE_DESTINATION_ERROR_RESPONSE = 0x0116, + + /** + * STUN/TURN Connect Request + */ + PJ_STUN_CONNECT_REQUEST = 0x0007, + + /** + * STUN/TURN Connect Response + */ + PJ_STUN_CONNECT_RESPONSE = 0x0107, + + /** + * STUN/TURN Connect Error Response + */ + PJ_STUN_CONNECT_ERROR_RESPONSE = 0x0117, + + /** + * STUN/TURN Connect Status Indication + */ + PJ_STUN_CONNECT_STATUS_INDICATION = 0x0118 + + +} pj_stun_msg_type; + + + +/** + * This enumeration describes STUN attribute types. + */ +typedef enum pj_stun_attr_type +{ + PJ_STUN_ATTR_MAPPED_ADDR = 0x0001,/**< MAPPED-ADDRESS. */ + PJ_STUN_ATTR_RESPONSE_ADDR = 0x0002,/**< RESPONSE-ADDRESS (deprcatd)*/ + PJ_STUN_ATTR_CHANGE_REQUEST = 0x0003,/**< CHANGE-REQUEST (deprecated)*/ + PJ_STUN_ATTR_SOURCE_ADDR = 0x0004,/**< SOURCE-ADDRESS (deprecated)*/ + PJ_STUN_ATTR_CHANGED_ADDR = 0x0005,/**< CHANGED-ADDRESS (deprecatd)*/ + PJ_STUN_ATTR_USERNAME = 0x0006,/**< USERNAME attribute. */ + PJ_STUN_ATTR_PASSWORD = 0x0007,/**< PASSWORD attribute. */ + PJ_STUN_ATTR_MESSAGE_INTEGRITY = 0x0008,/**< MESSAGE-INTEGRITY. */ + PJ_STUN_ATTR_ERROR_CODE = 0x0009,/**< ERROR-CODE. */ + PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES = 0x000A,/**< UNKNOWN-ATTRIBUTES. */ + PJ_STUN_ATTR_REFLECTED_FROM = 0x000B,/**< REFLECTED-FROM (deprecatd)*/ + PJ_STUN_ATTR_LIFETIME = 0x000D,/**< LIFETIME attribute. */ + PJ_STUN_ATTR_BANDWIDTH = 0x0010,/**< BANDWIDTH attribute */ + PJ_STUN_ATTR_REMOTE_ADDRESS = 0x0012,/**< REMOTE-ADDRESS attribute */ + PJ_STUN_ATTR_DATA = 0x0013,/**< DATA attribute. */ + PJ_STUN_ATTR_REALM = 0x0014,/**< REALM attribute. */ + PJ_STUN_ATTR_NONCE = 0x0015,/**< NONCE attribute. */ + PJ_STUN_ATTR_RELAY_ADDRESS = 0x0016,/**< RELAY-ADDRESS attribute. */ + PJ_STUN_ATTR_REQUESTED_ADDR_TYPE= 0x0017,/**< REQUESTED-ADDRESS-TYPE */ + PJ_STUN_ATTR_REQUESTED_PORT_PROPS=0x0018,/**< REQUESTED-PORT-PROPS */ + PJ_STUN_ATTR_REQUESTED_TRANSPORT= 0x0019,/**< REQUESTED-TRANSPORT */ + PJ_STUN_ATTR_XOR_MAPPED_ADDRESS = 0x0020,/**< XOR-MAPPED-ADDRESS */ + PJ_STUN_ATTR_TIMER_VAL = 0x0021,/**< TIMER-VAL attribute. */ + PJ_STUN_ATTR_REQUESTED_IP = 0x0022,/**< REQUESTED-IP attribute */ + PJ_STUN_ATTR_XOR_REFLECTED_FROM = 0x0023,/**< XOR-REFLECTED-FROM */ + PJ_STUN_ATTR_PRIORITY = 0x0024,/**< PRIORITY */ + PJ_STUN_ATTR_USE_CANDIDATE = 0x0025,/**< USE-CANDIDATE */ + PJ_STUN_ATTR_XOR_INTERNAL_ADDR = 0x0026,/**< XOR-INTERNAL-ADDRESS */ + + PJ_STUN_ATTR_END_MANDATORY_ATTR, + + PJ_STUN_ATTR_START_EXTENDED_ATTR= 0x8021, + + PJ_STUN_ATTR_FINGERPRINT = 0x8021,/**< FINGERPRINT attribute. */ + PJ_STUN_ATTR_SERVER = 0x8022,/**< SERVER attribute. */ + PJ_STUN_ATTR_ALTERNATE_SERVER = 0x8023,/**< ALTERNATE-SERVER. */ + PJ_STUN_ATTR_REFRESH_INTERVAL = 0x8024,/**< REFRESH-INTERVAL. */ + + PJ_STUN_ATTR_END_EXTENDED_ATTR + +} pj_stun_attr_type; + + +/** + * STUN error codes, which goes into STUN ERROR-CODE attribute. + */ +typedef enum pj_stun_status +{ + PJ_STUN_STATUS_TRY_ALTERNATE = 300, /**< Try Alternate */ + PJ_STUN_STATUS_BAD_REQUEST = 400, /**< Bad Request */ + PJ_STUN_STATUS_UNAUTHORIZED = 401, /**< Unauthorized */ + PJ_STUN_STATUS_UNKNOWN_ATTRIBUTE = 420, /**< Unknown Attribute */ + PJ_STUN_STATUS_STALE_CREDENTIALS = 430, /**< Stale Credentials */ + PJ_STUN_STATUS_INTEGRITY_CHECK_FAILURE = 431, /**< Integrity Chk Fail */ + PJ_STUN_STATUS_MISSING_USERNAME = 432, /**< Missing Username */ + PJ_STUN_STATUS_USE_TLS = 433, /**< Use TLS */ + PJ_STUN_STATUS_MISSING_REALM = 434, /**< Missing Realm */ + PJ_STUN_STATUS_MISSING_NONCE = 435, /**< Missing Nonce */ + PJ_STUN_STATUS_UNKNOWN_USERNAME = 436, /**< Unknown Username */ + PJ_STUN_STATUS_NO_BINDING = 437, /**< No Binding. */ + PJ_STUN_STATUS_STALE_NONCE = 438, /**< Stale Nonce */ + PJ_STUN_STATUS_TRANSITIONING = 439, /**< Transitioning. */ + PJ_STUN_STATUS_WRONG_USERNAME = 441, /**< Wrong Username. */ + PJ_STUN_STATUS_UNSUPP_TRANSPORT_PROTO = 442, /**< Unsupported Transport Protocol */ + PJ_STUN_STATUS_INVALID_IP_ADDR = 443, /**< Invalid IP Address */ + PJ_STUN_STATUS_INVALID_PORT = 444, /**< Invalid Port */ + PJ_STUN_STATUS_OPER_TCP_ONLY = 445, /**< Operation for TCP Only */ + PJ_STUN_STATUS_CONNECTION_FAILURE = 446, /**< Connection Failure */ + PJ_STUN_STATUS_CONNECTION_TIMEOUT = 447, /**< Connection Timeout */ + PJ_STUN_STATUS_SERVER_ERROR = 500, /**< Server Error */ + PJ_STUN_STATUS_GLOBAL_FAILURE = 600 /**< Global Failure */ +} pj_stun_status; + + +/** + * This structure describes STUN message header. A STUN message has the + * following format: + * + * \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |0 0| STUN Message Type | Message Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Magic Cookie | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Transaction ID + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_msg_hdr +{ + /** + * STUN message type, which the first two bits must be zeroes. + */ + pj_uint16_t type; + + /** + * The message length is the size, in bytes, of the message not + * including the 20 byte STUN header. + */ + pj_uint16_t length; + + /** + * The magic cookie is a fixed value, 0x2112A442 (PJ_STUN_MAGIC constant). + * In the previous version of this specification [15] this field was part + * of the transaction ID. + */ + pj_uint32_t magic; + + /** + * The transaction ID is a 96 bit identifier. STUN transactions are + * identified by their unique 96-bit transaction ID. For request/ + * response transactions, the transaction ID is chosen by the STUN + * client and MUST be unique for each new STUN transaction generated by + * that STUN client. The transaction ID MUST be uniformly and randomly + * distributed between 0 and 2**96 - 1. + */ + pj_uint8_t tsx_id[12]; + +} pj_stun_msg_hdr; + + +/** + * This structre describes STUN attribute header. Each attribute is + * TLV encoded, with a 16 bit type, 16 bit length, and variable value. + * Each STUN attribute ends on a 32 bit boundary: + * + * \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Value .... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_attr_hdr +{ + /** + * STUN attribute type. + */ + pj_uint16_t type; + + /** + * The Length refers to the length of the actual useful content of the + * Value portion of the attribute, measured in bytes. The value + * in the Length field refers to the length of the Value part of the + * attribute prior to padding - i.e., the useful content. + */ + pj_uint16_t length; + +} pj_stun_attr_hdr; + + +/** + * This structure describes STUN generic IP address attribute, used for + * example to represent STUN MAPPED-ADDRESS attribute. + * + * The generic IP address attribute indicates the transport address. + * It consists of an eight bit address family, and a sixteen bit port, + * followed by a fixed length value representing the IP address. If the + * address family is IPv4, the address is 32 bits, in network byte + * order. If the address family is IPv6, the address is 128 bits in + * network byte order. + * + * The format of the generic IP address attribute is: + * + * \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |x x x x x x x x| Family | Port | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Address (variable) + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_generic_ip_addr_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * The socket address (as a union) + */ + union { + pj_sockaddr addr; /**< Generic socket address. */ + pj_sockaddr_in ipv4; /**< IPv4 socket address. */ + pj_sockaddr_in6 ipv6; /**< IPv6 socket address. */ + } addr; + +} pj_stun_generic_ip_addr_attr; + + +/** + * This structure represents a generic STUN attributes with no payload, + * and it is used for example by ICE USE-CANDIDATE attribute. + */ +typedef struct pj_stun_empty_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + +} pj_stun_empty_attr; + + +/** + * This structure represents generic STUN string attributes, such as STUN + * USERNAME, PASSWORD, SERVER, REALM, and NONCE attributes. Note that for REALM and + * NONCE attributes, the text MUST be quoted with. + */ +typedef struct pj_stun_generic_string_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * The string value. + */ + pj_str_t value; + +} pj_stun_generic_string_attr; + + +/** + * This structure represents a generic STUN attributes with 32bit (unsigned) + * integer value, such as STUN FINGERPRINT and REFRESH-INTERVAL attributes. + */ +typedef struct pj_stun_generic_uint_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * The 32bit value. + */ + pj_uint32_t value; + +} pj_stun_generic_uint_attr; + + +/** + * This structure represents generic STUN attributes to hold a raw binary + * data. + */ +typedef struct pj_stun_binary_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * Length of the data. + */ + unsigned length; + + /** + * The raw data. + */ + char *data; + +} pj_stun_binary_attr; + + +/** + * This structure describes STUN MESSAGE-INTEGRITY attribute. + * The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [10] of the + * STUN message. The MESSAGE-INTEGRITY attribute can be present in any + * STUN message type. Since it uses the SHA1 hash, the HMAC will be 20 + * bytes. + */ +typedef struct pj_stun_msg_integrity_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * The 20 bytes hmac value. + */ + pj_uint8_t hmac[20]; + +} pj_stun_msg_integrity_attr; + + +/** + * This structure describes STUN FINGERPRINT attribute. The FINGERPRINT + * attribute can be present in all STUN messages. It is computed as + * the CRC-32 of the STUN message up to (but excluding) the FINGERPRINT + * attribute itself, xor-d with the 32 bit value 0x5354554e + */ +typedef struct pj_stun_generic_uint_attr pj_stun_fingerprint_attr; + + +/** + * This structure represents STUN ERROR-CODE attribute. The ERROR-CODE + * attribute is present in the Binding Error Response and Shared Secret + * Error Response. It is a numeric value in the range of 100 to 699 + * plus a textual reason phrase encoded in UTF-8 + * + * \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 0 |Class| Number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reason Phrase (variable) .. + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_error_code_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * The value must be zero. + */ + pj_uint16_t zero; + + /** + * Error class (1-6). + */ + pj_uint8_t err_class; + + /** + * Error number is the error number modulo 100. + */ + pj_uint8_t number; + + /** + * The reason phrase. + */ + pj_str_t reason; + +} pj_stun_error_code_attr; + + +/** + * This describes STUN REALM attribute. + * The REALM attribute is present in requests and responses. It + * contains text which meets the grammar for "realm" as described in RFC + * 3261 [11], and will thus contain a quoted string (including the + * quotes). + */ +typedef struct pj_stun_generic_string_attr pj_stun_realm_attr; + + +/** + * This describes STUN NONCE attribute. + * The NONCE attribute is present in requests and in error responses. + * It contains a sequence of qdtext or quoted-pair, which are defined in + * RFC 3261 [11]. See RFC 2617 [7] for guidance on selection of nonce + * values in a server. + */ +typedef struct pj_stun_generic_string_attr pj_stun_nonce_attr; + + +/** + * This describes STUN UNKNOWN-ATTRIBUTES attribute. + * The UNKNOWN-ATTRIBUTES attribute is present only in an error response + * when the response code in the ERROR-CODE attribute is 420. + * The attribute contains a list of 16 bit values, each of which + * represents an attribute type that was not understood by the server. + * If the number of unknown attributes is an odd number, one of the + * attributes MUST be repeated in the list, so that the total length of + * the list is a multiple of 4 bytes. + */ +typedef struct pj_stun_unknown_attr +{ + /** + * Standard STUN attribute header. + */ + pj_stun_attr_hdr hdr; + + /** + * Number of unknown attributes in the array. + */ + unsigned attr_count; + + /** + * Array of unknown attribute IDs. + */ + pj_uint16_t attrs[PJ_STUN_MAX_ATTR]; + +} pj_stun_unknown_attr; + + +/** + * This structure describes STUN MAPPED-ADDRESS attribute. + * The MAPPED-ADDRESS attribute indicates the mapped transport address. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_mapped_addr_attr; + + +/** + * This describes STUN XOR-MAPPED-ADDRESS attribute (which has the same + * format as STUN MAPPED-ADDRESS attribute). + * The XOR-MAPPED-ADDRESS attribute is present in responses. It + * provides the same information that would present in the MAPPED- + * ADDRESS attribute but because the NAT's public IP address is + * obfuscated through the XOR function, STUN messages are able to pass + * through NATs which would otherwise interfere with STUN. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_xor_mapped_addr_attr; + + +/** + * This describes STUN SERVER attribute. + * The server attribute contains a textual description of the software + * being used by the server, including manufacturer and version number. + * The attribute has no impact on operation of the protocol, and serves + * only as a tool for diagnostic and debugging purposes. The value of + * SERVER is variable length. + */ +typedef struct pj_stun_generic_string_attr pj_stun_server_attr; + + +/** + * This describes STUN ALTERNATE-SERVER attribute. + * The alternate server represents an alternate transport address for a + * different STUN server to try. It is encoded in the same way as + * MAPPED-ADDRESS. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_alt_server_attr; + + +/** + * This describes STUN REFRESH-INTERVAL attribute. + * The REFRESH-INTERVAL indicates the number of milliseconds that the + * server suggests the client should use between refreshes of the NAT + * bindings between the client and server. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_refresh_interval_attr; + + +/** + * This structure describes STUN RESPONSE-ADDRESS attribute. + * The RESPONSE-ADDRESS attribute indicates where the response to a + * Binding Request should be sent. Its syntax is identical to MAPPED- + * ADDRESS. + * + * Note that the usage of this attribute has been deprecated by the + * RFC 3489-bis standard. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_response_addr_attr; + + +/** + * This structure describes STUN CHANGED-ADDRESS attribute. + * The CHANGED-ADDRESS attribute indicates the IP address and port where + * responses would have been sent from if the "change IP" and "change + * port" flags had been set in the CHANGE-REQUEST attribute of the + * Binding Request. The attribute is always present in a Binding + * Response, independent of the value of the flags. Its syntax is + * identical to MAPPED-ADDRESS. + * + * Note that the usage of this attribute has been deprecated by the + * RFC 3489-bis standard. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_changed_addr_attr; + + +/** + * This structure describes STUN CHANGE-REQUEST attribute. + * The CHANGE-REQUEST attribute is used by the client to request that + * the server use a different address and/or port when sending the + * response. + * + * Bit 29 of the value is the "change IP" flag. If true, it requests + * the server to send the Binding Response with a different IP address + * than the one the Binding Request was received on. + * + * Bit 30 of the value is the "change port" flag. If true, it requests + * the server to send the Binding Response with a different port than + * the one the Binding Request was received on. + * + * Note that the usage of this attribute has been deprecated by the + * RFC 3489-bis standard. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_change_request_attr; + +/** + * This structure describes STUN SOURCE-ADDRESS attribute. + * The SOURCE-ADDRESS attribute is present in Binding Responses. It + * indicates the source IP address and port that the server is sending + * the response from. Its syntax is identical to that of MAPPED- + * ADDRESS. + * + * Note that the usage of this attribute has been deprecated by the + * RFC 3489-bis standard. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_src_addr_attr; + + +/** + * This describes the STUN REFLECTED-FROM attribute. + * The REFLECTED-FROM attribute is present only in Binding Responses, + * when the Binding Request contained a RESPONSE-ADDRESS attribute. The + * attribute contains the identity (in terms of IP address) of the + * source where the request came from. Its purpose is to provide + * traceability, so that a STUN server cannot be used as a reflector for + * denial-of-service attacks. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_reflected_from_attr; + + +/** + * This describes STUN USERNAME attribute. + * The USERNAME attribute is used for message integrity. It identifies + * the shared secret used in the message integrity check. Consequently, + * the USERNAME MUST be included in any request that contains the + * MESSAGE-INTEGRITY attribute. + */ +typedef struct pj_stun_generic_string_attr pj_stun_username_attr; + + +/** + * This describes STUN PASSWORD attribute. + * If the message type is Shared Secret Response it MUST include the + * PASSWORD attribute. + */ +typedef struct pj_stun_generic_string_attr pj_stun_password_attr; + + +/** + * This describes STUN LIFETIME attribute. + * The lifetime attribute represents the duration for which the server + * will maintain an allocation in the absence of data traffic either + * from or to the client. It is a 32 bit value representing the number + * of seconds remaining until expiration. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_lifetime_attr; + + +/** + * This describes STUN BANDWIDTH attribute. + * The bandwidth attribute represents the peak bandwidth, measured in + * kbits per second, that the client expects to use on the binding. The + * value represents the sum in the receive and send directions. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_bandwidth_attr; + + +/** + * This describes the STUN REMOTE-ADDRESS attribute. + * The REMOTE-ADDRESS specifies the address and port of the peer as seen + * from the STUN relay server. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_remote_addr_attr; + + +/** + * This describes the STUN DATA attribute. + * The DATA attribute is present in Send Indications and Data + * Indications. It contains raw payload data that is to be sent (in the + * case of a Send Request) or was received (in the case of a Data + * Indication).. + */ +typedef struct pj_stun_binary_attr pj_stun_data_attr; + + +/** + * This describes the STUN RELAY-ADDRESS attribute. + * The RELAY-ADDRESS is present in Allocate responses. It specifies the + * address and port that the server allocated to the client. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_relay_addr_attr; + + +/** + * This describes the REQUESTED-ADDRESS-TYPE attribute. + * The REQUESTED-ADDRESS-TYPE attribute is used by clients to request + * the allocation of a specific address type from a server. The + * following is the format of the REQUESTED-ADDRESS-TYPE attribute. + + \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Family | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_generic_uint_attr pj_stun_requested_addr_type; + +/** + * This describes the STUN REQUESTED-PORT-PROPS attribute. + * This attribute allows the client to request certain properties for + * the port that is allocated by the server. The attribute can be used + * with any transport protocol that has the notion of a 16 bit port + * space (including TCP and UDP). The attribute is 32 bits long. Its + * format is: + + \verbatim + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved = 0 |B| A | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + \endverbatim + */ +typedef struct pj_stun_generic_uint_attr pj_stun_requested_port_props_attr; + + +/** + * This describes the STUN REQUESTED-TRANSPORT attribute. + * This attribute is used by the client to request a specific transport + * protocol for the allocated transport address. It is a 32 bit + * unsigned integer. Its values are: 0x0000 for UDP and 0x0000 for TCP. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_requested_transport_attr; + + +/** + * This describes the STUN REQUESTED-IP attribute. + * The REQUESTED-IP attribute is used by the client to request that a + * specific IP address be allocated to it. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_requested_ip_attr; + +/** + * This describes the XOR-REFLECTED-FROM attribute, as described by + * draft-macdonald-behave-nat-behavior-discovery-00. + * The XOR-REFLECTED-FROM attribute is used in place of the REFLECTED- + * FROM attribute. It provides the same information, but because the + * NAT's public address is obfuscated through the XOR function, It can + * pass through a NAT that would otherwise attempt to translate it to + * the private network address. XOR-REFLECTED-FROM has identical syntax + * to XOR-MAPPED-ADDRESS. + */ +typedef struct pj_stun_generic_ip_addr_attr pj_stun_xor_reflected_from_attr; + +/** + * This describes the PRIORITY attribute from draft-ietf-mmusic-ice-13. + * The PRIORITY attribute indicates the priority that is to be + * associated with a peer reflexive candidate, should one be discovered + * by this check. It is a 32 bit unsigned integer, and has an attribute + * type of 0x0024. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_priority_attr; + +/** + * This describes the USE-CANDIDATE attribute from draft-ietf-mmusic-ice-13. + * The USE-CANDIDATE attribute indicates that the candidate pair + * resulting from this check should be used for transmission of media. + * The attribute has no content (the Length field of the attribute is + * zero); it serves as a flag. + */ +typedef struct pj_stun_empty_attr pj_stun_use_candidate_attr; + +/** + * This structure describes STUN XOR-INTERNAL-ADDRESS attribute from + * draft-wing-behave-nat-control-stun-usage-00. + * This attribute MUST be present in a Binding Response and may be used + * in other responses as well. This attribute is necessary to allow a + * STUN client to 'walk backwards' and communicate directly with all of + * the STUN-aware NATs along the path. + */ +typedef pj_stun_generic_ip_addr_attr pj_stun_xor_internal_addr_attr; + +/** + * This describes the STUN TIMER-VAL attribute. + * The TIMER-VAL attribute is used only in conjunction with the Set + * Active Destination response. It conveys from the server, to the + * client, the value of the timer used in the server state machine. + */ +typedef struct pj_stun_generic_uint_attr pj_stun_timer_val_attr; + + +/** + * This structure describes a parsed STUN message. All integral fields + * in this structure (including IP addresses) will be in the host + * byte order. + */ +typedef struct pj_stun_msg +{ + /** + * STUN message header. + */ + pj_stun_msg_hdr hdr; + + /** + * Number of attributes in the STUN message. + */ + unsigned attr_count; + + /** + * Array of STUN attributes. + */ + pj_stun_attr_hdr *attr[PJ_STUN_MAX_ATTR]; + +} pj_stun_msg; + + +/** + * Get STUN message method name. + * + * @param msg_type The STUN message type (in host byte order) + * + * @return The STUN message method name string. + */ +PJ_DECL(const char*) pj_stun_get_method_name(unsigned msg_type); + + +/** + * Get STUN message class name. + * + * @param msg_type The STUN message type (in host byte order) + * + * @return The STUN message class name string. + */ +PJ_DECL(const char*) pj_stun_get_class_name(unsigned msg_type); + + +/** + * Get STUN attribute name. + * + * @return attr_type The STUN attribute type (in host byte order). + * + * @return The STUN attribute type name string. + */ +PJ_DECL(const char*) pj_stun_get_attr_name(unsigned attr_type); + + +/** + * Get STUN standard reason phrase for the specified error code. + * + * @param err_code The STUN error code. + * + * @return The STUN error reason phrase. + */ +PJ_DECL(pj_str_t) pj_stun_get_err_reason(int err_code); + + +/** + * Create a blank STUN message. + * + * @param pool Pool to create the STUN message. + * @param msg_type The 14bit message type. + * @param magic Magic value to be put to the mesage; for requests, + * the value should be PJ_STUN_MAGIC. + * @param tsx_id Optional transaction ID, or NULL to let the + * function generates a random transaction ID. + * @param p_msg Pointer to receive the message. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pj_stun_msg_create(pj_pool_t *pool, + unsigned msg_type, + pj_uint32_t magic, + const pj_uint8_t tsx_id[12], + pj_stun_msg **p_msg); + + +/** + * Add STUN attribute to STUN message. + * + * @param msg The STUN message. + * @param attr The STUN attribute to be added to the message. + * + * @return PJ_SUCCESS on success, or PJ_ETOOMANY if there are + * already too many attributes in the message. + */ +PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg, + pj_stun_attr_hdr *attr); + + +/** + * Check that the PDU is potentially a valid STUN message. This function + * is useful when application needs to multiplex STUN packets with other + * application traffic. When this function returns PJ_SUCCESS, there is a + * big chance that the packet is a STUN packet. + * + * Note that we cannot be sure that the PDU is a really valid STUN message + * until we actually parse the PDU. + * + * @param pdu The packet buffer. + * @param pdu_len The length of the packet buffer. + * @param options Options. + * + * @return PJ_SUCCESS if the PDU is a potentially valid STUN + * message. + */ +PJ_DECL(pj_status_t) pj_stun_msg_check(const void *pdu, unsigned pdu_len, + unsigned options); + + +/** + * Parse incoming packet into STUN message. + * + * @param pool Pool to allocate the message. + * @param pdu The incoming packet to be parsed. + * @param pdu_len The length of the incoming packet. + * @param options Parsing flags. + * @param p_msg Pointer to receive the parsed message. + * @param p_parsed_len Optional pointer to receive how many bytes have + * been parsed for the STUN message. This is useful + * when the packet is received over stream oriented + * transport. + * @param p_err_code Optional pointer to receive STUN error code when + * parsing failed. + * @param uattr_cnt Optional pointer to specify the number of elements + * in uattr array. On return, this will be filled with + * the actual number of attributes set in the uattr. + * @param uattr Optional array to receive unknown attribute types. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_msg_decode(pj_pool_t *pool, + const pj_uint8_t *pdu, + unsigned pdu_len, + unsigned options, + pj_stun_msg **p_msg, + unsigned *p_parsed_len, + unsigned *p_err_code, + unsigned *uattr_cnt, + pj_uint16_t uattr[]); + +/** + * Print the message structure to a buffer. + * + * @param msg The message to be printed to a contiguous buffer. + * @param pkt_buf The buffer. + * @param buf_size Size of the buffer. + * @param options Options. + * @param p_msg_len Upon return, it will be filed with the size of + * the packet in bytes, or negative value on error. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pj_stun_msg_encode(const pj_stun_msg *msg, + pj_uint8_t *pkt_buf, + unsigned buf_size, + unsigned options, + unsigned *p_msg_len); + + +/** + * Find STUN attribute in the STUN message, starting from the specified + * index. + * + * @param msg The STUN message. + * @param attr_type The attribute type to be found. + * @param start_index The start index of the attribute in the message. + * Specify zero to start searching from the first + * attribute. + * + * @return The attribute instance, or NULL if it cannot be + * found. + */ +PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg, + int attr_type, + unsigned start_index); + + +/** + * Create a generic STUN IP address attribute for IPv4 address. Note that + * the port and ip_addr parameters are in host byte order. + * + * @param pool The pool to allocate memory from. + * @param attr_type Attribute type. + * @param xor_ed If non-zero, the port and address will be XOR-ed + * with magic, to make the XOR-MAPPED-ADDRESS attribute. + * @param addr_len Length of \a addr parameter. + * @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_generic_ip_addr_attr_create(pj_pool_t *pool, + int attr_type, + pj_bool_t xor_ed, + unsigned addr_len, + const pj_sockaddr_t *addr, + pj_stun_generic_ip_addr_attr **p_attr); + + +/** + * Create a STUN generic string attribute. + * + * @param pool The pool to allocate memory from. + * @param value The string value to be assigned to the attribute. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_generic_string_attr_create(pj_pool_t *pool, + int attr_type, + const pj_str_t *value, + pj_stun_generic_string_attr **p_attr); + + +/** + * Create a STUN generic 32bit value attribute. + * + * @param pool The pool to allocate memory from. + * @param attr_type Attribute type, from #pj_stun_attr_type. + * @param value The 32bit value to be assigned to the attribute. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_generic_uint_attr_create(pj_pool_t *pool, + int attr_type, + pj_uint32_t value, + pj_stun_generic_uint_attr **p_attr); + + +/** + * Create a STUN MESSAGE-INTEGRITY attribute. + * + * @param pool The pool to allocate memory from. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_msg_integrity_attr_create(pj_pool_t *pool, + pj_stun_msg_integrity_attr **p_attr); + + +/** + * Create a STUN ERROR-CODE attribute. + * + * @param pool The pool to allocate memory from. + * @param err_code STUN error code. + * @param err_reason Optional STUN error reason. If NULL is given, the + * standard error reason will be given. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_error_code_attr_create(pj_pool_t *pool, + int err_code, + const pj_str_t *err_reason, + pj_stun_error_code_attr **p_attr); + + +/** + * Create an empty instance of STUN UNKNOWN-ATTRIBUTES attribute. + * + * @param pool The pool to allocate memory from. + * @param attr_cnt Number of attributes in the array (can be zero). + * @param attr Optional array of attributes. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_unknown_attr_create(pj_pool_t *pool, + unsigned attr_cnt, + pj_uint16_t attr[], + pj_stun_unknown_attr **p_attr); + + +/** + * Create a blank binary attribute. + * + * @param pool The pool to allocate memory from. + * @param attr_type The attribute type. + * @param p_attr Pointer to receive the attribute. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_binary_attr_create(pj_pool_t *pool, + int attr_type, + pj_stun_binary_attr **p_attr); + + +/** + * @} + */ + + +PJ_END_DECL + + +#endif /* __PJ_STUN_MSG_H__ */ + diff --git a/pjlib-util/include/pjlib-util/stun_server.h b/pjlib-util/include/pjlib-util/stun_server.h new file mode 100644 index 00000000..15ecf308 --- /dev/null +++ b/pjlib-util/include/pjlib-util/stun_server.h @@ -0,0 +1,109 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJ_STUN_SERVER_H__ +#define __PJ_STUN_SERVER_H__ + +/** + * @file stun_server.h + * @brief STUN server side services. + */ + +#include <pjlib-util/stun_msg.h> +#include <pjlib-util/stun_endpoint.h> + + +PJ_BEGIN_DECL + + +/* **************************************************************************/ +/** + * @defgroup PJLIB_UTIL_STUN_SERVER STUN Server Side Services + * @brief STUN server side services + * @ingroup PJLIB_UTIL_STUN + * @{ + */ + +typedef struct pj_stun_service pj_stun_service; + + +/** + * STUN service handler. + */ +typedef struct pj_stun_service_handler +{ + /** + * The STUN message type. + */ + int msg_type; + + /** + * Callback to be called to handle this STUN message type. + * + * @param svc The service. + * @param msg The STUN message. + */ + pj_status_t (*handle_msg)(pj_stun_service *svc, + void *handle_data, + const pj_stun_msg *msg); + +} pj_stun_service_handler; + + +/** + * Create STUN service. + */ +PJ_DECL(pj_status_t) pj_stun_service_create(pj_pool_t *pool, + const char *name, + unsigned options, + unsigned handler_cnt, + pj_stun_service_handler cb[], + void *user_data, + pj_stun_service **p_svc); + +/** + * Destroy STUN service + */ +PJ_DECL(pj_status_t) pj_stun_service_destroy(pj_stun_service *svc); + + +/** + * Get user data associated with the STUN service. + */ +PJ_DECL(void*) pj_stun_service_get_user_data(pj_stun_service *svc); + + +/** + * Instruct the STUN service to handle incoming STUN message. + */ +PJ_DECL(pj_status_t) pj_stun_service_handle_msg(pj_stun_service *svc, + void *handle_data, + const pj_stun_msg *msg); + + + +/** + * @} + */ + + +PJ_END_DECL + + +#endif /* __PJ_STUN_SERVER_H__ */ + diff --git a/pjlib-util/include/pjlib-util/stun.h b/pjlib-util/include/pjlib-util/stun_simple.h index e317877c..5a4f2c78 100644 --- a/pjlib-util/include/pjlib-util/stun.h +++ b/pjlib-util/include/pjlib-util/stun_simple.h @@ -1,4 +1,4 @@ -/* $Id */ +/* $Id$ */ /* * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> * @@ -16,8 +16,8 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#ifndef __PJ_STUN_H__ -#define __PJ_STUN_H__ +#ifndef __PJSTUN_H__ +#define __PJSTUN_H__ /** * @file stun.h @@ -27,127 +27,133 @@ #include <pjlib-util/types.h> #include <pj/sock.h> -/** - * @defgroup PJLIB_UTIL_STUN_CLIENT Mini/Tiny STUN Client - * @ingroup PJLIB_UTIL - * @{ - */ PJ_BEGIN_DECL -/** +/* * This enumeration describes STUN message types. */ -typedef enum pj_stun_msg_type +typedef enum pjstun_msg_type { - PJ_STUN_BINDING_REQUEST = 0x0001, - PJ_STUN_BINDING_RESPONSE = 0x0101, - PJ_STUN_BINDING_ERROR_RESPONSE = 0x0111, - PJ_STUN_SHARED_SECRET_REQUEST = 0x0002, - PJ_STUN_SHARED_SECRET_RESPONSE = 0x0102, - PJ_STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112 -} pj_stun_msg_type; + PJSTUN_BINDING_REQUEST = 0x0001, + PJSTUN_BINDING_RESPONSE = 0x0101, + PJSTUN_BINDING_ERROR_RESPONSE = 0x0111, + PJSTUN_SHARED_SECRET_REQUEST = 0x0002, + PJSTUN_SHARED_SECRET_RESPONSE = 0x0102, + PJSTUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112 +} pjstun_msg_type; -/** +/* * This enumeration describes STUN attribute types. */ -typedef enum pj_stun_attr_type +typedef enum pjstun_attr_type { - PJ_STUN_ATTR_MAPPED_ADDR = 1, - PJ_STUN_ATTR_RESPONSE_ADDR, - PJ_STUN_ATTR_CHANGE_REQUEST, - PJ_STUN_ATTR_SOURCE_ADDR, - PJ_STUN_ATTR_CHANGED_ADDR, - PJ_STUN_ATTR_USERNAME, - PJ_STUN_ATTR_PASSWORD, - PJ_STUN_ATTR_MESSAGE_INTEGRITY, - PJ_STUN_ATTR_ERROR_CODE, - PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES, - PJ_STUN_ATTR_REFLECTED_FORM -} pj_stun_attr_type; - - -/** + PJSTUN_ATTR_MAPPED_ADDR = 1, + PJSTUN_ATTR_RESPONSE_ADDR, + PJSTUN_ATTR_CHANGE_REQUEST, + PJSTUN_ATTR_SOURCE_ADDR, + PJSTUN_ATTR_CHANGED_ADDR, + PJSTUN_ATTR_USERNAME, + PJSTUN_ATTR_PASSWORD, + PJSTUN_ATTR_MESSAGE_INTEGRITY, + PJSTUN_ATTR_ERROR_CODE, + PJSTUN_ATTR_UNKNOWN_ATTRIBUTES, + PJSTUN_ATTR_REFLECTED_FORM +} pjstun_attr_type; + + +/* * This structre describes STUN message header. */ -typedef struct pj_stun_msg_hdr +typedef struct pjstun_msg_hdr { pj_uint16_t type; pj_uint16_t length; pj_uint32_t tsx[4]; -} pj_stun_msg_hdr; +} pjstun_msg_hdr; -/** +/* * This structre describes STUN attribute header. */ -typedef struct pj_stun_attr_hdr +typedef struct pjstun_attr_hdr { pj_uint16_t type; pj_uint16_t length; -} pj_stun_attr_hdr; +} pjstun_attr_hdr; -/** +/* * This structre describes STUN MAPPED-ADDR attribute. */ -typedef struct pj_stun_mapped_addr_attr +typedef struct pjstun_mapped_addr_attr { - pj_stun_attr_hdr hdr; + pjstun_attr_hdr hdr; pj_uint8_t ignored; pj_uint8_t family; pj_uint16_t port; pj_uint32_t addr; -} pj_stun_mapped_addr_attr; +} pjstun_mapped_addr_attr; -typedef pj_stun_mapped_addr_attr pj_stun_response_addr_attr; -typedef pj_stun_mapped_addr_attr pj_stun_changed_addr_attr; -typedef pj_stun_mapped_addr_attr pj_stun_src_addr_attr; -typedef pj_stun_mapped_addr_attr pj_stun_reflected_form_attr; +typedef pjstun_mapped_addr_attr pjstun_response_addr_attr; +typedef pjstun_mapped_addr_attr pjstun_changed_addr_attr; +typedef pjstun_mapped_addr_attr pjstun_src_addr_attr; +typedef pjstun_mapped_addr_attr pjstun_reflected_form_attr; -typedef struct pj_stun_change_request_attr +typedef struct pjstun_change_request_attr { - pj_stun_attr_hdr hdr; + pjstun_attr_hdr hdr; pj_uint32_t value; -} pj_stun_change_request_attr; +} pjstun_change_request_attr; -typedef struct pj_stun_username_attr +typedef struct pjstun_username_attr { - pj_stun_attr_hdr hdr; + pjstun_attr_hdr hdr; pj_uint32_t value[1]; -} pj_stun_username_attr; +} pjstun_username_attr; -typedef pj_stun_username_attr pj_stun_password_attr; +typedef pjstun_username_attr pjstun_password_attr; -typedef struct pj_stun_error_code_attr +typedef struct pjstun_error_code_attr { - pj_stun_attr_hdr hdr; + pjstun_attr_hdr hdr; pj_uint16_t ignored; pj_uint8_t err_class; pj_uint8_t number; char reason[4]; -} pj_stun_error_code_attr; +} pjstun_error_code_attr; -typedef struct pj_stun_msg +typedef struct pjstun_msg { - pj_stun_msg_hdr *hdr; + pjstun_msg_hdr *hdr; int attr_count; - pj_stun_attr_hdr *attr[PJ_STUN_MAX_ATTR]; -} pj_stun_msg; + pjstun_attr_hdr *attr[PJSTUN_MAX_ATTR]; +} pjstun_msg; /* STUN message API (stun.c). */ -PJ_DECL(pj_status_t) pj_stun_create_bind_req( pj_pool_t *pool, +PJ_DECL(pj_status_t) pjstun_create_bind_req( pj_pool_t *pool, void **msg, pj_size_t *len, pj_uint32_t id_hi, pj_uint32_t id_lo); -PJ_DECL(pj_status_t) pj_stun_parse_msg( void *buf, pj_size_t len, - pj_stun_msg *msg); -PJ_DECL(void*) pj_stun_msg_find_attr( pj_stun_msg *msg, pj_stun_attr_type t); +PJ_DECL(pj_status_t) pjstun_parse_msg( void *buf, pj_size_t len, + pjstun_msg *msg); +PJ_DECL(void*) pjstun_msg_find_attr( pjstun_msg *msg, pjstun_attr_type t); /** + * @defgroup PJLIB_UTIL_STUN_CLIENT Simple STUN Helper + * @ingroup PJLIB_UTIL_STUN + * @brief A simple and small footprint STUN resolution helper + * @{ + * + * This is the older implementation of STUN client, with only one function + * provided (pjstun_get_mapped_addr()) to retrieve the public IP address + * of multiple sockets. + */ + +/** * This is the main function to request the mapped address of local sockets * to multiple STUN servers. This function is able to find the mapped * addresses of multiple sockets simultaneously, and for each socket, two @@ -185,7 +191,7 @@ PJ_DECL(void*) pj_stun_msg_find_attr( pj_stun_msg *msg, pj_stun_attr_type t); * - etc. * */ -PJ_DECL(pj_status_t) pj_stun_get_mapped_addr( pj_pool_factory *pf, +PJ_DECL(pj_status_t) pjstun_get_mapped_addr( pj_pool_factory *pf, int sock_cnt, pj_sock_t sock[], const pj_str_t *srv1, int port1, const pj_str_t *srv2, int port2, @@ -197,5 +203,5 @@ PJ_END_DECL * @} */ -#endif /* __PJ_STUN_H__ */ +#endif /* __PJSTUN_H__ */ diff --git a/pjlib-util/include/pjlib-util/stun_transaction.h b/pjlib-util/include/pjlib-util/stun_transaction.h new file mode 100644 index 00000000..2cacef36 --- /dev/null +++ b/pjlib-util/include/pjlib-util/stun_transaction.h @@ -0,0 +1,205 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2005 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJ_STUN_TRANSACTION_H__ +#define __PJ_STUN_TRANSACTION_H__ + +/** + * @file stun_transaction.h + * @brief STUN transaction + */ + +#include <pjlib-util/stun_msg.h> +#include <pjlib-util/stun_endpoint.h> + + +PJ_BEGIN_DECL + + +/* **************************************************************************/ +/** + * @defgroup PJLIB_UTIL_STUN_TRANSACTION STUN Client Transaction + * @brief STUN client transaction + * @ingroup PJLIB_UTIL_STUN + * @{ + * + The @ref PJLIB_UTIL_STUN_TRANSACTION is used to manage outgoing STUN request, + for example to retransmit the request and to notify application about the + completion of the request. + + The @ref PJLIB_UTIL_STUN_TRANSACTION does not use any networking operations, + but instead application must supply the transaction with a callback to + be used by the transaction to send outgoing requests. This way the STUN + transaction is made more generic and can work with different types of + networking codes in application. + + + */ + +/** + * Opaque declaration of STUN client transaction. + */ +typedef struct pj_stun_client_tsx pj_stun_client_tsx; + +/** + * STUN client transaction callback. + */ +typedef struct pj_stun_tsx_cb +{ + /** + * This callback is called when the STUN transaction completed. + * + * @param tsx The STUN transaction. + * @param status Status of the transaction. Status PJ_SUCCESS + * means that the request has received a successful + * response. + * @param response The STUN response, which value may be NULL if + * \a status is not PJ_SUCCESS. + */ + void (*on_complete)(pj_stun_client_tsx *tsx, + pj_status_t status, + pj_stun_msg *response); + + /** + * This callback is called by the STUN transaction when it wants to send + * outgoing message. + * + * @param tsx The STUN transaction instance. + * @param stun_pkt The STUN packet to be sent. + * @param pkt_size Size of the STUN packet. + * + * @return If return value of the callback is not PJ_SUCCESS, + * the transaction will fail. + */ + pj_status_t (*on_send_msg)(pj_stun_client_tsx *tsx, + const void *stun_pkt, + pj_size_t pkt_size); + +} pj_stun_tsx_cb; + + + +/** + * Create an instance of STUN client transaction. The STUN client + * transaction is used to transmit outgoing STUN request and to + * ensure the reliability of the request by periodically retransmitting + * the request, if necessary. + * + * @param endpt The STUN endpoint, which will be used to retrieve + * various settings for the transaction. + * @param cb Callback structure, to be used by the transaction + * to send message and to notify the application about + * the completion of the transaction. + * @param p_tsx Pointer to receive the transaction instance. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_client_tsx_create( pj_stun_endpoint *endpt, + const pj_stun_tsx_cb *cb, + pj_stun_client_tsx **p_tsx); + +/** + * Destroy a STUN client transaction. + * + * @param tsx The STUN transaction. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_client_tsx_destroy(pj_stun_client_tsx *tsx); + + +/** + * Associate an arbitrary data with the STUN transaction. This data + * can be then retrieved later from the transaction, by using + * pj_stun_client_tsx_get_data() function. + * + * @param tsx The STUN client transaction. + * @param data Application data to be associated with the + * STUN transaction. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pj_stun_client_tsx_set_data(pj_stun_client_tsx *tsx, + void *data); + + +/** + * Get the user data that was previously associated with the STUN + * transaction. + * + * @param tsx The STUN client transaction. + * + * @return The user data. + */ +PJ_DECL(void*) pj_stun_client_tsx_get_data(pj_stun_client_tsx *tsx); + + +/** + * Start the STUN client transaction by sending STUN request using + * this transaction. If reliable transport such as TCP or TLS is used, + * the retransmit flag should be set to PJ_FALSE because reliablity + * will be assured by the transport layer. + * + * @param tsx The STUN client transaction. + * @param retransmit Should this message be retransmitted by the + * STUN transaction. + * @param msg The STUN message. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_client_tsx_send_msg(pj_stun_client_tsx *tsx, + pj_bool_t retransmit, + const pj_stun_msg *msg); + + +/** + * Notify the STUN transaction about the arrival of STUN response. + * If the STUN response contains a final error (300 and greater), the + * transaction will be terminated and callback will be called. If the + * STUN response contains response code 100-299, retransmission + * will cease, but application must still call this function again + * with a final response later to allow the transaction to complete. + * + * @param tsx The STUN client transaction instance. + * @param packet The incoming packet. + * @param pkt_size Size of the incoming packet. + * @param parsed_len Optional pointer to receive the number of bytes + * that have been parsed from the incoming packet + * for the STUN message. This is useful if the + * STUN transaction is running over stream oriented + * socket such as TCP or TLS. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_client_tsx_on_rx_msg(pj_stun_client_tsx *tsx, + const void *packet, + pj_size_t pkt_size, + unsigned *parsed_len); + + + +/** + * @} + */ + + +PJ_END_DECL + + +#endif /* __PJ_STUN_TRANSACTION_H__ */ + |