Low-level representation and parsing of STUN messages.

Data Structures
struct	pj_stun_msg_hdr
struct	pj_stun_attr_hdr
struct	pj_stun_xor_reflected_from_attr
struct	pj_stun_use_candidate_attr
struct	pj_stun_password_attr
struct	pj_stun_icmp_attr
struct	pj_stun_ice_controlled_attr
struct	pj_stun_data_attr
struct	pj_stun_msgint_attr
struct	pj_stun_errcode_attr
struct	pj_stun_unknown_attr
struct	pj_stun_msg
Defines
#define	PJ_STUN_MAGIC 0x2112A442
#define	PJ_STUN_GET_METHOD(msg_type) ((msg_type) & 0xFEEF)
#define	PJ_STUN_IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000)
#define	PJ_STUN_IS_SUCCESS_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0100)
#define	PJ_STUN_SUCCESS_RESPONSE_BIT (0x0100)
#define	PJ_STUN_IS_ERROR_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0110)
#define	PJ_STUN_ERROR_RESPONSE_BIT (0x0110)
#define	PJ_STUN_IS_RESPONSE(msg_type) (((msg_type) & 0x0100) == 0x0100)
#define	PJ_STUN_IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010)
#define	PJ_STUN_INDICATION_BIT (0x0010)
#define	PJ_STUN_GET_CH_NB(u32) ((pj_uint16_t)(u32>>16))
#define	PJ_STUN_SET_CH_NB(chnum) (((pj_uint32_t)chnum) << 16)
#define	PJ_STUN_GET_RT_PROTO(u32) (u32 >> 24)
#define	PJ_STUN_SET_RT_PROTO(proto) (((pj_uint32_t)(proto)) << 24)
Enumerations
enum	pj_stun_method_e { PJ_STUN_BINDING_METHOD = 1, PJ_STUN_SHARED_SECRET_METHOD = 2, PJ_STUN_ALLOCATE_METHOD = 3, PJ_STUN_REFRESH_METHOD = 4, PJ_STUN_SEND_METHOD = 6, PJ_STUN_DATA_METHOD = 7, PJ_STUN_CREATE_PERM_METHOD = 8, PJ_STUN_CHANNEL_BIND_METHOD = 9, PJ_STUN_METHOD_MAX }
enum	pj_stun_msg_class_e { PJ_STUN_REQUEST_CLASS = 0, PJ_STUN_INDICATION_CLASS = 1, PJ_STUN_SUCCESS_CLASS = 2, PJ_STUN_ERROR_CLASS = 3 }
enum	pj_stun_msg_type { PJ_STUN_BINDING_REQUEST = 0x0001, PJ_STUN_BINDING_RESPONSE = 0x0101, PJ_STUN_BINDING_ERROR_RESPONSE = 0x0111, PJ_STUN_BINDING_INDICATION = 0x0011, PJ_STUN_SHARED_SECRET_REQUEST = 0x0002, PJ_STUN_SHARED_SECRET_RESPONSE = 0x0102, PJ_STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112, PJ_STUN_ALLOCATE_REQUEST = 0x0003, PJ_STUN_ALLOCATE_RESPONSE = 0x0103, PJ_STUN_ALLOCATE_ERROR_RESPONSE = 0x0113, PJ_STUN_REFRESH_REQUEST = 0x0004, PJ_STUN_REFRESH_RESPONSE = 0x0104, PJ_STUN_REFRESH_ERROR_RESPONSE = 0x0114, PJ_STUN_SEND_INDICATION = 0x0016, PJ_STUN_DATA_INDICATION = 0x0017, PJ_STUN_CREATE_PERM_REQUEST = 0x0008, PJ_STUN_CREATE_PERM_RESPONSE = 0x0108, PJ_STUN_CREATE_PERM_ERROR_RESPONSE = 0x0118, PJ_STUN_CHANNEL_BIND_REQUEST = 0x0009, PJ_STUN_CHANNEL_BIND_RESPONSE = 0x0109, PJ_STUN_CHANNEL_BIND_ERROR_RESPONSE = 0x0119 }
enum	pj_stun_attr_type { PJ_STUN_ATTR_MAPPED_ADDR = 0x0001, PJ_STUN_ATTR_RESPONSE_ADDR = 0x0002, PJ_STUN_ATTR_CHANGE_REQUEST = 0x0003, PJ_STUN_ATTR_SOURCE_ADDR = 0x0004, PJ_STUN_ATTR_CHANGED_ADDR = 0x0005, PJ_STUN_ATTR_USERNAME = 0x0006, PJ_STUN_ATTR_PASSWORD = 0x0007, PJ_STUN_ATTR_MESSAGE_INTEGRITY = 0x0008, PJ_STUN_ATTR_ERROR_CODE = 0x0009, PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES = 0x000A, PJ_STUN_ATTR_REFLECTED_FROM = 0x000B, PJ_STUN_ATTR_CHANNEL_NUMBER = 0x000C, PJ_STUN_ATTR_LIFETIME = 0x000D, PJ_STUN_ATTR_MAGIC_COOKIE = 0x000F, PJ_STUN_ATTR_BANDWIDTH = 0x0010, PJ_STUN_ATTR_XOR_PEER_ADDR = 0x0012, PJ_STUN_ATTR_DATA = 0x0013, PJ_STUN_ATTR_REALM = 0x0014, PJ_STUN_ATTR_NONCE = 0x0015, PJ_STUN_ATTR_XOR_RELAYED_ADDR = 0x0016, PJ_STUN_ATTR_REQ_ADDR_TYPE = 0x0017, PJ_STUN_ATTR_EVEN_PORT = 0x0018, PJ_STUN_ATTR_REQ_TRANSPORT = 0x0019, PJ_STUN_ATTR_DONT_FRAGMENT = 0x001A, PJ_STUN_ATTR_XOR_MAPPED_ADDR = 0x0020, PJ_STUN_ATTR_TIMER_VAL = 0x0021, PJ_STUN_ATTR_RESERVATION_TOKEN = 0x0022, PJ_STUN_ATTR_XOR_REFLECTED_FROM = 0x0023, PJ_STUN_ATTR_PRIORITY = 0x0024, PJ_STUN_ATTR_USE_CANDIDATE = 0x0025, PJ_STUN_ATTR_ICMP = 0x0030, PJ_STUN_ATTR_END_MANDATORY_ATTR, PJ_STUN_ATTR_START_EXTENDED_ATTR = 0x8021, PJ_STUN_ATTR_SOFTWARE = 0x8022, PJ_STUN_ATTR_ALTERNATE_SERVER = 0x8023, PJ_STUN_ATTR_REFRESH_INTERVAL = 0x8024, PJ_STUN_ATTR_FINGERPRINT = 0x8028, PJ_STUN_ATTR_ICE_CONTROLLED = 0x8029, PJ_STUN_ATTR_ICE_CONTROLLING = 0x802a, PJ_STUN_ATTR_END_EXTENDED_ATTR }
enum	pj_stun_status { PJ_STUN_SC_TRY_ALTERNATE = 300, PJ_STUN_SC_BAD_REQUEST = 400, PJ_STUN_SC_UNAUTHORIZED = 401, PJ_STUN_SC_FORBIDDEN = 403, PJ_STUN_SC_UNKNOWN_ATTRIBUTE = 420, PJ_STUN_SC_ALLOCATION_MISMATCH = 437, PJ_STUN_SC_STALE_NONCE = 438, PJ_STUN_SC_TRANSITIONING = 439, PJ_STUN_SC_WRONG_CREDENTIALS = 441, PJ_STUN_SC_UNSUPP_TRANSPORT_PROTO = 442, PJ_STUN_SC_OPER_TCP_ONLY = 445, PJ_STUN_SC_CONNECTION_FAILURE = 446, PJ_STUN_SC_CONNECTION_TIMEOUT = 447, PJ_STUN_SC_ALLOCATION_QUOTA_REACHED = 486, PJ_STUN_SC_ROLE_CONFLICT = 487, PJ_STUN_SC_SERVER_ERROR = 500, PJ_STUN_SC_INSUFFICIENT_CAPACITY = 508, PJ_STUN_SC_GLOBAL_FAILURE = 600 }
enum	pj_stun_decode_options { PJ_STUN_IS_DATAGRAM = 1, PJ_STUN_CHECK_PACKET = 2, PJ_STUN_NO_AUTHENTICATE = 4, PJ_STUN_NO_FINGERPRINT_CHECK = 8 }
Functions
const char *	pj_stun_get_method_name (unsigned msg_type)
const char *	pj_stun_get_class_name (unsigned msg_type)
const char *	pj_stun_get_attr_name (unsigned attr_type)
pj_str_t	pj_stun_get_err_reason (int err_code)
int	pj_stun_set_padding_char (int chr)
pj_status_t	pj_stun_msg_init (pj_stun_msg *msg, unsigned msg_type, pj_uint32_t magic, const pj_uint8_t tsx_id[12])
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)
pj_stun_msg *	pj_stun_msg_clone (pj_pool_t pool, const pj_stun_msg msg)
pj_status_t	pj_stun_msg_create_response (pj_pool_t pool, const pj_stun_msg req_msg, unsigned err_code, const pj_str_t err_msg, pj_stun_msg *p_response)
pj_status_t	pj_stun_msg_add_attr (pj_stun_msg msg, pj_stun_attr_hdr attr)
pj_status_t	pj_stun_msg_encode (pj_stun_msg msg, pj_uint8_t pkt_buf, pj_size_t buf_size, unsigned options, const pj_str_t key, pj_size_t p_msg_len)
pj_status_t	pj_stun_msg_check (const pj_uint8_t *pdu, pj_size_t pdu_len, unsigned options)
pj_status_t	pj_stun_msg_decode (pj_pool_t pool, const pj_uint8_t pdu, pj_size_t pdu_len, unsigned options, pj_stun_msg *p_msg, pj_size_t p_parsed_len, pj_stun_msg **p_response)
char *	pj_stun_msg_dump (const pj_stun_msg msg, char buffer, unsigned length, unsigned *printed_len)
pj_stun_attr_hdr *	pj_stun_msg_find_attr (const pj_stun_msg *msg, int attr_type, unsigned start_index)
pj_stun_attr_hdr *	pj_stun_attr_clone (pj_pool_t pool, const pj_stun_attr_hdr attr)
pj_status_t	pj_stun_sockaddr_attr_init (pj_stun_sockaddr_attr attr, int attr_type, pj_bool_t xor_ed, const pj_sockaddr_t addr, unsigned addr_len)
pj_status_t	pj_stun_sockaddr_attr_create (pj_pool_t pool, int attr_type, pj_bool_t xor_ed, const pj_sockaddr_t addr, unsigned addr_len, pj_stun_sockaddr_attr **p_attr)
pj_status_t	pj_stun_msg_add_sockaddr_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type, pj_bool_t xor_ed, const pj_sockaddr_t *addr, unsigned addr_len)
pj_status_t	pj_stun_string_attr_init (pj_stun_string_attr attr, pj_pool_t pool, int attr_type, const pj_str_t *value)
pj_status_t	pj_stun_string_attr_create (pj_pool_t pool, int attr_type, const pj_str_t value, pj_stun_string_attr **p_attr)
pj_status_t	pj_stun_msg_add_string_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type, const pj_str_t *value)
pj_status_t	pj_stun_uint_attr_create (pj_pool_t pool, int attr_type, pj_uint32_t value, pj_stun_uint_attr *p_attr)
pj_status_t	pj_stun_msg_add_uint_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type, pj_uint32_t value)
pj_status_t	pj_stun_uint64_attr_create (pj_pool_t pool, int attr_type, const pj_timestamp value, pj_stun_uint64_attr **p_attr)
pj_status_t	pj_stun_msg_add_uint64_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type, const pj_timestamp *value)
pj_status_t	pj_stun_msgint_attr_create (pj_pool_t pool, pj_stun_msgint_attr *p_attr)
pj_status_t	pj_stun_msg_add_msgint_attr (pj_pool_t pool, pj_stun_msg msg)
pj_status_t	pj_stun_errcode_attr_create (pj_pool_t pool, int err_code, const pj_str_t err_reason, pj_stun_errcode_attr **p_attr)
pj_status_t	pj_stun_msg_add_errcode_attr (pj_pool_t pool, pj_stun_msg msg, int err_code, const pj_str_t *err_reason)
pj_status_t	pj_stun_unknown_attr_create (pj_pool_t pool, unsigned attr_cnt, const pj_uint16_t attr[], pj_stun_unknown_attr *p_attr)
pj_status_t	pj_stun_msg_add_unknown_attr (pj_pool_t pool, pj_stun_msg msg, unsigned attr_cnt, const pj_uint16_t attr[])
pj_status_t	pj_stun_binary_attr_init (pj_stun_binary_attr attr, pj_pool_t pool, int attr_type, const pj_uint8_t *data, unsigned length)
pj_status_t	pj_stun_binary_attr_create (pj_pool_t pool, int attr_type, const pj_uint8_t data, unsigned length, pj_stun_binary_attr **p_attr)
pj_status_t	pj_stun_msg_add_binary_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type, const pj_uint8_t *data, unsigned length)
pj_status_t	pj_stun_empty_attr_create (pj_pool_t pool, int attr_type, pj_stun_empty_attr *p_attr)
pj_status_t	pj_stun_msg_add_empty_attr (pj_pool_t pool, pj_stun_msg msg, int attr_type)

