libosmogsm 1.13.1.1-afb4 Osmocom GSM library

Data Structures | Macros | Functions | Variables
gsm0480.h File Reference
`#include <osmocom/core/defs.h>`
`#include <osmocom/core/msgb.h>`
`#include <osmocom/gsm/protocol/gsm_04_08.h>`
`#include <osmocom/gsm/protocol/gsm_04_80.h>`

Go to the source code of this file.

## Data Structures
struct | ussd_request
struct | ss_request
| This structure represents some meaningful parts of a decoded and/or to be encoded GSM 04.80 message. More...

## Macros
#define | GSM0480_USSD_OCTET_STRING_LEN 160
| According to the GSM 04.80 (version 5.0.0) specification Annex A "Expanded ASN.1 Module "SS-Protocol", the maximum size of a USSD OCTET STRING field is 160 bytes. More...
#define | GSM0480_USSD_7BIT_STRING_LEN 182
| Thus according to ETSI TS 123 038 (version 10.0.0) specification 6.1.2.3 "USSD packing of 7 bit characters", in 160 octets, it's possible to pack (160 * 8) / 7 = 182.8, that is 182 characters. More...
#define | MAX_LEN_USSD_STRING 31
| DEPRECATED: this definition doesn't follow any specification, so we only keep it for compatibility reasons. More...

## Functions
static const char * | gsm0480_comp_type_name (uint8_t comp_type)
static const char * | gsm0480_op_code_name (uint8_t op_code)
int | gsm0480_decode_ussd_request (const struct gsm48_hdr *hdr, uint16_t len, struct ussd_request *request) OSMO_DEPRECATED("Use gsm0480_decode_ss_request() instead")
int | gsm0480_extract_ie_by_tag (const struct gsm48_hdr *hdr, uint16_t msg_len, uint8_t **ie, uint16_t *ie_len, uint8_t ie_tag)
| Get pointer to the IE of a given type. More...
int | gsm0480_parse_facility_ie (const uint8_t *facility_ie, uint16_t length, struct ss_request *req)
| Parse the components of a given Facility IE. More...
int | gsm0480_decode_ss_request (const struct gsm48_hdr *hdr, uint16_t len, struct ss_request *request)
struct msgb * | gsm0480_msgb_alloc_name (const char *name)
struct msgb * | gsm0480_gen_ussd_resp_7bit (uint8_t invoke_id, const char *text)
| Generate a USSD ReturnResult component containing a string in default GSM alphabet. More...
struct msgb * | gsm0480_gen_return_error (uint8_t invoke_id, uint8_t error_code)
| Generate a ReturnError component (see section 3.6.1) and given error code (see section 3.6.6). More...
struct msgb * | gsm0480_gen_reject (int invoke_id, uint8_t problem_tag, uint8_t problem_code)
| Generate a Reject component (see section 3.6.1) and given error code (see section 3.6.7). More...
struct msgb * | gsm0480_create_ussd_resp (uint8_t invoke_id, uint8_t trans_id, const char *text)
| Legacy helper: Generate USSD response including FACILITY IE + L3 header. More...
struct msgb * | gsm0480_create_unstructuredSS_Notify (int alertPattern, const char *text)
struct msgb * | gsm0480_create_notifySS (const char *text)
struct msgb * | gsm0480_create_ussd_notify (int level, const char *text)
struct msgb * | gsm0480_create_ussd_release_complete (void) OSMO_DEPRECATED("Use gsm0480_create_release_complete() instead.")
| Deprecated, use gsm0480_create_release_complete() instead. More...
struct msgb * | gsm0480_create_release_complete (uint8_t trans_id)
| Create a GSM 04.80 Release complete (see 2.5) message, prefixed by GSM 04.08 L3 header with a given transaction ID. More...
int | gsm0480_wrap_invoke (struct msgb *msg, int op, int link_id)
int | gsm0480_wrap_facility (struct msgb *msg)

## Variables
const struct value_string | gsm0480_comp_type_names []
const struct value_string | gsm0480_op_code_names []

## Macro Definition Documentation

