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)
osmo_gad_type_name
static const char * osmo_gad_type_name(enum gad_type val)
Definition: gad.h:172
osmo_gad_err
Definition: gad.h:165
osmo_gad_err::type
enum gad_type type
Definition: gad.h:167

## 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.

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.

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, and OSMO_MIN.

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, and OSMO_MIN.

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::h, gad_raw_polygon::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 __attribute__().

## 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 | ) |

inline static

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" },
{}
}
GAD_TYPE_POLYGON
@ GAD_TYPE_POLYGON
Definition: gsm_23_032.h:39
GAD_TYPE_ELL_POINT_ALT
@ GAD_TYPE_ELL_POINT_ALT
Ellipsoid point with altitude.
Definition: gsm_23_032.h:41
GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE
@ GAD_TYPE_HA_ELL_POINT_UNC_ELLIPSE
High accuracy ellipsoid point with uncertainty ellipse.
Definition: gsm_23_032.h:47
GAD_TYPE_ELL_POINT
@ GAD_TYPE_ELL_POINT
Ellipsoid point.
Definition: gsm_23_032.h:34
GAD_TYPE_ELL_POINT_ALT_UNC_ELL
@ GAD_TYPE_ELL_POINT_ALT_UNC_ELL
Ellipsoid point with altitude and uncertainty ellipsoid.
Definition: gsm_23_032.h:43
GAD_TYPE_ELL_POINT_UNC_CIRCLE
@ GAD_TYPE_ELL_POINT_UNC_CIRCLE
Ellipsoid point with uncertainty circle.
Definition: gsm_23_032.h:36
GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL
@ GAD_TYPE_HA_ELL_POINT_ALT_UNC_ELL
High accuracy ellipsoid point with altitude and uncertainty ellipsoid.
Definition: gsm_23_032.h:49
GAD_TYPE_ELL_POINT_UNC_ELLIPSE
@ GAD_TYPE_ELL_POINT_UNC_ELLIPSE
Ellipsoid point with uncertainty ellipse.
Definition: gsm_23_032.h:38
GAD_TYPE_ELL_ARC
@ GAD_TYPE_ELL_ARC
Ellipsoid arc.
Definition: gsm_23_032.h:45

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