Define Documentation

#define PJ_STUN_ERROR_RESPONSE_BIT (0x0110)

The error response bit in the message type.

#define PJ_STUN_GET_CH_NB ( u32 ) ((pj_uint16_t)(u32>>16))

Get 16bit channel number from 32bit integral value. Note that uint32 attributes are always stored in host byte order after they have been parsed from the PDU, so no need to do ntohs() here.

#define PJ_STUN_GET_METHOD ( msg_type ) ((msg_type) & 0xFEEF)

Retrieve the STUN method from the message-type field of the STUN message.

#define PJ_STUN_GET_RT_PROTO ( u32 ) (u32 >> 24)

Get protocol value from 32bit TURN REQUESTED-TRANSPORT attribute.

#define PJ_STUN_INDICATION_BIT (0x0010)

The error response bit in the message type.

#define PJ_STUN_IS_ERROR_RESPONSE ( msg_type ) (((msg_type) & 0x0110) == 0x0110)

Determine if the message type is an error response.

#define PJ_STUN_IS_INDICATION ( msg_type ) (((msg_type) & 0x0110) == 0x0010)

Determine if the message type is an indication message.

#define PJ_STUN_IS_REQUEST ( msg_type ) (((msg_type) & 0x0110) == 0x0000)

Determine if the message type is a request.

