3GPP TS 23.032 GAD: Universal Geographical Area Description.

Files
file	gad.h
	Message encoding and decoding for 3GPP TS 23.032 GAD: Universal Geographical Area Description.
file	gsm_23_032.h
file	gad.c
	Message encoding and decoding for 3GPP TS 23.032 GAD: Universal Geographical Area Description.

Data Structures
struct	osmo_gad_ell_point
struct	osmo_gad_ell_point_unc_circle
struct	osmo_gad_ell_point_unc_ellipse
struct	osmo_gad_polygon
struct	osmo_gad_ell_point_alt
struct	osmo_gad_ell_point_alt_unc_ell
struct	osmo_gad_ell_arc
struct	osmo_gad_ha_ell_point_alt_unc_ell
struct	osmo_gad
struct	osmo_gad_err
struct	gad_raw_head
struct	gad_raw_ell_point
struct	gad_raw_ell_point_unc_circle
struct	gad_raw_ell_point_unc_ellipse
struct	gad_raw_polygon
struct	gad_raw_ell_point_alt
struct	gad_raw_ell_point_alt_unc_ell
struct	gad_raw_ell_arc
struct	gad_raw_ha_ell_point_unc_ell
struct	gad_raw_ha_ell_point_alt_unc_ell
union	gad_raw
	GAD PDU in network-byte-order according to 3GPP TS 23.032 GAD: Universal Geographical Area Description. More...

Macros
#define	DEC_ERR(RC, TYPE, fmt, args...)

Enumerations
enum	gad_type {   GAD_TYPE_ELL_POINT = 0 ,   GAD_TYPE_ELL_POINT_UNC_CIRCLE = 1 ,   GAD_TYPE_ELL_POINT_UNC_ELLIPSE = 3 ,   GAD_TYPE_POLYGON = 5 ,   GAD_TYPE_ELL_POINT_ALT = 8 ,   GAD_TYPE_ELL_POINT_ALT_UNC_ELL = 9 ,   GAD_TYPE_ELL_ARC = 10 ,   GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE = 11 ,   GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL = 12 }

Functions
static const char *	osmo_gad_type_name (enum gad_type val)
int	osmo_gad_raw_write (struct msgb *msg, const union gad_raw *gad_raw)
	Append a GAD PDU to the msgb. More...
int	osmo_gad_raw_read (union gad_raw *gad_raw, struct osmo_gad_err **err, void *err_ctx, const uint8_t *data, uint8_t len)
	Read a GAD PDU and validate structure. More...
int	osmo_gad_enc (union gad_raw *gad_raw, const struct osmo_gad *gad)
	Write GAD values with consistent units to raw GAD PDU representation. More...
int	osmo_gad_dec (struct osmo_gad *gad, struct osmo_gad_err **err, void *err_ctx, const union gad_raw *raw)
	Decode GAD raw PDU to values with consistent units. More...
int	osmo_gad_to_str_buf (char *buf, size_t buflen, const struct osmo_gad *gad)
	Return a human readable representation of GAD (location estimate) values. More...
char *	osmo_gad_to_str_c (void *ctx, const struct osmo_gad *gad)
	Return a human readable representation of GAD (location estimate) values. More...
uint32_t	osmo_gad_enc_lat (int32_t deg_1e6)
	Encode a latitude value according to 3GPP TS 23.032. More...
int32_t	osmo_gad_dec_lat (uint32_t lat)
	Decode a latitude value according to 3GPP TS 23.032. More...
uint32_t	osmo_gad_enc_lon (int32_t deg_1e6)
	Encode a longitude value according to 3GPP TS 23.032. More...
int32_t	osmo_gad_dec_lon (uint32_t lon)
	Decode a longitude value according to 3GPP TS 23.032. More...
uint8_t	osmo_gad_enc_unc (uint32_t mm)
	Encode an uncertainty circle value according to 3GPP TS 23.032. More...
uint32_t	osmo_gad_dec_unc (uint8_t unc)
	Decode an uncertainty circle value according to 3GPP TS 23.032. More...
struct gad_raw_head	__attribute__ ((packed))
static int	osmo_gad_enc_ell_point_unc_circle (struct gad_raw_ell_point_unc_circle *raw, const struct osmo_gad_ell_point_unc_circle *v)
static int	osmo_gad_dec_ell_point_unc_circle (struct osmo_gad_ell_point_unc_circle *v, struct osmo_gad_err **err, void *err_ctx, const struct gad_raw_ell_point_unc_circle *raw)
static int	osmo_gad_raw_len (const union gad_raw *gad_raw)
int	osmo_gad_raw_to_str_buf (char *buf, size_t buflen, const union gad_raw *raw)
	Return a human readable representation of a raw GAD PDU. More...
