AT parameters

The AT parameters module provides functionality to store lists of AT command or respond parameters. These lists can be used by other modules to write and read parameter values.

Tip

The primary intention of this module is to be used for AT command or respond parameters, but this is no requirement. You can use this module to store other kinds of parameters, as long as they consist of numeric or string values.

A parameter list contains an array of parameters defined by a type and a value. The size of the parameter list is static and can not be changed after it has been initialized, but the list can be freed, and a new list with different size can be created. Each parameter in a list can be overwritten by writing a new parameter to an already used index in the list. When setting a parameter in the list, its value is copied. Parameters should be cleared to free the memory that they occupy. Getter and setter methods are available to read parameter values.

API documentation

Header file: include/modem/at_params.h
Source file: lib/at_cmd_parser/src/at_params.c
group at_params

A parameter list contains an array of parameters defined by a type, a length and a value. Those parameters could be arguments of an AT command, AT response or event, for example. Several parameter types can be stored. They can be arrays or a single numeric or string values. Optional or empty parameters are supported. The same list of parameters can be reused. Each parameter can be updated or cleared. A parameter type or value can be changed at any time. Once the parameter list is created, its size cannot be changed. All parameters values are copied in the list. Parameters should be cleared to free that memory. Getter and setter methods are available to read and write parameter values.

Enums

enum at_param_type

Parameter types that can be stored.

Values:

enumerator AT_PARAM_TYPE_INVALID

Invalid parameter, typically a parameter that does not exist.

enumerator AT_PARAM_TYPE_NUM_SHORT

Parameter of type short.

enumerator AT_PARAM_TYPE_NUM_INT

Parameter of type integer.

enumerator AT_PARAM_TYPE_STRING

Parameter of type string.

enumerator AT_PARAM_TYPE_ARRAY

Parameter of type array.

enumerator AT_PARAM_TYPE_EMPTY

Empty or optional parameter that should be skipped.

Functions

int at_params_list_init(struct at_param_list *list, size_t max_params_count)

Create a list of parameters.

An array of max_params_count is allocated. Each parameter is initialized to its default value. This function should not be called again before freeing the list.

Parameters

  • [in] list: Parameter list to initialize.

  • [in] max_params_count: Maximum number of element that the list can store.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

void at_params_list_clear(struct at_param_list *list)

Clear/reset all parameter types and values.

All parameter types and values are reset to default values.

Parameters

  • [in] list: Parameter list to clear.

void at_params_list_free(struct at_param_list *list)

Free a list of parameters.

First the list is cleared. Then the list and its elements are deleted.

Parameters

  • [in] list: Parameter list to free.

int at_params_short_put(const struct at_param_list *list, size_t index, uint16_t value)

Add a parameter in the list at the specified index and assign it a short value.

If a parameter exists at this index, it is replaced.

Parameters

  • [in] list: Parameter list.

  • [in] index: Index in the list where to put the parameter.

  • [in] value: Parameter value.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_int_put(const struct at_param_list *list, size_t index, uint32_t value)

Add a parameter in the list at the specified index and assign it an integer value.

If a parameter exists at this index, it is replaced.

Parameters

  • [in] list: Parameter list.

  • [in] index: Index in the list where to put the parameter.

  • [in] value: Parameter value.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_string_put(const struct at_param_list *list, size_t index, const char *str, size_t str_len)

Add a parameter in the list at the specified index and assign it a string value.

The parameter string value is copied and added to the list as a null-terminated string. If a parameter exists at this index, it is replaced.

Parameters

  • [in] list: Parameter list.

  • [in] index: Index in the list where to put the parameter.

  • [in] str: Pointer to the string value.

  • [in] str_len: Number of characters of the string value str.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_array_put(const struct at_param_list *list, size_t index, const uint32_t *array, size_t array_len)

Add a parameter in the list at the specified index and assign it an array type value.

The parameter array value is copied and added to the list. If a parameter exists at this index, it is replaced. Only numbers (uint32_t) are currently supported. If the list contain compound values the parser will try to convert the value. Either 0 will be stored or if the value start with a numeric value that value will be converted, the rest of the value will be ignored. Ie. 5-23 will result in 5.

Parameters

  • [in] list: Parameter list.

  • [in] index: Index in the list where to put the parameter.

  • [in] array: Pointer to the array of number values.

  • [in] array_len: In bytes (must currently be divisible by 4)

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_empty_put(const struct at_param_list *list, size_t index)

Add a parameter in the list at the specified index and assign it a empty status.

This will indicate that an empty parameter was found when parsing the AT string.

Parameters

  • [in] list: Parameter list.

  • [in] index: Index in the list where to put the parameter.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_size_get(const struct at_param_list *list, size_t index, size_t *len)

Get the size of a given parameter (in bytes).

A size of ‘0’ is returned for invalid and empty parameters.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

  • [out] len: Length of the parameter in bytes.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_short_get(const struct at_param_list *list, size_t index, uint16_t *value)

Get a parameter value as a short number.

Numeric values are stored as unsigned number. The parameter type must be a short, or an error is returned.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

  • [out] value: Parameter value.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_int_get(const struct at_param_list *list, size_t index, uint32_t *value)

Get a parameter value as an integer number.

Numeric values are stored as unsigned number. The parameter type must be an integer, or an error is returned.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

  • [out] value: Parameter value.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_string_get(const struct at_param_list *list, size_t index, char *value, size_t *len)

Get a parameter value as a string.

The parameter type must be a string, or an error is returned. The string parameter value is copied to the buffer. len must be bigger than the string length, or an error is returned. The copied string is not null-terminated.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

  • [in] value: Pointer to the buffer where to copy the value.

  • [inout] len: Available space in value, returns actual length copied into string buffer in bytes.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int at_params_array_get(const struct at_param_list *list, size_t index, uint32_t *array, size_t *len)

Get a parameter value as a array.

The parameter type must be a array, or an error is returned. The string parameter value is copied to the buffer. len must be equal or bigger than the array length, or an error is returned. The copied string is not null-terminated.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

  • [out] array: Pointer to the buffer where to copy the array.

  • [inout] len: Available space in value, returns actual length copied into array buffer in bytes.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

uint32_t at_params_valid_count_get(const struct at_param_list *list)

Get the number of valid parameters in the list.

Return

The number of valid parameters until an empty parameter is found.

Parameters

  • [in] list: Parameter list.

enum at_param_type at_params_type_get(const struct at_param_list *list, size_t index)

Get parameter type for parameter at index.

Return

Return parameter type of at_param_type.

Parameters

  • [in] list: Parameter list.

  • [in] index: Parameter index in the list.

union at_param_value
#include <at_params.h>

Parameter value.

Public Members

uint32_t int_val

Integer value.

char *str_val

String value.

uint32_t *array_val

Array of uint32_t

struct at_param
#include <at_params.h>

A parameter is defined with a type, length and value.

struct at_param_list
#include <at_params.h>

List of AT parameters that compose an AT command or response.

Contains an array of opaque data. Setter and getter methods should be used to get access to the parameters in the array.