diff --git a/include/re_bfcp.h b/include/re_bfcp.h index ce92dc2..c6591f1 100644 --- a/include/re_bfcp.h +++ b/include/re_bfcp.h @@ -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); diff --git a/src/bfcp/attr.c b/src/bfcp/attr.c index 92d060f..bbf496e 100644 --- a/src/bfcp/attr.c +++ b/src/bfcp/attr.c @@ -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) { diff --git a/src/bfcp/msg.c b/src/bfcp/msg.c index 9b7ffe3..073f295 100644 --- a/src/bfcp/msg.c +++ b/src/bfcp/msg.c @@ -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; diff --git a/src/bfcp/rep.c b/src/bfcp/rep.c index f296bfa..e36840a 100644 --- a/src/bfcp/rep.c +++ b/src/bfcp/rep.c @@ -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, ...) { diff --git a/src/bfcp/req.c b/src/bfcp/req.c index d464a01..36a9a31 100644 --- a/src/bfcp/req.c +++ b/src/bfcp/req.c @@ -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, diff --git a/src/bfcp/sock.c b/src/bfcp/sock.c index fbff0e3..fd307e8 100644 --- a/src/bfcp/sock.c +++ b/src/bfcp/sock.c @@ -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) diff --git a/src/bfcp/transp.c b/src/bfcp/transp.c index 8a6da3a..d61aaea 100644 --- a/src/bfcp/transp.c +++ b/src/bfcp/transp.c @@ -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) {