JANSSON模块在STM32产品开发中的应用

背景

项目中用到语音识别和控制,底层采用 STM32+VS1053 的方式来解决音频的编解码问题,然后将音频通过 Wi-Fi 透传送至百度语音识别的REST API接口。接口返回 JSON 格式的数据,进一步与图灵机器人的api进行通讯,也需要 JSON 格式的数据。所以想要移植一个 JSON 的库来解决这个问题。
目前比较合适的选择有cJSON。相关资料也多,没去仔细看,还有一个是网友分享的基于cJSON的-C结构体与JSON快速互转库,也是开源的,献上github的传送门。但是,在多方找寻之后,发现MDK已经移植好了Jansson。也适用于Cortex-M内核,也就不想去折腾其他,而且这个库好像挺强大了,但是准备开始用才发现,貌似用在 stm3 2上的资料不是很多,所以只能硬着头皮看文档。为了将碎片化的认知和一些翻译理解记录下来,所以也就有了该博文。

版本

MDK版本:v5.23
Jansson版本:v2.7.0

安装

  1. 打开MDK后,点击工具栏中 PackInstaller 图标打开 Pack Installer 界面。
    image1.jpg
  2. 在 Pack Installer 界面选择 Keil::Jansson 库进行安装。
    image2.jpg
  3. 在项目中启用 Jansson ,点击打开 Manage Run-Time Environment 界面,勾选Data Exchange ---> JSON ---> Jansson 启用。
    image3.jpg
  4. 在使用的地方包含 jasson的头文件即可。

函数说明书

  • 作用:创建一个json对象。是新的一个引用
json_t *json_object(void);
  • 作用:返回json对象中的成员数量(键值对?好几层的怎办)
size_t json_object_size(const json_t *object)
  • 作用:获取跟名称相对应的值。(这里使用了一个引用,注意维护引用数)
json_t *json_object_get(const json_t *object, const char *key)
  • 作用:设置与名称相对应的值,值不能为空,且必须喂UTF-8编码,会取代原先值,成功返回 0 . 错误返回 -1
int json_object_set(json_t *object, const char *key, json_t *value)
  • 作用:类似json_object_set() ,但是这个函数不会校验值是否是UTF-8的 编码,如果你确认是UTF-8或者有其他方式进行校验时,可以使用这个函数。
int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
  • 作用:类似json_object_set(),但这个函数会抢占json格式的值(json_t value)的引用,一般用在json格式的值(json_t value)只为此次键值对赋值的情况 下,用完就没用了
int json_object_set_new(json_t *object, const char *key, json_t *value)
  • 作用:类似json_object_set_new(),但是这个函数不会校验值是否是UTF-8的编码,如果你确认是UTF-8或者有其他方式进行校验时,可以使用这个函数。
int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
  • 作用:从json数据删除对应的键值对,成功返回0.没找到返回-1.被删除的值的引用计数会递减
int json_object_del(json_t *object, const char *key)
  • 作用,清空json数据中的所有元素。成功返回0.对象不是json格式则返回-1.被删除的值的引用计数会递减
int json_object_clear(json_t *object)
  • 作用:把 other 中的键值对数据复制到 object 中,有相同的键的则覆盖其值。成功返回0,错误返回-1
int json_object_update(json_t *object, json_t *other)
  • 作用:类似 json_object_update() ,但只是更新已有的键值对,不会在 other 的json对象中生成新的键值对.成功返回0,错误返回-1
    2.3版本中新增
int json_object_update_existing(json_t *object, json_t *other)
  • 作用:类似 json_object_update() ,但只会创建新的键值对,不会改变已有的键值对,成功返回0,错误返回-1
    2.3版本中新增
int json_object_update_missing(json_t *object, json_t *other)
  • 作用:历遍json数据中的所有键值对,每个键值对都会执行后面的程序块用来设 置键和值?(应该是这个作用把,暂未用到,还不太清楚)
    2.3版本中新增

这是个宏定义。该宏在预处理时扩展为普通的for语句,因此其性能与使用对象迭代协议的手写迭代代码相同(见下文)。 这个宏的主要优点在于它可以消除迭代的复杂性,并且使得代码 更简洁易读。

json_object_foreach(object, key, value)

原文如下:Iterate over every key-value pair of object, running the block of code that follows each time with the proper values set to variables key and value, of types const char and json_t respectively. Example:

/* obj is a JSON object */
const char key;
json_t value;
json_object_foreach(obj, key, value) {
/* block of code that uses key and value */
}