#define PJ_STUN_IS_RESPONSE ( msg_type ) (((msg_type) & 0x0100) == 0x0100)

Determine if the message type is a response.

#define PJ_STUN_IS_SUCCESS_RESPONSE ( msg_type ) (((msg_type) & 0x0110) == 0x0100)

Determine if the message type is a successful response.

#define PJ_STUN_MAGIC 0x2112A442

STUN magic cookie.

#define PJ_STUN_SET_CH_NB ( chnum ) (((pj_uint32_t)chnum) << 16)

Convert 16bit channel number into 32bit integral value. Note that uint32 attributes will be converted to network byte order when the attribute is written to packet, so no need to do htons() here.

#define PJ_STUN_SET_RT_PROTO ( proto ) (((pj_uint32_t)(proto)) << 24)

Convert protocol value to be placed in 32bit TURN REQUESTED-TRANSPORT attribute.

#define PJ_STUN_SUCCESS_RESPONSE_BIT (0x0100)

The response bit in the message type.

Enumeration Type Documentation

enum pj_stun_attr_type

This enumeration describes STUN attribute types.

Enumerator:

PJ_STUN_ATTR_MAPPED_ADDR	MAPPED-ADDRESS.
PJ_STUN_ATTR_RESPONSE_ADDR	RESPONSE-ADDRESS (deprcatd)
PJ_STUN_ATTR_CHANGE_REQUEST	CHANGE-REQUEST (deprecated)
PJ_STUN_ATTR_SOURCE_ADDR	SOURCE-ADDRESS (deprecated)
PJ_STUN_ATTR_CHANGED_ADDR	CHANGED-ADDRESS (deprecatd)
PJ_STUN_ATTR_USERNAME	USERNAME attribute.
PJ_STUN_ATTR_PASSWORD	was PASSWORD attribute.
PJ_STUN_ATTR_MESSAGE_INTEGRITY	MESSAGE-INTEGRITY.
PJ_STUN_ATTR_ERROR_CODE	ERROR-CODE.
PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES	UNKNOWN-ATTRIBUTES.
PJ_STUN_ATTR_REFLECTED_FROM	REFLECTED-FROM (deprecatd)
PJ_STUN_ATTR_CHANNEL_NUMBER	TURN CHANNEL-NUMBER
PJ_STUN_ATTR_LIFETIME	TURN LIFETIME attr.
PJ_STUN_ATTR_MAGIC_COOKIE	MAGIC-COOKIE attr (deprec)
PJ_STUN_ATTR_BANDWIDTH	TURN BANDWIDTH (deprec)
PJ_STUN_ATTR_XOR_PEER_ADDR	TURN XOR-PEER-ADDRESS
PJ_STUN_ATTR_DATA	DATA attribute.
PJ_STUN_ATTR_REALM	REALM attribute.
PJ_STUN_ATTR_NONCE	NONCE attribute.
PJ_STUN_ATTR_XOR_RELAYED_ADDR	TURN XOR-RELAYED-ADDRESS
PJ_STUN_ATTR_REQ_ADDR_TYPE	REQUESTED-ADDRESS-TYPE
PJ_STUN_ATTR_EVEN_PORT	TURN EVEN-PORT
PJ_STUN_ATTR_REQ_TRANSPORT	TURN REQUESTED-TRANSPORT
PJ_STUN_ATTR_DONT_FRAGMENT	TURN DONT-FRAGMENT
PJ_STUN_ATTR_XOR_MAPPED_ADDR	XOR-MAPPED-ADDRESS
PJ_STUN_ATTR_TIMER_VAL	TIMER-VAL attribute.
PJ_STUN_ATTR_RESERVATION_TOKEN	TURN RESERVATION-TOKEN
PJ_STUN_ATTR_XOR_REFLECTED_FROM	XOR-REFLECTED-FROM
PJ_STUN_ATTR_PRIORITY	PRIORITY
PJ_STUN_ATTR_USE_CANDIDATE	USE-CANDIDATE
PJ_STUN_ATTR_ICMP	ICMP (TURN)
PJ_STUN_ATTR_SOFTWARE	SOFTWARE attribute.
PJ_STUN_ATTR_ALTERNATE_SERVER	ALTERNATE-SERVER.
PJ_STUN_ATTR_REFRESH_INTERVAL	REFRESH-INTERVAL.
PJ_STUN_ATTR_FINGERPRINT	FINGERPRINT attribute.
PJ_STUN_ATTR_ICE_CONTROLLED	ICE-CCONTROLLED attribute.
PJ_STUN_ATTR_ICE_CONTROLLING	ICE-CCONTROLLING attribute

