stun_msg.h

来自「一个开源的sip源代码」· C头文件 代码 · 共 1,601 行 · 第 1/4 页

PJ_DECL(void) pj_stun_create_key(pj_pool_t *pool,
				 pj_str_t *key,
				 const pj_str_t *realm,
				 const pj_str_t *username,
				 const pj_str_t *passwd);



/**
 * 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	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.
 *
 * @return		PJ_SUCCESS if the PDU is a potentially valid STUN
 *			message.
 */
PJ_DECL(pj_status_t) pj_stun_msg_check(const pj_uint8_t *pdu, 
				       unsigned pdu_len, unsigned options);


/**
 * Decode 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, according to pj_stun_decode_options.
 * @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_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.
 *
 * @return		PJ_SUCCESS if a STUN message has been successfully
 *			decoded.
 */
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,
				        pj_stun_msg **p_response);

/**
 * Dump STUN message to a printable string output.
 *
 * @param msg		The STUN message
 * @param buffer	Buffer where the printable string output will
 *			be printed on.
 * @param length	Specify the maximum length of the buffer.
 * @param printed_len	Optional pointer, which on output will be filled
 *			up with the actual length of the output string.
 *
 * @return		The message string output.
 */
#if PJ_LOG_MAX_LEVEL > 0
PJ_DECL(char*) pj_stun_msg_dump(const pj_stun_msg *msg,
			        char *buffer,
			        unsigned length,
				unsigned *printed_len);
#else
#   define pj_stun_msg_dump(msg, buf, length, printed_len)  ""
#endif


/**
 * 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, from pj_stun_attr_type.
 * @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. The \a addr_len and
 * \a addr parameters specify whether the address is IPv4 or IPv4
 * address.
 *
 * @param pool		The pool to allocate memory from.
 * @param attr_type	Attribute type, from #pj_stun_attr_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		A pj_sockaddr_in or pj_sockaddr_in6 structure.
 * @param addr_len	Length of \a addr parameter.
 * @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_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 and add generic STUN IP address attribute to a STUN message.
 * The \a addr_len and \a addr parameters specify whether the address is 
 * IPv4 or IPv4 address.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message.
 * @param attr_type	Attribute type, from #pj_stun_attr_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		A pj_sockaddr_in or pj_sockaddr_in6 structure.
 * @param addr_len	Length of \a addr parameter.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 a STUN generic string attribute.
 *
 * @param pool		The pool to allocate memory from.
 * @param attr_type	Attribute type, from #pj_stun_attr_type.
 * @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_string_attr_create(pj_pool_t *pool,
					        int attr_type,
					        const pj_str_t *value,
					        pj_stun_string_attr **p_attr);

/**
 * Create and add STUN generic string attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message.
 * @param attr_type	Attribute type, from #pj_stun_attr_type.
 * @param value		The string value to be assigned to the attribute.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 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_uint_attr_create(pj_pool_t *pool,
					      int attr_type,
					      pj_uint32_t value,
					      pj_stun_uint_attr **p_attr);

/**
 * Create and add STUN generic 32bit value attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message
 * @param attr_type	Attribute type, from #pj_stun_attr_type.
 * @param value		The 32bit value to be assigned to the attribute.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 a STUN generic 64bit value attribute.
 *
 * @param pool		Pool to allocate memory from.
 * @param attr_type	Attribute type, from #pj_stun_attr_type.
 * @param value		Optional value to be assigned.
 * @param p_attr	Pointer to receive the attribute.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DEF(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 and add STUN generic 64bit value attribute to the message. 
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message
 * @param attr_type	Attribute type, from #pj_stun_attr_type.
 * @param value		The 64bit value to be assigned to the attribute.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 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_msgint_attr_create(pj_pool_t *pool,
						pj_stun_msgint_attr **p_attr);

/** 
 * Create and add STUN MESSAGE-INTEGRITY attribute.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(pj_status_t) pj_stun_msg_add_msgint_attr(pj_pool_t *pool,
						 pj_stun_msg *msg);

/**
 * 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_errcode_attr_create(pj_pool_t *pool,
						int err_code,
						const pj_str_t *err_reason,
						pj_stun_errcode_attr **p_attr);


/**
 * Create and add STUN ERROR-CODE attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN mesage.
 * @param err_code	STUN error code.
 * @param err_reason	Optional STUN error reason. If NULL is given, the
 *			standard error reason will be given.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 instance of STUN UNKNOWN-ATTRIBUTES attribute and copy the
 * unknown attribute array to the 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,
						const pj_uint16_t attr[],
						pj_stun_unknown_attr **p_attr);

/**
 * Create and add STUN UNKNOWN-ATTRIBUTES attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message.
 * @param attr_cnt	Number of attributes in the array (can be zero).
 * @param attr		Optional array of attributes.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 STUN binary attribute.
 *
 * @param pool		The pool to allocate memory from.
 * @param attr_type	The attribute type, from #pj_stun_attr_type.
 * @param data		Data to be coped to the attribute, or NULL
 *			if no data to be copied now.
 * @param length	Length of data, or zero if no data is to be
 *			copied now.
 * @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,
					        const pj_uint8_t *data,
					        unsigned length,
					        pj_stun_binary_attr **p_attr);

/**
 * Create STUN binary attribute and add the attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message.
 * @param attr_type	The attribute type, from #pj_stun_attr_type.
 * @param data		Data to be coped to the attribute, or NULL
 *			if no data to be copied now.
 * @param length	Length of data, or zero if no data is to be
 *			copied now.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(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 empty attribute.
 *
 * @param pool		The pool to allocate memory from.
 * @param attr_type	The attribute type, from #pj_stun_attr_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_empty_attr_create(pj_pool_t *pool,
					       int attr_type,
					       pj_stun_empty_attr **p_attr);

/**
 * Create STUN empty attribute and add the attribute to the message.
 *
 * @param pool		The pool to allocate memory from.
 * @param msg		The STUN message.
 * @param attr_type	The attribute type, from #pj_stun_attr_type.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(pj_status_t) pj_stun_msg_add_empty_attr(pj_pool_t *pool,
						pj_stun_msg *msg,
						int attr_type);

/**
 * @}
 */


PJ_END_DECL


#endif	/* __PJNATH_STUN_MSG_H__ */