stv0g/re
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

stun: added doxygen comments

Browse source
This commit is contained in:
Richard Aas 2014-11-24 06:38:19 +00:00
parent de76184842
commit 165e9a87fe
9 changed files with 256 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
include/re_stun.h
View file

@ -99,6 +99,7 @@ struct stun_even_port {
bool r;
};
/** Defines a STUN attribute */
struct stun_attr {
struct le le;
uint16_t type;
@ -145,12 +146,13 @@ struct stun_attr {
};
/** STUN Configuration */
struct stun_conf {
uint32_t rto;
uint32_t rc;
uint32_t rm;
uint32_t ti;
uint8_t tos; /**< Type-of-service field */
uint32_t rto; /**< RTO Retransmission TimeOut [ms] */
uint32_t rc; /**< Rc Retransmission count (default 7) */
uint32_t rm; /**< Rm Max retransmissions (default 16) */
uint32_t ti; /**< Ti Timeout for reliable transport [ms] */
uint8_t tos; /**< Type-of-service field */
};

3
mk/Doxyfile
View file

@ -89,8 +89,7 @@ FILE_PATTERNS = *.c \
RECURSIVE = YES
EXCLUDE = test.c \
include/re_bitv.h \
src/md5/md5.h src/md5/md5.c \
src/stun include/re_stun.h
src/md5/md5.h src/md5/md5.c
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS = */.svn/*

7
src/stun/attr.c
View file

@ -348,6 +348,13 @@ int stun_attr_decode(struct stun_attr **attrp, struct mbuf *mb,
}
/**
* Get the name of a STUN attribute
*
* @param type STUN attribute type
*
* @return String with attribute name
*/
const char *stun_attr_name(uint16_t type)
{
switch (type) {

9
src/stun/ctrans.c
View file

@ -152,6 +152,15 @@ static void tcp_close_handler(int err, void *arg)
}
/**
* Handle an incoming STUN message to a Client Transaction
*
* @param stun STUN instance
* @param msg STUN message
* @param ua Unknown attributes
*
* @return 0 if success, otherwise errorcode
*/
int stun_ctrans_recv(struct stun *stun, const struct stun_msg *msg,
const struct stun_unknown_attr *ua)
{

17
src/stun/ind.c
View file

@ -13,6 +13,23 @@
#include "stun.h"
/**
* Send a STUN Indication message
*
* @param proto Transport Protocol
* @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn)
* @param dst Destination network address
* @param presz Number of bytes in preamble, if sending over TURN
* @param method STUN Method
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param attrc Number of attributes to encode (variable arguments)
* @param ... Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_indication(int proto, void *sock, const struct sa *dst, size_t presz,
uint16_t method, const uint8_t *key, size_t keylen,
bool fp, uint32_t attrc, ...)

115
src/stun/msg.c
View file

@ -68,6 +68,12 @@ static void destructor(void *arg)
/**
* Decode a buffer to a STUN Message
*
* @param msgpp Pointer to allocation STUN message
* @param mb Buffer containing the raw STUN packet
* @param ua Unknown attributes (optional)
*
* @return 0 if success, otherwise errorcode
*
* @note `mb' will be referenced
*/
int stun_msg_decode(struct stun_msg **msgpp, struct mbuf *mb,
@ -127,36 +133,79 @@ int stun_msg_decode(struct stun_msg **msgpp, struct mbuf *mb,
}
/**
* Get the STUN message type
*
* @param msg STUN Message
*
* @return STUN Message type
*/
uint16_t stun_msg_type(const struct stun_msg *msg)
{
return msg ? msg->hdr.type : 0;
}
/**
* Get the STUN message class
*
* @param msg STUN Message
*
* @return STUN Message class
*/
uint16_t stun_msg_class(const struct stun_msg *msg)
{
return STUN_CLASS(stun_msg_type(msg));
}
/**
* Get the STUN message method
*
* @param msg STUN Message
*
* @return STUN Message method
*/
uint16_t stun_msg_method(const struct stun_msg *msg)
{
return STUN_METHOD(stun_msg_type(msg));
}
/**
* Get the STUN message Transaction-ID
*
* @param msg STUN Message
*
* @return STUN Message Transaction-ID
*/
const uint8_t *stun_msg_tid(const struct stun_msg *msg)
{
return msg ? msg->hdr.tid : NULL;
}
/**
* Check if a STUN Message has the magic cookie
*
* @param msg STUN Message
*
* @return true if Magic Cookie, otherwise false
*/
bool stun_msg_mcookie(const struct stun_msg *msg)
{
return msg && (STUN_MAGIC_COOKIE == msg->hdr.cookie);
}
/**
* Lookup a STUN attribute in a STUN message
*
* @param msg STUN Message
* @param type STUN Attribute type
*
* @return STUN Attribute if found, otherwise NULL
*/
struct stun_attr *stun_msg_attr(const struct stun_msg *msg, uint16_t type)
{
struct le *le = msg ? list_head(&msg->attrl) : NULL;
@ -174,6 +223,15 @@ struct stun_attr *stun_msg_attr(const struct stun_msg *msg, uint16_t type)
}
/**
* Apply a function handler to all STUN attribute
*
* @param msg STUN Message
* @param h Attribute handler
* @param arg Handler argument
*
* @return STUN attribute if handler returned true, otherwise NULL
*/
struct stun_attr *stun_msg_attr_apply(const struct stun_msg *msg,
stun_attr_h *h, void *arg)
{
@ -192,6 +250,24 @@ struct stun_attr *stun_msg_attr_apply(const struct stun_msg *msg,
}
/**
* Encode a STUN message
*
* @param mb Buffer to encode message into
* @param method STUN Method
* @param class STUN Method class
* @param tid Transaction ID
* @param ec STUN error code (optional)
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param padding Padding byte
* @param attrc Number of attributes to encode (variable arguments)
* @param ap Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_msg_vencode(struct mbuf *mb, uint16_t method, uint8_t class,
const uint8_t *tid, const struct stun_errcode *ec,
const uint8_t *key, size_t keylen, bool fp,
@ -265,6 +341,24 @@ int stun_msg_vencode(struct mbuf *mb, uint16_t method, uint8_t class,
}
/**
* Encode a STUN message
*
* @param mb Buffer to encode message into
* @param method STUN Method
* @param class STUN Method class
* @param tid Transaction ID
* @param ec STUN error code (optional)
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param padding Padding byte
* @param attrc Number of attributes to encode (variable arguments)
* @param ... Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_msg_encode(struct mbuf *mb, uint16_t method, uint8_t class,
const uint8_t *tid, const struct stun_errcode *ec,
const uint8_t *key, size_t keylen, bool fp,
@ -282,6 +376,15 @@ int stun_msg_encode(struct mbuf *mb, uint16_t method, uint8_t class,
}
/**
* Verify the Message-Integrity of a STUN message
*
* @param msg STUN Message
* @param key Authentication key
* @param keylen Number of bytes in authentication key
*
* @return 0 if verified, otherwise errorcode
*/
int stun_msg_chk_mi(const struct stun_msg *msg, const uint8_t *key,
size_t keylen)
{
@ -321,6 +424,13 @@ int stun_msg_chk_mi(const struct stun_msg *msg, const uint8_t *key,
}
/**
* Check the Fingerprint of a STUN message
*
* @param msg STUN Message
*
* @return 0 if fingerprint matches, otherwise errorcode
*/
int stun_msg_chk_fingerprint(const struct stun_msg *msg)
{
struct stun_attr *fp;
@ -355,6 +465,11 @@ static bool attr_print(const struct stun_attr *attr, void *arg)
}
/**
* Print a STUN message to STDOUT
*
* @param msg STUN Message
*/
void stun_msg_dump(const struct stun_msg *msg)
{
if (!msg)

36
src/stun/rep.c
View file

@ -12,6 +12,23 @@
#include "stun.h"
/**
* Send a STUN response message
*
* @param proto Transport Protocol
* @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn)
* @param dst Destination network address
* @param presz Number of bytes in preamble, if sending over TURN
* @param req Matching STUN request
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param attrc Number of attributes to encode (variable arguments)
* @param ... Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_reply(int proto, void *sock, const struct sa *dst, size_t presz,
const struct stun_msg *req, const uint8_t *key,
size_t keylen, bool fp, uint32_t attrc, ...)
@ -46,6 +63,25 @@ int stun_reply(int proto, void *sock, const struct sa *dst, size_t presz,
}
/**
* Send a STUN error response
*
* @param proto Transport Protocol
* @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn)
* @param dst Destination network address
* @param presz Number of bytes in preamble, if sending over TURN
* @param req Matching STUN request
* @param scode Status code
* @param reason Reason string
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param attrc Number of attributes to encode (variable arguments)
* @param ... Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_ereply(int proto, void *sock, const struct sa *dst, size_t presz,
const struct stun_msg *req, uint16_t scode,
const char *reason, const uint8_t *key, size_t keylen,

21
src/stun/req.c
View file

@ -13,6 +13,27 @@
#include "stun.h"
/**
* Send a STUN request using a client transaction
*
* @param ctp Pointer to allocated client transaction (optional)
* @param stun STUN Instance
* @param proto Transport Protocol
* @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn)
* @param dst Destination network address
* @param presz Number of bytes in preamble, if sending over TURN
* @param method STUN Method
* @param key Authentication key (optional)
* @param keylen Number of bytes in authentication key
* @param fp Use STUN Fingerprint attribute
* @param resph Response handler
* @param arg Response handler argument
* @param attrc Number of attributes to encode (variable arguments)
* @param ... Variable list of attribute-tuples
* Each attribute has 2 arguments, attribute type and value
*
* @return 0 if success, otherwise errorcode
*/
int stun_request(struct stun_ctrans **ctp, struct stun *stun, int proto,
void *sock, const struct sa *dst, size_t presz,
uint16_t method, const uint8_t *key, size_t keylen, bool fp,

43
src/stun/stun.c
View file

@ -36,6 +36,16 @@ static void destructor(void *arg)
}
/**
* Allocate a new STUN instance
*
* @param stunp Pointer to allocated STUN instance
* @param conf STUN configuration (optional)
* @param indh STUN Indication handler (optional)
* @param arg STUN Indication handler argument
*
* @return 0 if success, otherwise errorcode
*/
int stun_alloc(struct stun **stunp, const struct stun_conf *conf,
stun_ind_h *indh, void *arg)
{
@ -58,12 +68,29 @@ int stun_alloc(struct stun **stunp, const struct stun_conf *conf,
}
/**
* Get STUN configuration object
*
* @param stun STUN Instance
*
* @return STUN configuration
*/
struct stun_conf *stun_conf(struct stun *stun)
{
return stun ? &stun->conf : NULL;
}
/**
* Send a STUN message
*
* @param proto Transport protocol (IPPROTO_UDP or IPPROTO_TCP)
* @param sock Socket, UDP (struct udp_sock) or TCP (struct tcp_conn)
* @param dst Destination network address (UDP only)
* @param mb Buffer containing the STUN message
*
* @return 0 if success, otherwise errorcode
*/
int stun_send(int proto, void *sock, const struct sa *dst, struct mbuf *mb)
{
int err;
@ -90,6 +117,14 @@ int stun_send(int proto, void *sock, const struct sa *dst, struct mbuf *mb)
}
/**
* Receive a STUN message
*
* @param stun STUN Instance
* @param mb Buffer containing STUN message
*
* @return 0 if success, otherwise errorcode
*/
int stun_recv(struct stun *stun, struct mbuf *mb)
{
struct stun_unknown_attr ua;
@ -128,6 +163,14 @@ int stun_recv(struct stun *stun, struct mbuf *mb)
}
/**
* Print STUN instance debug information
*
* @param pf Print function
* @param stun STUN Instance
*
* @return 0 if success, otherwise errorcode
*/
int stun_debug(struct re_printf *pf, const struct stun *stun)
{
if (!stun)