## ◆ GSM0480_USSD_7BIT_STRING_LEN

#define GSM0480_USSD_7BIT_STRING_LEN 182

Thus according to ETSI TS 123 038 (version 10.0.0) specification 6.1.2.3 "USSD packing of 7 bit characters", in 160 octets, it's possible to pack (160 * 8) / 7 = 182.8, that is 182 characters.

The remaining 6 bits are set to zero.

## ◆ GSM0480_USSD_OCTET_STRING_LEN

#define GSM0480_USSD_OCTET_STRING_LEN 160

According to the GSM 04.80 (version 5.0.0) specification Annex A "Expanded ASN.1 Module "SS-Protocol", the maximum size of a USSD OCTET STRING field is 160 bytes.

## ◆ MAX_LEN_USSD_STRING

#define MAX_LEN_USSD_STRING 31

DEPRECATED: this definition doesn't follow any specification, so we only keep it for compatibility reasons.

It's strongly recommended to use correct definitions above.

## Function Documentation

## ◆ gsm0480_comp_type_name()

static const char * gsm0480_comp_type_name | ( | uint8_t | comp_type | ) |
| inline static

References get_value_string(), and gsm0480_comp_type_names.

## ◆ gsm0480_create_notifySS()

struct msgb * gsm0480_create_notifySS | ( | const char * | text | ) |

References data, gsm0480_msgb_alloc_name(), GSM_0480_SEQUENCE_TAG, gsm_7bit_encode_n_ussd(), len, msg, msgb_put(), msgb_put_u8(), and msgb_tailroom().

## ◆ gsm0480_create_release_complete()

struct msgb * gsm0480_create_release_complete | ( | uint8_t | trans_id | ) |

Create a GSM 04.80 Release complete (see 2.5) message, prefixed by GSM 04.08 L3 header with a given transaction ID.

Parameters

  [in] | trans_id | GSM 04.07 transaction identifier (and TI flag)

Returns
  message buffer containing the Release complete message

References gsm0480_msgb_alloc_name(), GSM0480_MTYPE_RELEASE_COMPLETE, GSM48_PDISC_NC_SS, gsm48_push_l3hdr_tid, and msg.

## ◆ gsm0480_create_unstructuredSS_Notify()

struct msgb * gsm0480_create_unstructuredSS_Notify | ( | int | alertPattern,
|  | const char * | text
| ) |  |

References ASN1_OCTET_STRING_TAG, data, gsm0480_msgb_alloc_name(), GSM_0480_SEQUENCE_TAG, gsm_7bit_encode_n_ussd(), len, msg, msgb_put(), msgb_put_u8(), and msgb_tailroom().

Referenced by gsm0480_create_ussd_notify().

## ◆ gsm0480_create_ussd_notify()

struct msgb * gsm0480_create_ussd_notify | ( | int | level,
|  | const char * | text
| ) |  |

References gsm0480_create_unstructuredSS_Notify(), GSM0480_MTYPE_REGISTER, GSM0480_OP_CODE_USS_NOTIFY, gsm0480_wrap_facility(), gsm0480_wrap_invoke(), GSM48_PDISC_NC_SS, gsm48_push_l3hdr(), level, and msg.

## ◆ gsm0480_create_ussd_release_complete()

struct msgb * gsm0480_create_ussd_release_complete | ( | void |  | ) |

Deprecated, use gsm0480_create_release_complete() instead.

References gsm0480_msgb_alloc_name(), GSM0480_MTYPE_RELEASE_COMPLETE, GSM48_PDISC_NC_SS, gsm48_push_l3hdr(), and msg.

## ◆ gsm0480_create_ussd_resp()

struct msgb * gsm0480_create_ussd_resp | ( | uint8_t | invoke_id,
|  | uint8_t | trans_id,
|  | const char * | text
| ) |  |

Legacy helper: Generate USSD response including FACILITY IE + L3 header.

This function is just like gsm0480_gen_ussd_resp_7bit, but it generates not only the FACILITY value, but the full L3 message including message header and FACILITY IE Tag+Length.