enum pj_stun_decode_options

STUN decoding options

Enumerator:

PJ_STUN_IS_DATAGRAM	Tell the decoder that the message was received from datagram oriented transport (such as UDP).
PJ_STUN_CHECK_PACKET	Tell pj_stun_msg_decode() to check the validity of the STUN message by calling pj_stun_msg_check() before starting to decode the packet.
PJ_STUN_NO_AUTHENTICATE	This option current is only valid for pj_stun_session_on_rx_pkt(). When specified, it tells the session NOT to authenticate the message.
PJ_STUN_NO_FINGERPRINT_CHECK	Disable FINGERPRINT verification. This option can be used when calling pj_stun_msg_check() and pj_stun_msg_decode() to disable the verification of FINGERPRINT, for example when the STUN usage says when FINGERPRINT mechanism shall not be used.

enum pj_stun_method_e

STUN method constants.

Enumerator:

PJ_STUN_BINDING_METHOD	STUN Binding method as defined by RFC 3489-bis.
PJ_STUN_SHARED_SECRET_METHOD	STUN Shared Secret method as defined by RFC 3489-bis.
PJ_STUN_ALLOCATE_METHOD	STUN/TURN Allocate method as defined by draft-ietf-behave-turn
PJ_STUN_REFRESH_METHOD	STUN/TURN Refresh method as defined by draft-ietf-behave-turn
PJ_STUN_SEND_METHOD	STUN/TURN Send indication as defined by draft-ietf-behave-turn
PJ_STUN_DATA_METHOD	STUN/TURN Data indication as defined by draft-ietf-behave-turn
PJ_STUN_CREATE_PERM_METHOD	STUN/TURN CreatePermission method as defined by draft-ietf-behave-turn
PJ_STUN_CHANNEL_BIND_METHOD	STUN/TURN ChannelBind as defined by draft-ietf-behave-turn
PJ_STUN_METHOD_MAX	All known methods.