项目按照插入对象的顺序返回。

  • 作用:类似于json_object_foreach,但此函数可以在迭代期间安全的调用json_object_del(object, key)函数,你只需要在形参输入一个函数指针变量用于临时存储
    2.8版本中新增
json_object_foreach_safe(object, tmp, key, value)

以下函数可用于遍历对象中的所有键值对。 项目按照插入对象的顺序返回。

  • 作用:返回一个可以用来历遍json数据中所有键值对的不透明的迭代器,json对象如果是空就返回NULL;注意函数指针
void *json_object_iter(json_t *object)
  • 作用:类似于 json_object_iter() ,但返回的只是和形参中键相等的键值对迭 代器,如果没有则返回NULL。
void *json_object_iter_at(json_t *object, const char *key)

这个清空还不能理解,原文如下: Iterating forward to the end of object only yields all keyvalue pairs of the object if key happens to be the first key in the underlying hash table.

  • 作用:返回一个指向json对象中下一对键值对的迭代器,如果已历遍json对象则 返回NULL
void *json_object_iter_next(json_t *object, void *iter)
  • 作用:提取指定的迭代的键
const char *json_object_iter_key(void *iter)
  • 作用:提取指定的迭代的值,借用的引用+1
json_t *json_object_iter_value(void *iter)
  • 作用:修改指定的迭代所指向的json对象中的键值对的值
int json_object_iter_set(json_t *object, void *iter, json_t *value)
  • 作用:类似 json_object_iter_set() ,但这个函数会抢占json格式的值 (json_t value)的引用,一般用在json格式的值(json_t value)只为此次键值对赋值的情况下,用完就没用了
int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
  • 作用:类似于json_object_iter_at(),但是会快很多,但仅适用于json_object_iter_key()函数返回的键。如果使用其他方式的键则会导致段错误。
    2.3版本中新增
void *json_object_key_to_iter(const char *key)

此函数常应用在json_object_foreach()里面,例如

/* obj is a JSON object */
const char key;
json_t value;
void iter = json_object_iter(obj);
while(iter)
{
  key = json_object_iter_key(iter);
  value = json_object_iter_value(iter);
  /* use key and value ... */
  iter = json_object_iter_next(obj, iter);
}
  • 作用:设置用于实现Jansson的哈希表的哈希函数的种子。 种子用于随机化哈希函数, 以便攻击者无法控制其输出。
    如果种子为0,Jansson通过从操作系统的熵源读取随机数据来生成种子本身。如果没有熵源可用,则返回到使用当前时间戳的组合(如果可能的话,具有微秒精度)和进程ID。如果被调用,则在调用json_object()之前必须调用此函数,无论是显式还是隐式。 如果这个函数没有被用户调用,那么第一次调用 json_object()(显式的或者 隐式的)会使哈希函数成为种子。 有关线程安全性的说明,请参阅线程安全如果需要可重复的结果,例如单元测试,哈希函数可以通过在程序启动时调用形参为常量的json_object_seed()函数来“伪随机化”,例 如json_object_seed(1)

2.6版本中新增

void json_object_seed(size_t seed)
  • 作用:返回一个新的JSON数组,错误则返回NULL,最开始数组为空,是一个新的引用
json_t *json_array(void)
  • 作用:返回数组中的成员数量,如果为空或者不是json数组,则返回0.
size_t json_array_size(const json_t *array)
  • 作用:返回json数组中相应索引位置的成员,index的有效范围是0( json_array_size() - 1),假如该数组不是json数组,或者index索引超出范围,则返回NULL。借用引用
json_t *json_array_get(const json_t *array, size_t index)
  • 作用:替换json数组中指定位置的json成员,index(索引)的有效范围是0( json_array_size() - 1),成功返回0,错误返回-1
int json_array_set(json_t *array, size_t index, json_t *value)
  • 作用:类似 json_array_set() 但会抢占形参value的引用数,通常用在仅为此 次调用而创建的value的情况下
int json_array_set_new(json_t *array, size_t index, json_t *value)
  • 作用:将value添加至json数组的末尾,变成新的数组成员,数组的大小加1。成功返回0.错误返回-1;
int json_array_append(json_t *array, json_t *value)
  • 作用:类似json_array_append(),但会抢占形参value的引用数,通常用在仅为此次调用而创建的value的情况下
int json_array_append_new(json_t *array, json_t *value)
  • 作用:将值插入到数组的指定位置,索引位置的数组成员及其后面的数组成员依 次后移,成功返回0.错误返回-1。