References gsm0480_gen_ussd_resp_7bit(), GSM0480_IE_FACILITY, GSM0480_MTYPE_RELEASE_COMPLETE, GSM48_PDISC_NC_SS, gsm48_push_l3hdr_tid, msg, and msgb_push_tl().

## ◆ gsm0480_decode_ss_request()

int gsm0480_decode_ss_request | ( | const struct gsm48_hdr * | hdr,
|  | uint16_t | len,
|  | struct ss_request * | request
| ) |  |

Check Protocol Discriminator see TS GSM 04.07 and GSM 04.80

References DLGLOBAL, gsm48_hdr_pdisc(), GSM48_PDISC_NC_SS, hdr, len, LOGL_ERROR, LOGP, parse_ss(), gsm48_hdr::proto_discr, and ss_request::transaction_id.

## ◆ gsm0480_decode_ussd_request()

int gsm0480_decode_ussd_request | ( | const struct gsm48_hdr * | hdr,
|  | uint16_t | len,
|  | struct ussd_request * | request
| ) |  |

References DLGLOBAL, gsm48_hdr_pdisc(), GSM48_PDISC_NC_SS, hdr, ussd_request::invoke_id, ss_request::invoke_id, len, LOGL_ERROR, LOGP, parse_ss(), gsm48_hdr::proto_discr, ussd_request::text, ussd_request::transaction_id, ss_request::transaction_id, and ss_request::ussd_text.

## ◆ gsm0480_extract_ie_by_tag()

int gsm0480_extract_ie_by_tag | ( | const struct gsm48_hdr * | hdr,
|  | uint16_t | msg_len,
|  | uint8_t ** | ie,
|  | uint16_t * | ie_len,
|  | uint8_t | ie_tag
| ) |  |

Get pointer to the IE of a given type.

Parameters

  [in] | hdr | Pointer to the message starting from header
  [in] | msg_len | Length of the whole message + header
  [out] | ie | External pointer to be set
  [out] | ie_len | External IE length variable
  [in] | ie_tag | Tag value of the required IE

Returns
  0 in case of success, otherwise -ERRNO

This function iterates over existing IEs within a given message (depending on its type), and looks for the one with given ie_tag value. If the IE is found, the external pointer pointed by ie will be set to its value part (omitting TL), and ie_len will be set to the length. Otherwise, e.g. in case of parsing error, both ie and ie_len are set to NULL and 0 respectively.

References gsm48_hdr::data, GSM0480_IE_FACILITY, GSM0480_MTYPE_FACILITY, GSM0480_MTYPE_REGISTER, GSM0480_MTYPE_RELEASE_COMPLETE, gsm48_hdr_msg_type, gsm48_hdr_pdisc(), GSM48_PDISC_NC_SS, hdr, len, and msg_type.

## ◆ gsm0480_gen_reject()

struct msgb * gsm0480_gen_reject | ( | int | invoke_id,
|  | uint8_t | problem_tag,
|  | uint8_t | problem_code
| ) |  |

Generate a Reject component (see section 3.6.1) and given error code (see section 3.6.7).

Parameters

  [in] | invoke_id | InvokeID of the request
  [in] | problem_tag | Problem code tag (table 3.13)
  [in] | problem_code | Problem code (table 3.14-3.17)

Returns
  message buffer containing the Reject component

Note: if InvokeID is not available, e.g. when message parsing failed, any incorrect vlue can be passed (0x00 > x > 0xff), so the universal NULL-tag (see table 3.6) will be used instead.

References ASN1_NULL_TYPE_TAG, GSM0480_COMPIDTAG_INVOKE_ID, GSM0480_CTYPE_REJECT, gsm0480_msgb_alloc_name(), msg, msgb_push_tl(), msgb_tlv1_push(), and msgb_tv_push().

## ◆ gsm0480_gen_return_error()

struct msgb * gsm0480_gen_return_error | ( | uint8_t | invoke_id,
|  | uint8_t | error_code
| ) |  |

Generate a ReturnError component (see section 3.6.1) and given error code (see section 3.6.6).

Parameters

  [in] | invoke_id | InvokeID of the request
  [in] | error_code | Error code (section 4.5)