enum pj_stun_msg_class_e

STUN message classes constants.

Enumerator:

PJ_STUN_REQUEST_CLASS	This specifies that the message type is a STUN request message.
PJ_STUN_INDICATION_CLASS	This specifies that the message type is a STUN indication message.
PJ_STUN_SUCCESS_CLASS	This specifies that the message type is a STUN successful response.
PJ_STUN_ERROR_CLASS	This specifies that the message type is a STUN error response.

enum pj_stun_msg_type

This enumeration describes STUN message types.

Enumerator:

PJ_STUN_BINDING_REQUEST	STUN BINDING request.
PJ_STUN_BINDING_RESPONSE	Successful response to STUN BINDING-REQUEST.
PJ_STUN_BINDING_ERROR_RESPONSE	Error response to STUN BINDING-REQUEST.
PJ_STUN_BINDING_INDICATION	Binding Indication (ICE)
PJ_STUN_SHARED_SECRET_REQUEST	STUN SHARED-SECRET reqeust.
PJ_STUN_SHARED_SECRET_RESPONSE	Successful response to STUN SHARED-SECRET reqeust.
PJ_STUN_SHARED_SECRET_ERROR_RESPONSE	Error response to STUN SHARED-SECRET reqeust.
PJ_STUN_ALLOCATE_REQUEST	STUN/TURN Allocate Request
PJ_STUN_ALLOCATE_RESPONSE	Successful response to STUN/TURN Allocate Request
PJ_STUN_ALLOCATE_ERROR_RESPONSE	Failure response to STUN/TURN Allocate Request
PJ_STUN_REFRESH_REQUEST	STUN/TURN REFRESH Request
PJ_STUN_REFRESH_RESPONSE	Successful response to STUN REFRESH request
PJ_STUN_REFRESH_ERROR_RESPONSE	Error response to STUN REFRESH request.
PJ_STUN_SEND_INDICATION	TURN Send indication
PJ_STUN_DATA_INDICATION	TURN Data indication
PJ_STUN_CREATE_PERM_REQUEST	TURN CreatePermission request
PJ_STUN_CREATE_PERM_RESPONSE	TURN CreatePermission successful response.
PJ_STUN_CREATE_PERM_ERROR_RESPONSE	TURN CreatePermission failure response
PJ_STUN_CHANNEL_BIND_REQUEST	STUN/TURN ChannelBind Request
PJ_STUN_CHANNEL_BIND_RESPONSE	Successful response to STUN ChannelBind request
PJ_STUN_CHANNEL_BIND_ERROR_RESPONSE	Error response to STUN ChannelBind request.

enum pj_stun_status

STUN error codes, which goes into STUN ERROR-CODE attribute.

Enumerator:

PJ_STUN_SC_TRY_ALTERNATE	Try Alternate
PJ_STUN_SC_BAD_REQUEST	Bad Request
PJ_STUN_SC_UNAUTHORIZED	Unauthorized
PJ_STUN_SC_FORBIDDEN	Forbidden (TURN)
PJ_STUN_SC_UNKNOWN_ATTRIBUTE	Unknown Attribute
PJ_STUN_SC_ALLOCATION_MISMATCH	TURN Alloc Mismatch
PJ_STUN_SC_STALE_NONCE	Stale Nonce
PJ_STUN_SC_TRANSITIONING	Transitioning.
PJ_STUN_SC_WRONG_CREDENTIALS	TURN Wrong Credentials
PJ_STUN_SC_UNSUPP_TRANSPORT_PROTO	Unsupported Transport or Protocol (TURN)
PJ_STUN_SC_OPER_TCP_ONLY	Operation for TCP Only
PJ_STUN_SC_CONNECTION_FAILURE	Connection Failure
PJ_STUN_SC_CONNECTION_TIMEOUT	Connection Timeout
PJ_STUN_SC_ALLOCATION_QUOTA_REACHED	Allocation Quota Reached (TURN)
PJ_STUN_SC_ROLE_CONFLICT	Role Conflict
PJ_STUN_SC_SERVER_ERROR	Server Error
PJ_STUN_SC_INSUFFICIENT_CAPACITY	Insufficient Capacity (TURN)
PJ_STUN_SC_GLOBAL_FAILURE	Global Failure

