update/extend doxygen documentation
It's a pity that even with this patch we still are fare away from having
the whole API documented. However, at least we have a more solid
foundation. Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.
Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3
diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c
index 2cc0645..20d0075 100644
--- a/src/gsm/gsm48_ie.c
+++ b/src/gsm/gsm48_ie.c
@@ -34,12 +34,20 @@
#include <osmocom/gsm/protocol/gsm_04_08.h>
#include <osmocom/gsm/gsm48_ie.h>
+/*! \addtogroup gsm0408
+ * @{
+ */
+
static const char bcd_num_digits[] = {
'0', '1', '2', '3', '4', '5', '6', '7',
'8', '9', '*', '#', 'a', 'b', 'c', '\0'
};
-/* decode a 'called/calling/connect party BCD number' as in 10.5.4.7 */
+/*! \brief decode a 'called/calling/connect party BCD number' as in 10.5.4.7
+ * \param[out] Caller-provided output buffer
+ * \param[in] bcd_lv Length-Value portion of to-be-decoded IE
+ * \param[in] h_len Length of an optional heder between L and V portion
+ * \returns - in case of success; negative on error */
int gsm48_decode_bcd_number(char *output, int output_len,
const uint8_t *bcd_lv, int h_len)
{
@@ -65,7 +73,7 @@
return 0;
}
-/* convert a single ASCII character to call-control BCD */
+/*! \brief convert a single ASCII character to call-control BCD */
static int asc_to_bcd(const char asc)
{
int i;
@@ -77,7 +85,12 @@
return -EINVAL;
}
-/* convert a ASCII phone number to 'called/calling/connect party BCD number' */
+/*! \brief convert a ASCII phone number to 'called/calling/connect party BCD number'
+ * \param[out] bcd_lv Caller-provided output buffer
+ * \param[in] max_len Maximum Length of \a bcd_lv
+ * \param[in] h_len Length of an optional heder between L and V portion
+ * \param[in] input phone number as 0-terminated ASCII
+ * \returns number of bytes used in \a bcd_lv */
int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len,
int h_len, const char *input)
{
@@ -110,7 +123,10 @@
return (bcd_cur - bcd_lv);
}
-/* TS 04.08 10.5.4.5: decode 'bearer capability' */
+/*! \brief Decode TS 04.08 Bearer Capability IE (10.5.4.5)
+ * \param[out] Caller-provided memory for decoded output
+ * \[aram[in] LV portion of TS 04.08 Bearer Capability
+ * \returns 0 on success; negative on error */
int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap,
const uint8_t *lv)
{
@@ -219,7 +235,11 @@
return 0;
}
-/* TS 04.08 10.5.4.5: encode 'bearer capability' */
+/*! \brief Encode TS 04.08 Bearer Capability IE (10.5.4.5)
+ * \param[out] msg Message Buffer to which IE is to be appended
+ * \param[in] lv_only Write only LV portion (1) or TLV (0)
+ * \param[in] bcap Decoded Bearer Capability to be encoded
+ * \returns 0 on success; negative on error */
int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only,
const struct gsm_mncc_bearer_cap *bcap)
{
@@ -274,7 +294,10 @@
return 0;
}
-/* TS 04.08 10.5.4.5a: decode 'call control cap' */
+/*! \brief Decode TS 04.08 Call Control Capabilities IE (10.5.4.5a)
+ * \param[out] Caller-provided memory for decoded CC capabilities
+ * \param[in] lv Length-Value of IE
+ * \retursns 0 on success; negative on error */
int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv)
{
uint8_t in_len = lv[0];
@@ -289,7 +312,10 @@
return 0;
}
-/* TS 04.08 10.5.4.5a: encode 'call control cap' */
+/*! \brief Encodoe TS 04.08 Call Control Capabilities (10.5.4.5a)
+ * \param[out] msg Message Buffer to which to append IE (as TLV)
+ * \param[in] ccap Decoded CC Capabilities to be encoded
+ * \returns 0 on success; negative on error */
int gsm48_encode_cccap(struct msgb *msg,
const struct gsm_mncc_cccap *ccap)
{
@@ -307,7 +333,10 @@
return 0;
}
-/* TS 04.08 10.5.4.7: decode 'called party BCD number' */
+/*! \brief Decode TS 04.08 Called Party BCD Number IE (10.5.4.7)
+ * \param[out] called Caller-provided memory for decoded number
+ * \param[in] lv Length-Value portion of IE
+ * \returns 0 on success; negative on error */
int gsm48_decode_called(struct gsm_mncc_number *called,
const uint8_t *lv)
{
@@ -326,7 +355,10 @@
return 0;
}
-/* TS 04.08 10.5.4.7: encode 'called party BCD number' */
+/*! \brief Encode TS 04.08 Called Party IE (10.5.4.7)
+ * \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ * \param[in] called MNCC Number to encode/append
+ * \returns 0 on success; negative on error */
int gsm48_encode_called(struct msgb *msg,
const struct gsm_mncc_number *called)
{
@@ -348,7 +380,10 @@
return 0;
}
-/* decode callerid of various IEs */
+/*! \brief Decode TS 04.08 Caller ID
+ * \param[out] called Caller-provided memory for decoded number
+ * \param[in] lv Length-Value portion of IE
+ * \returns 0 on success; negative on error */
int gsm48_decode_callerid(struct gsm_mncc_number *callerid,
const uint8_t *lv)
{
@@ -375,7 +410,12 @@
return 0;
}
-/* encode callerid of various IEs */
+/*! \brief Encode TS 04.08 Caller ID IE
+ * \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ * \param[in] ie IE Identifier (tag)
+ * \param[in] max_len maximum generated output in bytes
+ * \param[in] callerid MNCC Number to encode/append
+ * \returns 0 on success; negative on error */
int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len,
const struct gsm_mncc_number *callerid)
{
@@ -406,7 +446,10 @@
return 0;
}
-/* TS 04.08 10.5.4.11: decode 'cause' */
+/*! \brief Decode TS 04.08 Cause IE (10.5.4.11)
+ * \param[out] cause Caller-provided memory for output
+ * \param[in] lv LV portion of Cause IE
+ * \returns 0 on success; negative on error */
int gsm48_decode_cause(struct gsm_mncc_cause *cause,
const uint8_t *lv)
{
@@ -449,7 +492,11 @@
return 0;
}
-/* TS 04.08 10.5.4.11: encode 'cause' */
+/*! \brief Encode TS 04.08 Cause IE (10.5.4.11)
+ * \param[out] msg Message Buffer to which to append IE
+ * \param[in] lv_only Encode as LV (1) or TLV (0)
+ * \param[in] cause Cause value to be encoded
+ * \returns 0 on success; negative on error */
int gsm48_encode_cause(struct msgb *msg, int lv_only,
const struct gsm_mncc_cause *cause)
{
@@ -489,49 +536,49 @@
return 0;
}
-/* TS 04.08 10.5.4.9: decode 'calling number' */
+/*! \brief Decode TS 04.08 Calling Number IE (10.5.4.9) */
int gsm48_decode_calling(struct gsm_mncc_number *calling,
const uint8_t *lv)
{
return gsm48_decode_callerid(calling, lv);
}
-/* TS 04.08 10.5.4.9: encode 'calling number' */
+/*! \brief Encode TS 04.08 Calling Number IE (10.5.4.9) */
int gsm48_encode_calling(struct msgb *msg,
const struct gsm_mncc_number *calling)
{
return gsm48_encode_callerid(msg, GSM48_IE_CALLING_BCD, 14, calling);
}
-/* TS 04.08 10.5.4.13: decode 'connected number' */
+/*! \brief Decode TS 04.08 Connected Number IE (10.5.4.13) */
int gsm48_decode_connected(struct gsm_mncc_number *connected,
const uint8_t *lv)
{
return gsm48_decode_callerid(connected, lv);
}
-/* TS 04.08 10.5.4.13: encode 'connected number' */
+/*! \brief Encode TS 04.08 Connected Number IE (10.5.4.13) */
int gsm48_encode_connected(struct msgb *msg,
const struct gsm_mncc_number *connected)
{
return gsm48_encode_callerid(msg, GSM48_IE_CONN_BCD, 14, connected);
}
-/* TS 04.08 10.5.4.21b: decode 'redirecting number' */
+/*! \brief Decode TS 04.08 Redirecting Number IE (10.5.4.21b) */
int gsm48_decode_redirecting(struct gsm_mncc_number *redirecting,
const uint8_t *lv)
{
return gsm48_decode_callerid(redirecting, lv);
}
-/* TS 04.08 10.5.4.21b: encode 'redirecting number' */
+/*! \brief Encode TS 04.08 Redirecting Number IE (10.5.4.21b) */
int gsm48_encode_redirecting(struct msgb *msg,
const struct gsm_mncc_number *redirecting)
{
return gsm48_encode_callerid(msg, GSM48_IE_REDIR_BCD, 19, redirecting);
}
-/* TS 04.08 10.5.4.15: decode 'facility' */
+/*! \brief Decode TS 04.08 Facility IE (10.5.4.15) */
int gsm48_decode_facility(struct gsm_mncc_facility *facility,
const uint8_t *lv)
{
@@ -549,7 +596,7 @@
return 0;
}
-/* TS 04.08 10.5.4.15: encode 'facility' */
+/*! \brief Encode TS 04.08 Facility IE (10.5.4.15) */
int gsm48_encode_facility(struct msgb *msg, int lv_only,
const struct gsm_mncc_facility *facility)
{
@@ -568,7 +615,7 @@
return 0;
}
-/* TS 04.08 10.5.4.20: decode 'notify' */
+/*! \brief Decode TS 04.08 Notify IE (10.5.4.20) */
int gsm48_decode_notify(int *notify, const uint8_t *v)
{
*notify = v[0] & 0x7f;
@@ -576,7 +623,7 @@
return 0;
}
-/* TS 04.08 10.5.4.20: encode 'notify' */
+/*! \brief Encode TS 04.08 Notify IE (10.5.4.20) */
int gsm48_encode_notify(struct msgb *msg, int notify)
{
msgb_v_put(msg, notify | 0x80);
@@ -584,7 +631,7 @@
return 0;
}
-/* TS 04.08 10.5.4.23: decode 'signal' */
+/*! \brief Decode TS 04.08 Signal IE (10.5.4.23) */
int gsm48_decode_signal(int *signal, const uint8_t *v)
{
*signal = v[0];
@@ -592,7 +639,7 @@
return 0;
}
-/* TS 04.08 10.5.4.23: encode 'signal' */
+/*! \brief Encode TS 04.08 Signal IE (10.5.4.23) */
int gsm48_encode_signal(struct msgb *msg, int signal)
{
msgb_tv_put(msg, GSM48_IE_SIGNAL, signal);
@@ -600,7 +647,7 @@
return 0;
}
-/* TS 04.08 10.5.4.17: decode 'keypad' */
+/*! \brief Decode TS 04.08 Keypad IE (10.5.4.17) */
int gsm48_decode_keypad(int *keypad, const uint8_t *lv)
{
uint8_t in_len = lv[0];
@@ -613,7 +660,7 @@
return 0;
}
-/* TS 04.08 10.5.4.17: encode 'keypad' */
+/*! \brief Encode TS 04.08 Keypad IE (10.5.4.17) */
int gsm48_encode_keypad(struct msgb *msg, int keypad)
{
msgb_tv_put(msg, GSM48_IE_KPD_FACILITY, keypad);
@@ -621,7 +668,7 @@
return 0;
}
-/* TS 04.08 10.5.4.21: decode 'progress' */
+/*! \brief Decode TS 04.08 Progress IE (10.5.4.21) */
int gsm48_decode_progress(struct gsm_mncc_progress *progress,
const uint8_t *lv)
{
@@ -637,7 +684,7 @@
return 0;
}
-/* TS 04.08 10.5.4.21: encode 'progress' */
+/*! \brief Encode TS 04.08 Progress IE (10.5.4.21) */
int gsm48_encode_progress(struct msgb *msg, int lv_only,
const struct gsm_mncc_progress *p)
{
@@ -654,7 +701,7 @@
return 0;
}
-/* TS 04.08 10.5.4.25: decode 'user-user' */
+/*! \brief Decode TS 04.08 User-User IE (10.5.4.25) */
int gsm48_decode_useruser(struct gsm_mncc_useruser *uu,
const uint8_t *lv)
{
@@ -680,7 +727,7 @@
return 0;
}
-/* TS 04.08 10.5.4.25: encode 'useruser' */
+/*! \brief Encode TS 04.08 User-User IE (10.5.4.25) */
int gsm48_encode_useruser(struct msgb *msg, int lv_only,
const struct gsm_mncc_useruser *uu)
{
@@ -700,7 +747,7 @@
return 0;
}
-/* TS 04.08 10.5.4.24: decode 'ss version' */
+/*! \brief Decode TS 04.08 SS Version IE (10.5.4.24) */
int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv,
const uint8_t *lv)
{
@@ -715,7 +762,7 @@
return 0;
}
-/* TS 04.08 10.5.4.24: encode 'ss version' */
+/*! \brief Encode TS 04.08 SS Version IE (10.5.4.24) */
int gsm48_encode_ssversion(struct msgb *msg,
const struct gsm_mncc_ssversion *ssv)
{
@@ -733,7 +780,7 @@
/* decode 'more data' does not require a function, because it has no value */
-/* TS 04.08 10.5.4.19: encode 'more data' */
+/*! \brief Encode TS 04.08 More Data IE (10.5.4.19) */
int gsm48_encode_more(struct msgb *msg)
{
uint8_t *ie;
@@ -756,7 +803,11 @@
return res;
}
-/* decode "Cell Channel Description" (10.5.2.1b) and other frequency lists */
+/*! \brief Decode TS 04.08 Cell Channel Description IE (10.5.2.1b) and other frequency lists
+ * \param[out] f Caller-provided output memory
+ * \param[in] cd Cell Channel Description IE
+ * \param[in] len Length of \a cd in bytes
+ * \returns 0 on success; negative on error */
int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd,
uint8_t len, uint8_t mask, uint8_t frqt)
{
@@ -1190,3 +1241,4 @@
return 0;
}
+/*! @} */