Returns
  message buffer containing the Reject component

References GSM0480_COMPIDTAG_INVOKE_ID, GSM0480_CTYPE_RETURN_ERROR, gsm0480_msgb_alloc_name(), GSM_0480_ERROR_CODE_TAG, msg, msgb_push_tl(), and msgb_tlv1_push().

## ◆ gsm0480_gen_ussd_resp_7bit()

struct msgb * gsm0480_gen_ussd_resp_7bit | ( | uint8_t | invoke_id,
|  | const char * | text
| ) |  |

Generate a USSD ReturnResult component containing a string in default GSM alphabet.

Parameters

  [in] | invoke_id | InvokeID of the request to which we respond
  [in] | text | USSD text in ASCII; to be encoded as GSM 7-but alphabet

References ASN1_OCTET_STRING_TAG, GSM0480_COMPIDTAG_INVOKE_ID, GSM0480_CTYPE_RETURN_RESULT, gsm0480_msgb_alloc_name(), GSM0480_OP_CODE_PROCESS_USS_REQ, GSM0480_OPERATION_CODE, GSM_0480_SEQUENCE_TAG, gsm_7bit_encode_n_ussd(), msg, msgb_push_tl(), msgb_put(), msgb_tailroom(), and msgb_tlv1_push().

Referenced by gsm0480_create_ussd_resp().

## ◆ gsm0480_msgb_alloc_name()

struct msgb * gsm0480_msgb_alloc_name | ( | const char * | name | ) |

References msgb_alloc_headroom(), and name.

Referenced by gsm0480_create_notifySS(), gsm0480_create_release_complete(), gsm0480_create_unstructuredSS_Notify(), gsm0480_create_ussd_release_complete(), gsm0480_gen_reject(), gsm0480_gen_return_error(), and gsm0480_gen_ussd_resp_7bit().

## ◆ gsm0480_op_code_name()

static const char * gsm0480_op_code_name | ( | uint8_t | op_code | ) |
| inline static

References get_value_string(), and gsm0480_op_code_names.

## ◆ gsm0480_parse_facility_ie()

int gsm0480_parse_facility_ie | ( | const uint8_t * | facility_ie,
|  | uint16_t | length,
|  | struct ss_request * | req
| ) |  |

Parse the components of a given Facility IE.

Parameters

  [in] | facility_ie | The Facility IE
  [in] | length | The length of Facility IE
  [out] | req | Abstract representation of SS message

Returns
  0 in case of success, otherwise -ERRNO

The internal functions are using inverted return codes, where '0' means error/failure. While a common approach is to return negative errno in case of any failure, and '0' if all is ok.

References DLGLOBAL, GSM0480_CTYPE_INVOKE, GSM0480_CTYPE_REJECT, GSM0480_CTYPE_RETURN_ERROR, GSM0480_CTYPE_RETURN_RESULT, length, LOGL_ERROR, LOGP, parse_ss_invoke(), and parse_ss_return_result().

Referenced by parse_ss_facility(), and parse_ss_info_elements().

## ◆ gsm0480_wrap_facility()

int gsm0480_wrap_facility | ( | struct msgb * | msg | ) |

References GSM0480_IE_FACILITY, msg, and msgb_push_tl().

Referenced by gsm0480_create_ussd_notify().

## ◆ gsm0480_wrap_invoke()

int gsm0480_wrap_invoke | ( | struct msgb * | msg,
|  | int | op,
|  | int | link_id
| ) |  |

References GSM0480_COMPIDTAG_INVOKE_ID, GSM0480_CTYPE_INVOKE, GSM0480_OPERATION_CODE, link_id, msg, msgb_push_tl(), and msgb_tlv1_push().

Referenced by gsm0480_create_ussd_notify().

## Variable Documentation

## ◆ gsm0480_comp_type_names

const struct value_string gsm0480_comp_type_names[]
| extern

Referenced by gsm0480_comp_type_name().

## ◆ gsm0480_op_code_names

const struct value_string gsm0480_op_code_names[]
| extern

Referenced by gsm0480_op_code_name().