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¶
include/modem/at_params.h
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_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.
-
enumerator
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
list – [in] Parameter list to initialize.
max_params_count – [in] Maximum number of element that the list can store.
- Returns 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
list – [in] 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
list – [in] Parameter list to free.
-
int
at_params_int_put
(const struct at_param_list *list, size_t index, int64_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
list – [in] Parameter list.
index – [in] Index in the list where to put the parameter.
value – [in] Parameter value.
- Returns 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
list – [in] Parameter list.
index – [in] Index in the list where to put the parameter.
str – [in] Pointer to the string value.
str_len – [in] Number of characters of the string value
str
.
- Returns 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
list – [in] Parameter list.
index – [in] Index in the list where to put the parameter.
array – [in] Pointer to the array of number values.
array_len – [in] In bytes (must currently be divisible by 4)
- Returns 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
list – [in] Parameter list.
index – [in] Index in the list where to put the parameter.
- Returns 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
list – [in] Parameter list.
index – [in] Parameter index in the list.
len – [out] Length of the parameter in bytes.
- Returns 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, int16_t *value)¶ Get a parameter value as a short number.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [out] Parameter value.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
int
at_params_unsigned_short_get
(const struct at_param_list *list, size_t index, uint16_t *value)¶ Get a parameter value as a unsigned short number.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [out] Parameter value.
- Returns 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, int32_t *value)¶ Get a parameter value as an integer number.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [out] Parameter value.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
int
at_params_unsigned_int_get
(const struct at_param_list *list, size_t index, uint32_t *value)¶ Get a parameter value as an unsigned integer number.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [out] Parameter value.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
int
at_params_int64_get
(const struct at_param_list *list, size_t index, int64_t *value)¶ Get a parameter value as an signed 64-bit integer number.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [out] Parameter value.
- Returns 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
list – [in] Parameter list.
index – [in] Parameter index in the list.
value – [in] Pointer to the buffer where to copy the value.
len – [inout] Available space in
value
, returns actual length copied into string buffer in bytes.
- Returns 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
list – [in] Parameter list.
index – [in] Parameter index in the list.
array – [out] Pointer to the buffer where to copy the array.
len – [inout] Available space in
value
, returns actual length copied into array buffer in bytes.
- Returns 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.
- Parameters
list – [in] Parameter list.
- Returns
The number of valid parameters until an empty parameter is found.
-
enum at_param_type
at_params_type_get
(const struct at_param_list *list, size_t index)¶ Get parameter type for parameter at index.
- Parameters
list – [in] Parameter list.
index – [in] Parameter index in the list.
- Returns
Return parameter type of at_param_type.
-
union
at_param_value
¶ - #include <at_params.h>
Parameter value.
-
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.
-
enum