Function Documentation

pj_stun_attr_hdr* pj_stun_attr_clone	(	pj_pool_t *	pool,
		const pj_stun_attr_hdr *	attr
	)

Clone a STUN attribute.

Parameters:

	pool	Pool to allocate memory.
	attr	Attribute to clone.

Returns:: Duplicate attribute.

pj_status_t pj_stun_binary_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		const pj_uint8_t *	data,
		unsigned	length,
		pj_stun_binary_attr **	p_attr
	)

Create STUN binary attribute.

Parameters:

	pool	The pool to allocate memory from.
	attr_type	The attribute type, from pj_stun_attr_type.
	data	Data to be coped to the attribute, or NULL if no data to be copied now.
	length	Length of data, or zero if no data is to be copied now.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_binary_attr_init	(	pj_stun_binary_attr *	attr,
		pj_pool_t *	pool,
		int	attr_type,
		const pj_uint8_t *	data,
		unsigned	length
	)

Initialize STUN binary attribute.

Parameters:

	attr	The attribute to be initialized.
	pool	Pool to copy data, if the data and length are set.
	attr_type	The attribute type, from pj_stun_attr_type.
	data	Data to be coped to the attribute, or NULL if no data to be copied now.
	length	Length of data, or zero if no data is to be copied now.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_empty_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		pj_stun_empty_attr **	p_attr
	)

Create STUN empty attribute.

Parameters:

	pool	The pool to allocate memory from.
	attr_type	The attribute type, from pj_stun_attr_type.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_errcode_attr_create	(	pj_pool_t *	pool,
		int	err_code,
		const pj_str_t *	err_reason,
		pj_stun_errcode_attr **	p_attr
	)

Create a STUN ERROR-CODE attribute.

Parameters:

	pool	The pool to allocate memory from.
	err_code	STUN error code.
	err_reason	Optional STUN error reason. If NULL is given, the standard error reason will be given.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

const char* pj_stun_get_attr_name ( unsigned attr_type )

Get STUN attribute name.

Returns:: attr_type The STUN attribute type (in host byte order).; The STUN attribute type name string.

const char* pj_stun_get_class_name ( unsigned msg_type )

Get STUN message class name.

Parameters:

msg_type

The STUN message type (in host byte order)

Returns:: The STUN message class name string.

pj_str_t pj_stun_get_err_reason ( int err_code )

Get STUN standard reason phrase for the specified error code.

Parameters:

err_code

The STUN error code.

Returns:: The STUN error reason phrase.

const char* pj_stun_get_method_name ( unsigned msg_type )

Get STUN message method name.

Parameters:

msg_type

The STUN message type (in host byte order)

Returns:: The STUN message method name string.

pj_status_t pj_stun_msg_add_attr	(	pj_stun_msg *	msg,
		pj_stun_attr_hdr *	attr
	)

Add STUN attribute to STUN message.

Parameters:

	msg	The STUN message.
	attr	The STUN attribute to be added to the message.

Returns:: PJ_SUCCESS on success, or PJ_ETOOMANY if there are already too many attributes in the message.

pj_status_t pj_stun_msg_add_binary_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type,
		const pj_uint8_t *	data,
		unsigned	length
	)

Create STUN binary attribute and add the attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message.
	attr_type	The attribute type, from pj_stun_attr_type.
	data	Data to be coped to the attribute, or NULL if no data to be copied now.
	length	Length of data, or zero if no data is to be copied now.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_empty_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type
	)

Create STUN empty attribute and add the attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message.
	attr_type	The attribute type, from pj_stun_attr_type.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_errcode_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	err_code,
		const pj_str_t *	err_reason
	)

Create and add STUN ERROR-CODE attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN mesage.
	err_code	STUN error code.
	err_reason	Optional STUN error reason. If NULL is given, the standard error reason will be given.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_msgint_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg
	)

Create and add STUN MESSAGE-INTEGRITY attribute.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_sockaddr_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type,
		pj_bool_t	xor_ed,
		const pj_sockaddr_t *	addr,
		unsigned	addr_len
	)

Create and add generic STUN IP address attribute to a STUN message. The addr_len and addr parameters specify whether the address is IPv4 or IPv4 address.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message.
	attr_type	Attribute type, from pj_stun_attr_type.
	xor_ed	If non-zero, the port and address will be XOR-ed with magic, to make the XOR-MAPPED-ADDRESS attribute.
	addr	A pj_sockaddr_in or pj_sockaddr_in6 structure.
	addr_len	Length of addr parameter.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_string_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type,
		const pj_str_t *	value
	)

Create and add STUN generic string attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message.
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The string value to be assigned to the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_uint64_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type,
		const pj_timestamp *	value
	)

Create and add STUN generic 64bit value attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The 64bit value to be assigned to the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_uint_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		int	attr_type,
		pj_uint32_t	value
	)