char *	osmo_gad_raw_to_str_c (void *ctx, const union gad_raw *raw)
	Return a human readable representation of a raw GAD PDU. More...

Variables
const struct value_string	osmo_gad_type_names []
const struct value_string	osmo_gad_type_names []
static uint32_t	table_uncertainty_1e3 [128]
enum gsmtap_um_voice_type	__attribute__

Detailed Description

Macro Definition Documentation

DEC_ERR

#define DEC_ERR	(		RC,
			TYPE,
			fmt,
			args...
	)

Value:

                do { \
                if (err) { \
                        *err = talloc_zero(err_ctx, struct osmo_gad_err); \
                        **err = (struct osmo_gad_err){ \
                                .rc = (RC), \
                                .type = (TYPE), \
                                .logmsg = talloc_asprintf(*err, "Error decoding GAD%s%s: " fmt, \
                                                          ((int)(TYPE)) >= 0 ? " " : "", \
                                                          ((int)(TYPE)) >= 0 ? osmo_gad_type_name(TYPE) : "", ##args), \
                        }; \
                } \
                return RC; \
        } while(0)

Enumeration Type Documentation

gad_type

enum gad_type

Enumerator
GAD_TYPE_ELL_POINT	Ellipsoid point.
GAD_TYPE_ELL_POINT_UNC_CIRCLE	Ellipsoid point with uncertainty circle.
GAD_TYPE_ELL_POINT_UNC_ELLIPSE	Ellipsoid point with uncertainty ellipse.
GAD_TYPE_POLYGON
GAD_TYPE_ELL_POINT_ALT	Ellipsoid point with altitude.
GAD_TYPE_ELL_POINT_ALT_UNC_ELL	Ellipsoid point with altitude and uncertainty ellipsoid.
GAD_TYPE_ELL_ARC	Ellipsoid arc.
GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE	High accuracy ellipsoid point with uncertainty ellipse.
GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL	High accuracy ellipsoid point with altitude and uncertainty ellipsoid.

Function Documentation

__attribute__()

struct gad_raw_head __attribute__

(

(packed)

)

osmo_gad_dec()

int osmo_gad_dec	(	struct osmo_gad *	gad,
		struct osmo_gad_err **	err,
		void *	err_ctx,
		const union gad_raw *	raw
	)

Decode GAD raw PDU to values with consistent units.

Parameters

[out]	gad	Decoded GAD values are written here.
[out]	err	Returned pointer to error info, dynamically allocated; NULL to not return any.
[in]	err_ctx	Talloc context to allocate err from, if required.
[in]	raw	Raw GAD data in network-byte-order.

Returns

0 on success, negative on error. If returning negative and err was non-NULL, *err is guaranteed to point to an allocated struct osmo_gad_err.

References DEC_ERR, osmo_gad::ell_point_unc_circle, gad_raw::ell_point_unc_circle, ENOTSUP, GAD_TYPE_ELL_POINT_UNC_CIRCLE, gad_raw::h, osmo_gad_dec_ell_point_unc_circle(), and osmo_gad::type.

Referenced by osmo_gad_raw_to_str_buf().

osmo_gad_dec_ell_point_unc_circle()

static int osmo_gad_dec_ell_point_unc_circle ( struct osmo_gad_ell_point_unc_circle *  v, struct osmo_gad_err **  err, void *  err_ctx, const struct gad_raw_ell_point_unc_circle *  raw  )

static

References DEC_ERR, osmo_gad_ell_point_unc_circle::lat, osmo_gad_ell_point_unc_circle::lon, osmo_gad_dec_lat(), osmo_gad_dec_lon(), osmo_gad_dec_unc(), and osmo_gad_ell_point_unc_circle::unc.

Referenced by osmo_gad_dec().

osmo_gad_dec_lat()

int32_t osmo_gad_dec_lat

(

uint32_t

lat

)

Decode a latitude value according to 3GPP TS 23.032.

Useful to clamp a latitude to an actually encodable accuracy: set_lat = osmo_gad_dec_lat(osmo_gad_enc_lat(orig_lat));

Parameters

[in]

lat

encoded latitude in host-byte-order (24bit).

Returns

decoded latitude in micro degrees (degrees * 1e6), -90'000'000 (S) .. 90'000'000 (N).

References lat, and x.

Referenced by osmo_gad_dec_ell_point_unc_circle().

osmo_gad_dec_lon()

int32_t osmo_gad_dec_lon

(

uint32_t

lon

)

Decode a longitude value according to 3GPP TS 23.032.

Normally, encoding and decoding is done via osmo_gad_enc() and osmo_gad_dec() for entire PDUs. But calling this directly can be useful to clamp a longitude to an actually encodable accuracy: int32_t set_lon = osmo_gad_dec_lon(osmo_gad_enc_lon(orig_lon));

Parameters

[in]

lon

Encoded longitude.

Returns

Longitude in micro degrees (degrees * 1e6), -180'000'000 (W) .. 180'000'000 (E).

References lon, and x.

Referenced by osmo_gad_dec_ell_point_unc_circle().

osmo_gad_dec_unc()

uint32_t osmo_gad_dec_unc

(

uint8_t

unc

)

Decode an uncertainty circle value according to 3GPP TS 23.032.

Useful to clamp a value to an actually encodable accuracy: set_unc = osmo_gad_dec_unc(osmo_gad_enc_unc(orig_unc));

Parameters

[in]

unc

Encoded uncertainty value.

Returns

Uncertainty value in millimeters.

References table_uncertainty_1e3.

Referenced by osmo_gad_dec_ell_point_unc_circle().

osmo_gad_enc()

int osmo_gad_enc	(	union gad_raw *	gad_raw,
		const struct osmo_gad *	gad
	)

Write GAD values with consistent units to raw GAD PDU representation.

Parameters

[out]	gad_raw	Write to this buffer.
[in]	gad	GAD values to encode.

Returns

number of bytes written, or negative on failure.

References osmo_gad::ell_point_unc_circle, gad_raw::ell_point_unc_circle, ENOTSUP, GAD_TYPE_ELL_POINT_UNC_CIRCLE, osmo_gad_enc_ell_point_unc_circle(), and osmo_gad::type.

osmo_gad_enc_ell_point_unc_circle()

static int osmo_gad_enc_ell_point_unc_circle ( struct gad_raw_ell_point_unc_circle *  raw, const struct osmo_gad_ell_point_unc_circle *  v  )

static

References GAD_TYPE_ELL_POINT_UNC_CIRCLE, osmo_gad_ell_point_unc_circle::lat, osmo_gad_ell_point_unc_circle::lon, osmo_gad_enc_lat(), osmo_gad_enc_lon(), osmo_gad_enc_unc(), and osmo_gad_ell_point_unc_circle::unc.

Referenced by osmo_gad_enc().

osmo_gad_enc_lat()

uint32_t osmo_gad_enc_lat

(

int32_t

deg_1e6

)

Encode a latitude value according to 3GPP TS 23.032.

Useful to clamp a latitude to an actually encodable accuracy: set_lat = osmo_gad_dec_lat(osmo_gad_enc_lat(orig_lat));

Parameters

[in]

deg_1e6

Latitude in micro degrees (degrees * 1e6), -90'000'000 (S) .. 90'000'000 (N).

Returns

encoded latitude in host-byte-order (24bit).

References OSMO_MAX, OSMO_MIN, and x.

Referenced by osmo_gad_enc_ell_point_unc_circle().

osmo_gad_enc_lon()

uint32_t osmo_gad_enc_lon

(

int32_t

deg_1e6

)

Encode a longitude value according to 3GPP TS 23.032.

Useful to clamp a longitude to an actually encodable accuracy: set_lon = osmo_gad_dec_lon(osmo_gad_enc_lon(orig_lon));

Parameters

[in]

deg_1e6

Longitude in micro degrees (degrees * 1e6), -180'000'000 (W) .. 180'000'000 (E).

Returns

encoded longitude in host-byte-order (24bit).

References OSMO_MAX, OSMO_MIN, and x.

Referenced by osmo_gad_enc_ell_point_unc_circle().

osmo_gad_enc_unc()

uint8_t osmo_gad_enc_unc

(

uint32_t

mm

)

Encode an uncertainty circle value according to 3GPP TS 23.032.

Normally, encoding and decoding is done via osmo_gad_enc() and osmo_gad_dec() for entire PDUs. But calling this directly can be useful to clamp a value to an actually encodable accuracy: uint32_t set_unc = osmo_gad_dec_unc(osmo_gad_enc_unc(orig_unc));

Parameters

[in]

mm

Uncertainty value in millimeters.

Returns

Encoded uncertainty value.

References ARRAY_SIZE, and table_uncertainty_1e3.

Referenced by osmo_gad_enc_ell_point_unc_circle().

osmo_gad_raw_len()

static int osmo_gad_raw_len ( const union gad_raw *  gad_raw )

static

References gad_raw::ell_arc, gad_raw::ell_point, gad_raw::ell_point_alt, gad_raw::ell_point_alt_unc_ell, gad_raw::ell_point_unc_circle, gad_raw::ell_point_unc_ellipse, ENOTSUP, GAD_TYPE_ELL_ARC, GAD_TYPE_ELL_POINT, GAD_TYPE_ELL_POINT_ALT, GAD_TYPE_ELL_POINT_ALT_UNC_ELL, GAD_TYPE_ELL_POINT_UNC_CIRCLE, GAD_TYPE_ELL_POINT_UNC_ELLIPSE, GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL, GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE, GAD_TYPE_POLYGON, gad_raw_polygon::h, gad_raw::h, gad_raw::ha_ell_point_alt_unc_ell, gad_raw::ha_ell_point_unc_ell, gad_raw_polygon::point, and gad_raw::polygon.

Referenced by osmo_gad_raw_read(), and osmo_gad_raw_write().

osmo_gad_raw_read()

int osmo_gad_raw_read	(	union gad_raw *	gad_raw,
		struct osmo_gad_err **	err,
		void *	err_ctx,
		const uint8_t *	data,
		uint8_t	len
	)

Read a GAD PDU and validate structure.

Memcpy from data to gad_raw struct, and validate correct length depending on the GAD type and possibly on variable length attributes.

Parameters

[out]	gad_raw	Copy GAD PDU here.
[out]	err	Returned pointer to error info, dynamically allocated; NULL to not return any.
[in]	err_ctx	Talloc context to allocate err from, if required.
[in]	data	Encoded GAD bytes buffer.
[in]	len	Length of data in bytes.

Returns

0 on success, negative on error. If returning negative and err was non-NULL, *err is guaranteed to point to an allocated struct osmo_gad_err.

References data, DEC_ERR, gad_raw::h, len, and osmo_gad_raw_len().

Referenced by osmo_bssmap_le_ie_dec_gad().

osmo_gad_raw_to_str_buf()

int osmo_gad_raw_to_str_buf	(	char *	buf,
		size_t	buflen,
		const union gad_raw *	raw
	)

Return a human readable representation of a raw GAD PDU.

Convert to GAD values and feed the result to osmo_gad_to_str_buf().

Parameters

[out]	buf	Buffer to write string to.
[in]	buflen	sizeof(buf).
[in]	gad	Location data.

Returns

number of chars that would be written, like snprintf().

References osmo_strbuf::buf, osmo_strbuf::chars_needed, osmo_gad_dec(), osmo_gad_to_str_buf(), and OSMO_STRBUF_PRINTF.

Referenced by osmo_gad_raw_to_str_c().

osmo_gad_raw_to_str_c()

char * osmo_gad_raw_to_str_c	(	void *	ctx,
		const union gad_raw *	raw
	)

Return a human readable representation of a raw GAD PDU.

Convert to GAD values and feed the result to osmo_gad_to_str_buf().

Parameters

[in]	ctx	Talloc ctx to allocate string buffer from.
[in]	raw	GAD data in network-byte-order.

Returns

resulting string, dynamically allocated.

References osmo_gad_raw_to_str_buf(), and OSMO_NAME_C_IMPL.

osmo_gad_raw_write()

int osmo_gad_raw_write	(	struct msgb *	msg,
		const union gad_raw *	gad_raw
	)

Append a GAD PDU to the msgb.

Write the correct number of bytes depending on the GAD type and possibly on variable length attributes.

Parameters

[out]	msg	Append to this msgb.
[in]	gad_raw	GAD data to write.

Returns

number of bytes appended to msgb, or negative on failure.

References len, msg, msgb_put(), and osmo_gad_raw_len().

Referenced by gsm0808_create_perform_location_response(), and osmo_bssmap_le_enc_perform_loc_resp().

osmo_gad_to_str_buf()

int osmo_gad_to_str_buf	(	char *	buf,
		size_t	buflen,
		const struct osmo_gad *	gad
	)

Return a human readable representation of GAD (location estimate) values.

Parameters

[out]	buf	Buffer to write string to.
[in]	buflen	sizeof(buf).
[in]	gad	Location data.

Returns

number of chars that would be written, like snprintf().

References osmo_strbuf::buf, osmo_strbuf::chars_needed, osmo_gad::ell_point, osmo_gad::ell_point_unc_circle, GAD_TYPE_ELL_POINT, GAD_TYPE_ELL_POINT_UNC_CIRCLE, osmo_gad_ell_point::lat, osmo_gad_ell_point_unc_circle::lat, osmo_gad_ell_point::lon, osmo_gad_ell_point_unc_circle::lon, osmo_gad_type_name(), osmo_int_to_float_str_buf(), OSMO_STRBUF_APPEND, OSMO_STRBUF_PRINTF, osmo_gad::type, and osmo_gad_ell_point_unc_circle::unc.

Referenced by osmo_gad_raw_to_str_buf(), and osmo_gad_to_str_c().

osmo_gad_to_str_c()

char * osmo_gad_to_str_c	(	void *	ctx,
		const struct osmo_gad *	gad
	)

Return a human readable representation of GAD (location estimate) values.

Parameters

[in]	ctx	Talloc ctx to allocate string buffer from.
[in]	val	Value to convert to float.

Returns

resulting string, dynamically allocated.

References osmo_gad_to_str_buf(), and OSMO_NAME_C_IMPL.

osmo_gad_type_name()

static const char * osmo_gad_type_name ( enum gad_type  val )

inlinestatic

References get_value_string(), and osmo_gad_type_names.

Referenced by osmo_gad_to_str_buf().

Variable Documentation

osmo_gad_type_names [1/2]

const struct value_string osmo_gad_type_names[]

extern

Referenced by osmo_gad_type_name().

osmo_gad_type_names [2/2]

const struct value_string osmo_gad_type_names[]

Initial value:

= {
        { GAD_TYPE_ELL_POINT, "Ellipsoid-point" },
        { GAD_TYPE_ELL_POINT_UNC_CIRCLE, "Ellipsoid-point-with-uncertainty-circle" },
        { GAD_TYPE_ELL_POINT_UNC_ELLIPSE, "Ellipsoid-point-with-uncertainty-ellipse" },
        { GAD_TYPE_POLYGON, "Polygon" },
        { GAD_TYPE_ELL_POINT_ALT, "Ellipsoid-point-with-altitude" },
        { GAD_TYPE_ELL_POINT_ALT_UNC_ELL, "Ellipsoid-point-with-altitude-and-uncertainty-ellipsoid" },
        { GAD_TYPE_ELL_ARC, "Ellipsoid-arc" },
        { GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE, "High-accuracy-ellipsoid-point-with-uncertainty-ellipse" },
        { GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL, "High-accuracy-ellipsoid-point-with-altitude-and-uncertainty-ellipsoid" },
        {}
}

Referenced by osmo_gad_type_name().

table_uncertainty_1e3

uint32_t table_uncertainty_1e3[128]

static

Initial value:

= {
        0, 1000, 2100, 3310, 4641, 6105, 7715, 9487, 11435, 13579, 15937, 18531, 21384, 24522, 27974, 31772, 35949,
        40544, 45599, 51159, 57274, 64002, 71402, 79543, 88497, 98347, 109181, 121099, 134209, 148630, 164494, 181943,
        201137, 222251, 245476, 271024, 299126, 330039, 364043, 401447, 442592, 487851, 537636, 592400, 652640, 718904,
        791795, 871974, 960172, 1057189, 1163908, 1281299, 1410429, 1552472, 1708719, 1880591, 2069650, 2277615,
        2506377, 2758014, 3034816, 3339298, 3674227, 4042650, 4447915, 4893707, 5384077, 5923485, 6516834, 7169517,
        7887469, 8677216, 9545938, 10501531, 11552685, 12708953, 13980849, 15379933, 16918927, 18611820, 20474002,
        22522402, 24775642, 27254206, 29980627, 32979690, 36278659, 39907525, 43899277, 48290205, 53120226, 58433248,
        64277573, 70706330, 77777964, 85556760, 94113436, 103525780, 113879358, 125268293, 137796123, 151576735,
        166735409, 183409950, 201751945, 221928139, 244121953, 268535149, 295389664, 324929630, 357423593, 393166952,
        432484648, 475734112, 523308524, 575640376, 633205414, 696526955, 766180651, 842799716, 927080688, 1019789756,
        1121769732, 1233947705, 1357343476, 1493078824, 1642387706, 1806627477,
}

Referenced by osmo_gad_dec_unc(), and osmo_gad_enc_unc().