int json_array_insert(json_t *array, size_t index, json_t*value) 
  • 作用:类似 json_array_insert() ,但会抢占形参value的引用数,通常用在仅 为此次调用而创建的value的情况下
int json_array_insert_new(json_t *array, size_t index, json_t*value)
  • 作用:删除json数组中指定位置的值,后排元素依次前移,成功返回0.错误返回-1,被删除的元素引用减 1
int json_array_remove(json_t *array, size_t index)
  • 作用:清空数组,删除组内所有成员,被删除的元素的引用相应减1
int json_array_clear(json_t *array)
  • 作用:合并json数组,将另一组Json数组成员添加至json数组的最后成员的后 面,成功返回 0,错误返回-1
int json_array_extend(json_t *array, json_t *other_array)
  • 作用:历遍数组内所有成员,每迭代一次便执行一次后面的用于修改变量index和 value的代码块,注意分别屎size_t和 json_t *的数据格式
    2.5版本中新增

这些项目按照索引顺序递增。该宏在预处理时扩展为普通的for语句,因此其性能与使用数组访问功能的手写代码相 当。这个宏的主要优点在于它可以消除复杂性,从而使得更简洁易读的代码。

/* array is a JSON array */
size_t index; json_t value;
json_array_foreach(array, index, value) { /* block of code that uses index and value */
}
json_array_foreach(array, index, value)
  • 作用:创建一个新的JSON字符串,错误时返回NULL,值必须是一个只有UTF-8 编码的空终止字符串。会新生成一个引用。
json_t *json_string(const char *value)
  • 作用:类似 json_string() ,但规定了长度,所以值可能包含空字符,未必是 空终止字符串。会新生成一个引用。
json_t *json_stringn(const char *value, size_t len)
  • 作用:类似 json_string() ,但不会去校验是否是UTF-8编码,需要自行确认, 通常用在已确定变量是utf-8的情况。会新生成一个引用。
json_t *json_string_nocheck(const char *value)
  • 作用:类似 json_string_nocheck() ,但规定了长度,所以值可能包含空字 符,未必是空终止字符串。会新生成一个引用
json_t *json_stringn_nocheck(const char *value, size_t len)
  • 作用:获取字符串的关联值,比如UTF-8编码的的空终止字符串,如果形参不是json格式字符串,则返回是NULL
    返回的值是只读的,不能被用户修改或释放。 只要字符串存在,即只要其引用计数没有下降到零,它是有效的。
const char *json_string_value(const json_t *string)
  • 作用:获得utf-8格式的json字符串的长度。如果不是json格式则返回0
size_t json_string_length(const json_t *string)
  • 作用:设置相应字符串的值将字符串,形参必须是有效的utf-8编码的字符串,成功返回0.错误返回-1
int json_string_set(json_t *string, const char *value)
  • 作用:类似 json_string_set() ,但有既定的长度,所以值可能包含空字符, 或者不是空终止字符串。
int json_string_setn(json_t *string, const char *value, size_t len)
  • 作用:类似 json_string_set() ,但不会去校验输入的值是否是UTF-8的编码
int json_string_set_nocheck(json_t *string, const char *value)
  • 作用:类似 json_string_set_nocheck() ,但有既定的长度,所以值可能包 含空字符,或者不是空终止字符串。
int json_string_setn_nocheck(json_t *string, const char *value,size_t len)
  • 作用:创建一个json的整形变量,新生成一个引用,错误返回NULL
json_t *json_integer(json_int_t value)
  • 作用:获取该json整形变量的值,类型不符则返回0
json_int_t json_integer_value(const json_t *integer)
  • 作用:给json整形变量赋值。成功返回0,类型不符返回-1
int json_integer_set(const json_t *integer, json_int_t value)
  • 作用:创建一个json的实数类型的变量,新生成一个引用,错误返回NULL
json_t *json_real(double value)
  • 作用:获取该实数类型变量的值,类型不符则返回0
double json_real_value(const json_t *real)
  • 作用:给实数类型变量赋值。成功返回0,类型不符返回-1
int json_real_set(const json_t *real, double value)
  • 作用:获取json数据的值,不管是整形还是实数类型,值都转换未double类型,如果不是整形也不是实数类型,则返回0.0;
double json_number_value(const json_t *json)
最后修改:2019 年 07 月 08 日 01 : 21 PM
如果觉得我的文章对你有用,请随意赞赏

发表评论