diff options
author | Harald Welte <laforge@gnumonks.org> | 2017-06-12 21:44:18 +0200 |
---|---|---|
committer | Harald Welte <laforge@gnumonks.org> | 2017-06-12 21:55:54 +0000 |
commit | 96e2a00d7a9044d0b1a83909c11d8f24955bc7c8 (patch) | |
tree | 4bbe6cb49a766df4cdefa9fffd56bb953d51da75 /src/gsm/gsm48_ie.c | |
parent | 7165880ac279a9d2d7403749f171eb9c60e70657 (diff) |
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
Diffstat (limited to 'src/gsm/gsm48_ie.c')
-rw-r--r-- | src/gsm/gsm48_ie.c | 122 |
1 files changed, 87 insertions, 35 deletions
diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c index 2cc0645d..20d0075d 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 @@ int gsm48_decode_bcd_number(char *output, int output_len, 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 @@ static int asc_to_bcd(const char asc) 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 @@ int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len, 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 @@ int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap, 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 @@ int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only, 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 @@ int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv) 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 @@ int gsm48_encode_cccap(struct msgb *msg, 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 @@ int gsm48_decode_called(struct gsm_mncc_number *called, 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 @@ int gsm48_encode_called(struct msgb *msg, 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 @@ int gsm48_decode_callerid(struct gsm_mncc_number *callerid, 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 @@ int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len, 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 @@ int gsm48_decode_cause(struct gsm_mncc_cause *cause, 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 @@ int gsm48_encode_cause(struct msgb *msg, int lv_only, 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 @@ int gsm48_decode_facility(struct gsm_mncc_facility *facility, 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 @@ int gsm48_encode_facility(struct msgb *msg, int lv_only, 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 @@ int gsm48_decode_notify(int *notify, const uint8_t *v) 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 @@ int gsm48_encode_notify(struct msgb *msg, int notify) 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 @@ int gsm48_decode_signal(int *signal, const uint8_t *v) 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 @@ int gsm48_encode_signal(struct msgb *msg, int signal) 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 @@ int gsm48_decode_keypad(int *keypad, const uint8_t *lv) 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 @@ int gsm48_encode_keypad(struct msgb *msg, int keypad) 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 @@ int gsm48_decode_progress(struct gsm_mncc_progress *progress, 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 @@ int gsm48_encode_progress(struct msgb *msg, int lv_only, 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 @@ int gsm48_decode_useruser(struct gsm_mncc_useruser *uu, 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 @@ int gsm48_encode_useruser(struct msgb *msg, int lv_only, 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 @@ int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv, 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 @@ int gsm48_encode_ssversion(struct msgb *msg, /* 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 @@ static int32_t smod(int32_t n, int32_t m) 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 @@ int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd, return 0; } +/*! @} */ |