Create and add STUN generic 32bit value attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The 32bit value to be assigned to the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_add_unknown_attr	(	pj_pool_t *	pool,
		pj_stun_msg *	msg,
		unsigned	attr_cnt,
		const pj_uint16_t	attr[]
	)

Create and add STUN UNKNOWN-ATTRIBUTES attribute to the message.

Parameters:

	pool	The pool to allocate memory from.
	msg	The STUN message.
	attr_cnt	Number of attributes in the array (can be zero).
	attr	Optional array of attribute types.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_msg_check	(	const pj_uint8_t *	pdu,
		pj_size_t	pdu_len,
		unsigned	options
	)

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.

Parameters:

	pdu	The packet buffer.
	pdu_len	The length of the packet buffer.
	options	Additional options to be applied in the checking, which can be taken from pj_stun_decode_options. One of the useful option is PJ_STUN_IS_DATAGRAM which means that the pdu represents a whole STUN packet.

Returns:: PJ_SUCCESS if the PDU is a potentially valid STUN message.

pj_stun_msg* pj_stun_msg_clone	(	pj_pool_t *	pool,
		const pj_stun_msg *	msg
	)

Clone a STUN message with all of its attributes.

Parameters:

	pool	Pool to allocate memory for the new message.
	msg	The message to be cloned.

Returns:: The duplicate message.

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
	)

Create a generic STUN message.

Parameters:

	pool	Pool to create the STUN message.
	msg_type	The 14bit message type.
	magic	Magic value to be put to the mesage; for requests, the value should be PJ_STUN_MAGIC.
	tsx_id	Optional transaction ID, or NULL to let the function generates a random transaction ID.
	p_msg	Pointer to receive the message.

Returns:: PJ_SUCCESS on success.

pj_status_t pj_stun_msg_create_response	(	pj_pool_t *	pool,
		const pj_stun_msg *	req_msg,
		unsigned	err_code,
		const pj_str_t *	err_msg,
		pj_stun_msg **	p_response
	)

Create STUN response message.

Parameters:

	pool	Pool to create the mesage.
	req_msg	The request message.
	err_code	STUN error code. If this value is not zero, then error response will be created, otherwise successful response will be created.
	err_msg	Optional error message to explain err_code. If this value is NULL and err_code is not zero, the error string will be taken from the default STUN error message.
	p_response	Pointer to receive the response.

Returns:: PJ_SUCCESS on success, or the appropriate error.

pj_status_t pj_stun_msg_decode	(	pj_pool_t *	pool,
		const pj_uint8_t *	pdu,
		pj_size_t	pdu_len,
		unsigned	options,
		pj_stun_msg **	p_msg,
		pj_size_t *	p_parsed_len,
		pj_stun_msg **	p_response
	)

Decode incoming packet into STUN message.

Parameters:

	pool	Pool to allocate the message.
	pdu	The incoming packet to be parsed.
	pdu_len	The length of the incoming packet.
	options	Parsing flags, according to pj_stun_decode_options.
	p_msg	Pointer to receive the parsed message.
	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.
	p_response	Optional pointer to receive an instance of response message, if one can be created. If the packet being decoded is a request message, and it contains error, and a response can be created, then the STUN response message will be returned on this argument.

Returns:: PJ_SUCCESS if a STUN message has been successfully decoded.

char* pj_stun_msg_dump	(	const pj_stun_msg *	msg,
		char *	buffer,
		unsigned	length,
		unsigned *	printed_len
	)

Dump STUN message to a printable string output.

Parameters:

	msg	The STUN message
	buffer	Buffer where the printable string output will be printed on.
	length	Specify the maximum length of the buffer.
	printed_len	Optional pointer, which on output will be filled up with the actual length of the output string.

Returns:: The message string output.

pj_status_t pj_stun_msg_encode	(	pj_stun_msg *	msg,
		pj_uint8_t *	pkt_buf,
		pj_size_t	buf_size,
		unsigned	options,
		const pj_str_t *	key,
		pj_size_t *	p_msg_len
	)

Print the STUN message structure to a packet buffer, ready to be sent to remote destination. This function will take care about calculating the MESSAGE-INTEGRITY digest as well as FINGERPRINT value, if these attributes are present in the message.

If application wants to apply credential to the message, it MUST include a blank MESSAGE-INTEGRITY attribute in the message as the last attribute or the attribute before FINGERPRINT. This function will calculate the HMAC digest from the message using the supplied key in the parameter. The key should be set to the password if short term credential is used, or calculated from the MD5 hash of the realm, username, and password using pj_stun_create_key() if long term credential is used.

If FINGERPRINT attribute is present, this function will calculate the FINGERPRINT CRC attribute for the message. The FINGERPRINT MUST be added as the last attribute of the message.

Parameters:

	msg	The STUN message to be printed. Upon return, some fields in the header (such as message length) will be updated.
	pkt_buf	The buffer to be filled with the packet.
	buf_size	Size of the buffer.
	options	Options, which currently must be zero.
	key	Authentication key to calculate MESSAGE-INTEGRITY value. Application can create this key by using pj_stun_create_key() function.
	p_msg_len	Upon return, it will be filed with the size of the packet in bytes, or negative value on error.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_stun_attr_hdr* pj_stun_msg_find_attr	(	const pj_stun_msg *	msg,
		int	attr_type,
		unsigned	start_index
	)

