bfcp: doxygen comments

This commit is contained in:
Richard Aas 2011-12-08 13:56:52 +00:00
parent 57e2151625
commit 3729d9fc6f
7 changed files with 217 additions and 0 deletions

View file

@ -5,6 +5,7 @@
*/
/** BFCP Version */
enum {BFCP_VERSION = 1};
/** BFCP Primitives */
@ -71,6 +72,7 @@ enum bfcp_err {
BFCP_ERR_USE_TLS = 9
};
/** BFCP Priority */
enum bfcp_prio {
BFCP_PRIO_LOWEST = 0,
BFCP_PRIO_LOW = 1,
@ -79,51 +81,60 @@ enum bfcp_prio {
BFCP_PRIO_HIGHEST = 4
};
/** BFCP Request status */
struct bfcp_reqstat {
enum bfcp_rstat stat;
uint8_t qpos;
};
/** BFCP Error code */
struct bfcp_errcode {
enum bfcp_err code;
uint8_t *details; /* optional */
size_t len;
};
/** BFCP supported attributes */
struct bfcp_supattr {
enum bfcp_attrib *attrv;
size_t attrc;
};
/** BFCP supported primitives */
struct bfcp_supprim {
enum bfcp_prim *primv;
size_t primc;
};
/** BFCP overall request status */
struct bfcp_overall_reqstat {
uint16_t freqid;
struct bfcp_reqstat reqstat;
char *statinfo;
};
/** BFCP beneficiary information */
struct bfcp_beneficiary_info {
uint16_t bfid;
char *dname;
char *uri;
};
/** BFCP requested by information */
struct bfcp_reqby_info {
uint16_t rbid;
char *dname;
char *uri;
};
/** BFCP floor request status */
struct bfcp_floor_reqstat {
uint16_t floorid;
struct bfcp_reqstat reqstat;
char *statinfo;
};
/** BFCP floor request info */
struct bfcp_floor_reqinfo {
uint16_t freqid;
struct bfcp_overall_reqstat ors;
@ -135,6 +146,7 @@ struct bfcp_floor_reqinfo {
char *ppi;
};
/** BFCP Attribute */
struct bfcp_attr {
struct le le;
enum bfcp_attrib type;
@ -168,6 +180,7 @@ struct bfcp_attr {
} v;
};
/** BFCP Transport */
enum bfcp_transp {
BFCP_TRANSP_TCP = 0,
BFCP_TRANSP_TLS = 1
@ -178,6 +191,14 @@ enum bfcp_transp {
struct bfcp_msg;
/**
* Defines the BFCP attribute handler
*
* @param attr BFCP attribute
* @param arg Handler argument
*
* @return True to stop processing, false to continue
*/
typedef bool (bfcp_attr_h)(const struct bfcp_attr *attr, void *arg);
int bfcp_msg_vencode(struct mbuf *mb, enum bfcp_prim prim,
@ -219,7 +240,21 @@ struct tls;
struct bfcp_sock;
struct bfcp_ctrans;
/**
* Defines the BFCP message handler
*
* @param msg BFCP message
* @param arg Handler argument
*/
typedef void (bfcp_msg_h)(const struct bfcp_msg *msg, void *arg);
/**
* Defines the BFCP response handler
*
* @param err Error code
* @param msg BFCP message
* @param arg Handler argument
*/
typedef void (bfcp_resp_h)(int err, const struct bfcp_msg *msg, void *arg);

View file

@ -535,6 +535,13 @@ int bfcp_attr_decode(struct bfcp_attr **attrp, struct mbuf *mb)
}
/**
* Get the BFCP attribute name
*
* @param attr BFCP attribute
*
* @return String with BFCP attribute name
*/
const char *bfcp_attr_name(enum bfcp_attrib attr)
{
switch (attr) {
@ -738,6 +745,13 @@ bool bfcp_attr_isgrouped(enum bfcp_attrib attr)
}
/**
* Get the BFCP Error code name
*
* @param code BFCP Error code
*
* @return String with error code
*/
const char *bfcp_errcode_name(enum bfcp_err code)
{
switch (code) {

View file

@ -29,6 +29,19 @@ static void destructor(void *arg)
}
/**
* Encode a BFCP message with variable arguments
*
* @param mb Mbuf to encode into
* @param prim BFCP Primitive
* @param confid Conference ID
* @param tid Transaction ID
* @param userid User ID
* @param attrc Number of attributes
* @param ap Variable argument of attributes
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_msg_vencode(struct mbuf *mb, enum bfcp_prim prim,
uint32_t confid, uint16_t tid, uint16_t userid,
uint32_t attrc, va_list ap)
@ -69,6 +82,18 @@ int bfcp_msg_vencode(struct mbuf *mb, enum bfcp_prim prim,
}
/**
* Encode a BFCP message
*
* @param mb Mbuf to encode into
* @param prim BFCP Primitive
* @param confid Conference ID
* @param tid Transaction ID
* @param userid User ID
* @param attrc Number of attributes
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_msg_encode(struct mbuf *mb, enum bfcp_prim prim, uint32_t confid,
uint16_t tid, uint16_t userid, uint32_t attrc, ...)
{
@ -83,6 +108,15 @@ int bfcp_msg_encode(struct mbuf *mb, enum bfcp_prim prim, uint32_t confid,
}
/**
* Decode a BFCP message from a buffer
*
* @param msgp Pointer to allocated and decoded BFCP message
* @param mb Mbuf to decode from
* @param src Source network address (optional)
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_msg_decode(struct bfcp_msg **msgp, struct mbuf *mb,
const struct sa *src)
{
@ -137,6 +171,14 @@ static bool attr_match(const struct bfcp_attr *attr, void *arg)
}
/**
* Get a BFCP attribute from a BFCP message
*
* @param msg BFCP message
* @param type Attribute type
*
* @return Matching BFCP attribute if found, otherwise NULL
*/
struct bfcp_attr *bfcp_msg_attr(const struct bfcp_msg *msg,
enum bfcp_attrib type)
{
@ -144,6 +186,15 @@ struct bfcp_attr *bfcp_msg_attr(const struct bfcp_msg *msg,
}
/**
* Apply a function handler to all attributes in a BFCP message
*
* @param msg BFCP message
* @param h Handler
* @param arg Handler argument
*
* @return BFCP attribute returned by handler, or NULL
*/
struct bfcp_attr *bfcp_msg_attr_apply(const struct bfcp_msg *msg,
bfcp_attr_h *h, void *arg)
{
@ -170,6 +221,14 @@ static bool attr_print(const struct bfcp_attr *attr, void *arg)
}
/**
* Print a BFCP message
*
* @param pf Print function
* @param msg BFCP message
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_msg_print(struct re_printf *pf, const struct bfcp_msg *msg)
{
int err;
@ -187,30 +246,65 @@ int bfcp_msg_print(struct re_printf *pf, const struct bfcp_msg *msg)
}
/**
* Get the BFCP primitive of a BFCP message
*
* @param msg BFCP message
*
* @return The BFCP primitive
*/
enum bfcp_prim bfcp_msg_prim(const struct bfcp_msg *msg)
{
return msg ? msg->hdr.prim : 0;
}
/**
* Get the Conference ID of a BFCP message
*
* @param msg BFCP message
*
* @return The Conference ID
*/
uint32_t bfcp_msg_confid(const struct bfcp_msg *msg)
{
return msg ? msg->hdr.confid : 0;
}
/**
* Get the Transaction ID of a BFCP message
*
* @param msg BFCP message
*
* @return The Transaction ID
*/
uint16_t bfcp_msg_tid(const struct bfcp_msg *msg)
{
return msg ? msg->hdr.tid : 0;
}
/**
* Get the User ID of a BFCP message
*
* @param msg BFCP message
*
* @return The User ID
*/
uint16_t bfcp_msg_userid(const struct bfcp_msg *msg)
{
return msg ? msg->hdr.userid : 0;
}
/**
* Get the BFCP Request status name
*
* @param rstat Request status
*
* @return String with BFCP Request status name
*/
const char *bfcp_reqstat_name(enum bfcp_rstat rstat)
{
switch (rstat) {
@ -227,6 +321,13 @@ const char *bfcp_reqstat_name(enum bfcp_rstat rstat)
}
/**
* Get the BFCP primitive name
*
* @param prim BFCP primitive
*
* @return String with BFCP primitive name
*/
const char *bfcp_prim_name(enum bfcp_prim prim)
{
switch (prim) {
@ -249,6 +350,13 @@ const char *bfcp_prim_name(enum bfcp_prim prim)
}
/**
* Get the source network address of a BFCP message
*
* @param msg BFCP message
*
* @return Source network address
*/
const struct sa *bfcp_msg_src(const struct bfcp_msg *msg)
{
return msg ? &msg->src : NULL;

View file

@ -14,6 +14,16 @@
#include "bfcp.h"
/**
* Send BFCP reply
*
* @param sock BFCP socket
* @param req BFCP request to reply to
* @param prim BFCP primitive
* @param attrc Number of attributes
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_reply(struct bfcp_sock *sock, const struct bfcp_msg *req,
enum bfcp_prim prim, uint32_t attrc, ...)
{
@ -48,6 +58,15 @@ int bfcp_reply(struct bfcp_sock *sock, const struct bfcp_msg *req,
}
/**
* Send BFCP error reply
*
* @param sock BFCP socket
* @param req BFCP request to reply to
* @param code BFCP Error code
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_ereply(struct bfcp_sock *sock, const struct bfcp_msg *req,
enum bfcp_err code, ...)
{

View file

@ -107,6 +107,21 @@ struct bfcp_ctrans *bfcp_ctrans_find(struct bfcp_sock *sock, uint16_t tid)
}
/**
* Send a BFCP request with variable number of attributes
*
* @param ctp Pointer to allocated transaction (optional)
* @param sock BFCP socket
* @param dst Destination network address
* @param prim BFCP primitive
* @param confid Conference ID
* @param userid User ID
* @param resph Response handler (optional)
* @param arg Handler argument
* @param attrc Number of BFCP attributes
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_request(struct bfcp_ctrans **ctp, struct bfcp_sock *sock,
const struct sa *dst,
enum bfcp_prim prim, uint32_t confid, uint16_t userid,

View file

@ -215,6 +215,18 @@ static struct bfcp_conn *findconn(const struct bfcp_sock *bs,
}
/**
* Listen on a BFCP socket
*
* @param sockp Pointer to allocated BFCP socket object
* @param transp BFCP transport
* @param tls TLS context, used for secure transport (optional)
* @param laddr Local network address (optional)
* @param msgh BFCP message handler (optional)
* @param arg Handler argument
*
* @return 0 if success, otherwise errorcode
*/
int bfcp_listen(struct bfcp_sock **sockp, enum bfcp_transp transp,
struct tls *tls, const struct sa *laddr,
bfcp_msg_h *msgh, void *arg)

View file

@ -16,6 +16,13 @@
#include "bfcp.h"
/**
* Check if BFCP transport is reliable
*
* @param tp BFCP transport
*
* @return True if reliable, false if un-reliable
*/
bool bfcp_transp_reliable(enum bfcp_transp tp)
{
switch (tp) {
@ -27,6 +34,13 @@ bool bfcp_transp_reliable(enum bfcp_transp tp)
}
/**
* Get the BFCP Transport protocol, suitable for SDP
*
* @param tp BFCP transport
*
* @return String with BFCP transport protocol
*/
const char *bfcp_transp_proto(enum bfcp_transp tp)
{
switch (tp) {