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 )

inlinestatic

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 )

inlinestatic

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().