Find STUN attribute in the STUN message, starting from the specified index.

Parameters:

	msg	The STUN message.
	attr_type	The attribute type to be found, from pj_stun_attr_type.
	start_index	The start index of the attribute in the message. Specify zero to start searching from the first attribute.

Returns:: The attribute instance, or NULL if it cannot be found.

pj_status_t pj_stun_msg_init	(	pj_stun_msg *	msg,
		unsigned	msg_type,
		pj_uint32_t	magic,
		const pj_uint8_t	tsx_id[12]
	)

Initialize a generic STUN message.

Parameters:

	msg	The message structure to be initialized.
	msg_type	The 14bit message type (see pj_stun_msg_type constants).
	magic	Magic value to be put to the mesage; for requests, the value normally should be PJ_STUN_MAGIC.
	tsx_id	Optional transaction ID, or NULL to let the function generates a random transaction ID.

Returns:: PJ_SUCCESS on success.

pj_status_t pj_stun_msgint_attr_create	(	pj_pool_t *	pool,
		pj_stun_msgint_attr **	p_attr
	)

Create a STUN MESSAGE-INTEGRITY attribute.

Parameters:

	pool	The pool to allocate memory from.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

int pj_stun_set_padding_char ( int chr )

Internal: set the padding character for string attribute. The default padding character is PJ_STUN_STRING_ATTR_PAD_CHR.

Returns:: The previous padding character.

pj_status_t pj_stun_sockaddr_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		pj_bool_t	xor_ed,
		const pj_sockaddr_t *	addr,
		unsigned	addr_len,
		pj_stun_sockaddr_attr **	p_attr
	)

Create a generic STUN IP address attribute. The addr_len and addr parameters specify whether the address is IPv4 or IPv4 address.

Parameters:

	pool	The pool to allocate memory from.
	attr_type	Attribute type, from pj_stun_attr_type.
	xor_ed	If non-zero, the port and address will be XOR-ed with magic, to make the XOR-MAPPED-ADDRESS attribute.
	addr	A pj_sockaddr_in or pj_sockaddr_in6 structure.
	addr_len	Length of addr parameter.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_sockaddr_attr_init	(	pj_stun_sockaddr_attr *	attr,
		int	attr_type,
		pj_bool_t	xor_ed,
		const pj_sockaddr_t *	addr,
		unsigned	addr_len
	)

Initialize generic STUN IP address attribute. The addr_len and addr parameters specify whether the address is IPv4 or IPv4 address.

Parameters:

	attr	The socket address attribute to initialize.
	attr_type	Attribute type, from pj_stun_attr_type.
	xor_ed	If non-zero, the port and address will be XOR-ed with magic, to make the XOR-MAPPED-ADDRESS attribute.
	addr	A pj_sockaddr_in or pj_sockaddr_in6 structure.
	addr_len	Length of addr parameter.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_string_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		const pj_str_t *	value,
		pj_stun_string_attr **	p_attr
	)

Create a STUN generic string attribute.

Parameters:

	pool	The pool to allocate memory from.
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The string value to be assigned to the attribute.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_string_attr_init	(	pj_stun_string_attr *	attr,
		pj_pool_t *	pool,
		int	attr_type,
		const pj_str_t *	value
	)

Initialize a STUN generic string attribute.

Parameters:

	attr	The string attribute to be initialized.
	pool	Pool to duplicate the value into the attribute, if value is not NULL or empty.
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The string value to be assigned to the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_uint64_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		const pj_timestamp *	value,
		pj_stun_uint64_attr **	p_attr
	)

Create a STUN generic 64bit value attribute.

Parameters:

	pool	Pool to allocate memory from.
	attr_type	Attribute type, from pj_stun_attr_type.
	value	Optional value to be assigned.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_uint_attr_create	(	pj_pool_t *	pool,
		int	attr_type,
		pj_uint32_t	value,
		pj_stun_uint_attr **	p_attr
	)

Create a STUN generic 32bit value attribute.

Parameters:

	pool	The pool to allocate memory from.
	attr_type	Attribute type, from pj_stun_attr_type.
	value	The 32bit value to be assigned to the attribute.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

pj_status_t pj_stun_unknown_attr_create	(	pj_pool_t *	pool,
		unsigned	attr_cnt,
		const pj_uint16_t	attr[],
		pj_stun_unknown_attr **	p_attr
	)

Create instance of STUN UNKNOWN-ATTRIBUTES attribute and copy the unknown attribute array to the attribute.

Parameters:

	pool	The pool to allocate memory from.
	attr_cnt	Number of attributes in the array (can be zero).
	attr	Optional array of attributes.
	p_attr	Pointer to receive the attribute.

Returns:: PJ_SUCCESS on success or the appropriate error code.

STUN Message Representation and Parsing [Base STUN objects]

Data Structures

Defines

Enumerations

Functions

Define Documentation

Enumeration Type Documentation

Function Documentation

STUN Message Representation and Parsing
[Base STUN objects]