title: C/OpenWRT API 文档

Wilddog (Methods)

wilddog_initWithUrl()

定义

Wilddog_T wilddog_initWithUrl(Wilddog_Str_T *url)

说明

初始化应用 URL 对应的 Wilddog 引用，并与 URL 建立会话。

参数

  • Wilddog_Str_T *url : 应用URL。Wilddog 中任何数据都能够通过一个URL来进行访问，如coap[s]://<SyncAppID>.wilddogio.com/<path> 其中为开发者在 Wilddog 平台申请的应用id。 为客户端关注的路径。

返回值

Wilddog_T 类型Wilddog引用的id，如果创建失败，返回0。

示例

  1. int main(){
  2.     //初始化引用
  3.     Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy/device/light/10abcde");
  5.     //do something
  6.     ...
  8.     //销毁引用
  9.     wilddog_destroy(&wilddog);
  10. }

wilddog_destroy()

定义

Wilddog_Return_T wilddog_destroy(Wilddog_T *p_wilddog)

说明

销毁一个引用并回收内存。

参数

  • p_wilddog Wilddog_T* : 当前节点引用id的地址。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //销毁引用
  5. wilddog_destroy(&wilddog);

wilddog_getValue()

定义

Wilddog_Return_T wilddog_getValue(Wilddog_T wilddog, onQueryFunc callback, void* arg)

说明

获取当前节点的数据,数据格式为Wilddog_Node_T(类似JSON)。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • callback onQueryFunc : 服务端回应数据或者回应超时触发的回调函数,类型是void (*onQueryFunc)(const Wilddog_Node_T* p_snapshot, void* arg, Wilddog_Return_T err),其中p_snapshot是取回的数据镜像（err为200时）或者NULL，退出函数后即被销毁, arg为用户传递的值, err为状态码。
  • arg void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onQueryCallback(const Wilddog_Node_T* p_snapshot, void* arg, Wilddog_Return_T err){
  2.     if(err != WILDDOG_HTTP_OK){
  3.         wilddog_debug("query error!");
  4.         return;
  5.     }
  6.     wilddog_debug("query success!");
  7.     if(p_snapshot){
  8.         *(Wilddog_Node_T**)arg = wilddog_node_clone(p_snapshot);
  9.     }
  10.     return;
  11. }
  12. int main(void){
  13.     Wilddog_T wilddog = 0;
  15.     //用户自定义参数，这里的用途为：将云端发回的数据clone到本地
  16.     Wilddog_Node_T * p_node = NULL;
  18.     //<url>即希望获取数据的url，如https://<SyncAppID>.wilddogio.com/a/b/c
  19.     wilddog = wilddog_initWithUrl(<url>);
  21.     //注意，这里省略了对wilddog_getValue返回值的检查
  22.     wilddog_getValue(wilddog, onQueryCallback, (void*)(&p_node));
  24.     while(1){
  25.         if(p_node){
  27.             //打印得到的节点数据
  28.             _wilddog_debug_printnode(p_node);
  29.             ...
  30.             wilddog_node_delete(p_node);
  31.         }
  32.         wilddog_trySync();
  33.     }
  34.     ...
  35.     wilddog_destroy(&wilddog);
  36. }

wilddog_setValue()

定义

Wilddog_Return_T wilddog_setValue(Wilddog_T wilddog, Wilddog_Node_T *p_node, onSetFunc callback, void *arg)

说明

设置当前节点的数据,数据格式为Wilddog_Node_T。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • p_node Wilddog_Node_T : 指向节点数据的指针，注意，头节点即为当前的 wilddog 节点。
  • callback onSetFunc : 服务端回应或者回应超时触发的回调函数 ,类型是void (*onSetFunc)(void* arg, Wilddog_Return_T err),其中arg为用户传递的值,err为状态码。
  • arg void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onSetCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("set error!");
  4.         return;
  5.     }
  6.     wilddog_debug("set success!");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     //用户自定义参数，这里的用途为：初始化为FALSE，回调函数中设为TRUE
  12.     //因此可以在main函数中得知是否成功
  13.     BOOL isFinish = FALSE;
  14.     Wilddog_T wilddog = 0;
  15.     Wilddog_Node_T * p_node = NULL;
  17.     /* create a node to "wilddog", value is "123456" */
  18.     p_node = wilddog_node_createUString(NULL,"123456");
  20.     //<url>即希望设置数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  21.     wilddog = wilddog_initWithUrl(<url>);
  23.     //注意，这里省略了对wilddog_setValue返回值的检查
  24.     wilddog_setValue(wilddog, p_node, onSetCallback, (void*)&isFinish);
  26.     //数据已经设置到云端，删除刚才建立的节点
  27.     wilddog_node_delete(p_node);
  29.     while(1){
  30.         if(TRUE == isFinish){
  31.             wilddog_debug("set success!");
  32.             ...
  33.         }
  34.         wilddog_trySync();
  35.     }
  36.     wilddog_destroy(&wilddog);
  37. }

wilddog_push()

定义

Wilddog_Return_T wilddog_push( Wilddog_T wilddog, Wilddog_Node_T *p_node, onPushFunc callback, void *arg)

说明

在当前节点下追加一个子节点，并在回调中返回该子节点的完整路径 。子节点的 key 由服务端根据当前时间生成。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • p_node Wilddog_Node_T* : 指向新增节点数据的指针，注意，头节点即为当前的 wilddog 节点。
  • callback onPushFunc : 服务端回应或者回应超时触发的回调函数 ,类型是(*onPushFunc)(Wilddog_Str_T * p_newPath, void* arg, Wilddog_Return_T err),其中 p_newPath 是新增节点的完整路径,arg 为用户传递的值,err 为状态码。

  • arg void* : 用户给回调函数传入的参数。

    返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见 wilddog.h。

示例

  1. STATIC void onPushCallback(u8 *p_path,void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("push failed");
  4.         return;
  5.     }
  6.     wilddog_debug("new path is %s", p_path);
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  11. int main(void){
  12.     //用户自定义参数，这里的用途为：初始化为FALSE，回调函数中设为TRUE
  13.     //因此可以在main函数中得知是否成功
  14.     BOOL isFinish = FALSE;
  15.     Wilddog_T wilddog = 0;
  16.     Wilddog_Node_T * p_node = NULL, *p_head = NULL;
  18.     //建立一个object节点，即类似json中的{}
  19.     p_head = wilddog_node_createObject(NULL);
  21.     //建立一个key为2，value为数字1234的节点
  22.     p_node = wilddog_node_createNum("2",1234);
  24.     //将节点p_node添加到object中
  25.     wilddog_node_addChild(p_head, p_node);
  27.     //<url>即希望推送数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  28.     wilddog = wilddog_initWithUrl(<url>);
  30.     //把新的object推送到云端
  31.     //注意，这里省略了对wilddog_push返回值的检查
  32.     wilddog_push(wilddog, p_head, onPushCallback, (void *)&isFinish);
  34.     //数据已经推送，删除刚才建立的节点
  35.     wilddog_node_delete(p_head);
  37.     while(1){
  38.         if(isFinish){
  39.             wilddog_debug("push success!");
  40.             break;
  41.         }
  42.         wilddog_trySync();
  43.     }
  44.     wilddog_destroy(&wilddog);
  45. }

wilddog_removeValue()

定义

Wilddog_Return_T wilddog_removeValue(Wilddog_T wilddog, onRemoveFunc callback, void *arg)

说明

删除当前节点及节点下所有数据。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • callback onRemoveFunc : 服务器回应或者回应超时触发的回调函数，类型是void (*onRemoveFunc)(void* arg, Wilddog_Return_T err),其中arg 为用户传递的值,err 为状态码。
  • arg void* : 用户传给回调函数的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onDeleteCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("delete failed!");
  4.         return;
  5.     }
  6.     wilddog_debug("delete success!");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     //用户自定义参数，这里的用途为：初始化为FALSE，回调函数中设为TRUE
  12.     //因此可以在main函数中得知是否成功
  13.     BOOL isFinished = FALSE;
  14.     Wilddog_T wilddog;
  16.     //<url>即希望删除数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  17.     wilddog = wilddog_initWithUrl(<url>);
  19.     //注意，这里省略了对wilddog_removeValue返回值的检查
  20.     wilddog_removeValue(wilddog, onDeleteCallback, (void*)&isFinished);
  22.     while(1){
  23.         if(TRUE == isFinished){
  24.             wilddog_debug("remove success!");
  25.             break;
  26.         }
  27.         wilddog_trySync();
  28.     }
  29.     wilddog_destroy(&wilddog);
  30. }

wilddog_addObserver()

定义

Wilddog_Return_T wilddog_addObserver(Wilddog_T wilddog, Wilddog_EventType_T event, onEventFunc onDataChange, void *dataChangeArg)

说明

监听节点的数据变化。一旦该数据发生改变, onDataChange函数将被调用。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • event Wilddog\_EventType\_T : 关注的事件类型，见Wilddog_EventType_T定义。
  • onDataChange onEventFunc : 数据变化所触发的回调函数，类型是(*onEventFunc)(const Wilddog_Node_T* p_snapshot, void* arg, Wilddog_Return_T err),其中p_snapshot是取回的数据镜像（err为200时）或者NULL，退出函数后即被销毁, arg为用户传递的值, err为状态码。
  • dataChangeArg void* : 传给回调函数的arg。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onObserverCallback(const Wilddog_Node_T* p_snapshot, void* arg, Wilddog_Return_T err){
  2.     if(err != WILDDOG_HTTP_OK){
  3.         wilddog_debug("observe failed!");
  4.         return;
  5.     }
  6.     wilddog_debug("observe data!");
  7.     return;
  8. }
  9. int main(void){
  10.     //用户自定义参数，这里的用途为：初始化为FALSE，回调函数中设为TRUE
  11.     //因此可以在main函数中得知是否成功
  12.     BOOL isFinished = FALSE;
  13.     Wilddog_T wilddog = 0;
  14.     STATIC int count = 0;
  16.     //<url>即希望订阅数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  17.     wilddog = wilddog_initWithUrl(<url>);
  19.     //注意，这里省略了对wilddog_addObserver返回值的检查
  20.     wilddog_addObserver(wilddog, WD_ET_VALUECHANGE, onObserverCallback, (void*)&isFinished);
  22.     while(1){
  23.         if(TRUE == isFinished){
  24.             //每次接收到推送count + 1
  25.             wilddog_debug("get new data %d times!", count++);
  27.             //重新设置接收状态为FALSE
  28.             isFinished = FALSE;
  30.             //count 超过10时，调用wilddog_removeObserver取消订阅，并退出
  31.             if(count > 10){
  32.                 wilddog_debug("off the data!");
  33.                 wilddog_removeObserver(wilddog, WD_ET_VALUECHANGE);
  34.                 break;
  35.             }
  36.         }
  37.         wilddog_trySync();
  38.     }
  39.     wilddog_destroy(&wilddog);
  40. }

wilddog_removeObserver()

定义

Wilddog_Return_T wilddog_removeObserver(Wilddog_T *p_wilddog, Wilddog_EventType_T event)

说明

取消对某节点的监听(对应于on)。

参数

  • p_wilddog Wilddog_T* : 当前节点引用的id。
  • event Wilddog_EventType_T : 取消的事件类型。

返回值

Wilddog_Return_T返回 0:成功 <0:失败，返回码见wilddog.h。

示例

见wilddog_addObserver的示例。

wilddog_onDisconnectSetValue()

定义

Wilddog_Return_T wilddog_onDisconnectSetValue(Wilddog_T wilddog, Wilddog_Node_T *p_node, onDisConnectFunc callback, void* arg)

说明

当该客户端离线时，云端自动执行该操作，设置当前节点的数据，数据格式为Wilddog_Node_T。回调函数用于判断该离线事件是否成功注册。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • p_node Wilddog_Node_T : 指向离线时设置的节点数据的指针，注意，头节点即为当前的 wilddog 节点。
  • callback onDisConnectFunc : 服务端回应或者回应超时触发的回调函数 ,类型是void (*onDisConnectFunc)(void* arg, Wilddog_Return_T err),其中arg为用户传递的值,err为状态码。
  • arg void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onSetCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("offline set error!");
  4.         return;
  5.     }
  6.     wilddog_debug("offline set success!");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     //用户自定义参数，这里的用途为：初始化为FALSE，回调函数中设为TRUE
  12.     //因此可以在main函数中得知是否成功
  13.     BOOL isFinish = FALSE;
  14.     Wilddog_T wilddog = 0;
  15.     Wilddog_Node_T * p_node = NULL;
  17.     /* create a node to "wilddog", value is "123456" */
  18.     p_node = wilddog_node_createUString(NULL,"123456");
  20.     //<url>即希望设置数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  21.     wilddog = wilddog_initWithUrl(<url>);
  23.     //注意，这里省略了对wilddog_onDisconnectSetValue返回值的检查
  24.     wilddog_onDisconnectSetValue(wilddog, p_node, onSetCallback, (void*)&isFinish);
  25.     wilddog_node_delete(p_node);
  27.     while(1){
  28.         if(TRUE == isFinish){
  29.             wilddog_debug("set success!");
  30.             ...
  31.         }
  32.         wilddog_trySync();
  33.     }
  34.     wilddog_destroy(&wilddog);
  35. }

wilddog_onDisconnectPush()

定义

Wilddog_Return_T wilddog_onDisconnectPush( Wilddog_T wilddog, Wilddog_Node_T *p_node, onDisConnectFunc callback, void* arg)

说明

当该客户端离线时，云端自动执行该操作，在当前节点下生成一个子节点。子节点的key利用服务端的当前时间生成。回调函数用于判断该离线事件是否成功注册。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • p_node Wilddog_Node_T* : 指向离线时新增节点数据的指针，注意，头节点即为当前的 wilddog 节点。
  • callback onDisConnectFunc : 服务端回应或者回应超时触发的回调函数 ,类型是(*onDisConnectFunc)(void* arg, Wilddog_Return_T err),其中arg为用户传递的值,err为状态码。
  • arg void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onPushCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("offline push failed");
  4.         return;
  5.     }
  6.     wilddog_debug("offline push success");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     BOOL isFinish = FALSE;
  12.     Wilddog_T wilddog = 0;
  13.     Wilddog_Node_T * p_node = NULL, *p_head = NULL;
  14.     p_head = wilddog_node_createObject(NULL);
  15.     p_node = wilddog_node_createNum("2",1234);
  16.     wilddog_node_addChild(p_head, p_node);
  18.     //<url>即希望推送数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  19.     wilddog = wilddog_initWithUrl(<url>);
  21.     //注意，这里省略了对wilddog_onDisconnectPush返回值的检查
  22.     wilddog_onDisconnectPush(wilddog, p_head, onPushCallback, (void *)&isFinish);
  23.     wilddog_node_delete(p_head);
  25.     while(1){
  26.         if(isFinish){
  27.             wilddog_debug("push success!");
  28.             break;
  29.         }
  30.         wilddog_trySync();
  31.     }
  32.     wilddog_destroy(&wilddog);
  33. }

wilddog_onDisconnectRemoveValue()

定义

Wilddog_Return_T wilddog_onDisconnectRemoveValue(Wilddog_T wilddog, onDisConnectFunc callback, void* arg)

说明

当该客户端离线时，云端自动执行该操作，删除当前节点及节点下所有数据。回调函数用于判断该离线事件是否成功注册。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • callback onDisConnectFunc : 服务端回应或者回应超时触发的回调函数 ,类型是(*onDisConnectFunc)(void* arg, Wilddog_Return_T err),其中arg为用户传递的值,err为状态码。
  • arg void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onDeleteCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("offline delete failed!");
  4.         return;
  5.     }
  6.     wilddog_debug("offline delete success!");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     BOOL isFinished = FALSE;
  12.     Wilddog_T wilddog = 0;
  14.     //<url>即希望删除数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  15.     wilddog = wilddog_initWithUrl(<url>);
  17.     //注意，这里省略了对wilddog_onDisconnectRemoveValue返回值的检查
  18.     wilddog_onDisconnectRemoveValue(wilddog, onDeleteCallback, (void*)&isFinished);
  20.     while(1){
  21.         if(TRUE == isFinished){
  22.             wilddog_debug("remove success!");
  23.             break;
  24.         }
  25.         wilddog_trySync();
  26.     }
  27.     wilddog_destroy(&wilddog);
  28. }

wilddog_cancelDisconnectOperations()

定义

Wilddog_Return_T wilddog_cancelDisconnectOperations(Wilddog_T wilddog, onDisConnectFunc callback, void* arg)

说明

取消之前设置的离线事件。

参数

  • wilddog Wilddog_T : 当前节点引用的id。
  • callback onDisConnectFunc : 服务端回应或者回应超时触发的回调函数 ,类型是(*onDisConnectFunc)(void* arg, Wilddog_Return_T err),其中arg为用户传递的值,err为状态码。

  • arg void* : 用户给回调函数传入的参数。

    返回值

Wilddog_Return_T 返回 0:成功 <0:失败，返回码见wilddog.h。

示例

  1. STATIC void onCancelCallback(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  3.         wilddog_debug("offline operation cancel failed!");
  4.         return;
  5.     }
  6.     wilddog_debug("offline operation cancel success!");
  7.     *(BOOL*)arg = TRUE;
  8.     return;
  9. }
  10. int main(void){
  11.     BOOL isFinished = FALSE;
  12.     Wilddog_T wilddog = 0;
  14.     //<url>即希望删除数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  15.     wilddog = wilddog_initWithUrl(<url>);
  17.     //注意，这里省略了对wilddog_cancelDisconnectOperations返回值的检查
  18.     wilddog_cancelDisconnectOperations(wilddog, onCancelCallback, (void*)&isFinished);
  20.     while(1){
  21.         if(TRUE == isFinished){
  22.             wilddog_debug("operation cancel success!");
  23.             break;
  24.         }
  25.         wilddog_trySync();
  26.     }
  27.     wilddog_destroy(&wilddog);
  28. }

wilddog_goOffline()

定义

void wilddog_goOffline(void)

说明

通过调用wilddog_goOffline 断开客户端和云端的连接，之前若注册了离线事件则云端会触发离线事件。

返回值

void

wilddog_goOnline()

定义

void wilddog_goOnline(void)

说明

通过调用wilddog_goOnline 若客户端处于离线状态，则重新连接云端服务，之前若注册了监听事件，则 SDK 回重新发送监听请求，注意重连时监听回调会触发返回当前的数据。

返回值

void

wilddog_trySync()

定义

void wilddog_trySync(void)

说明

当前网络情况的探测，连接的维持，数据的重发，数据的重发和接收，回调函数的触发均都在 wilddog_trySync 中实现，应当在程序空闲时不断调用该函数。

返回值

void

wilddog_increaseTime()

定义

void wilddog_increaseTime(u32 ms)。

说明

用于校准 Wilddog 的时钟(可以在定时器中调用)。一般情况下 wilddog_trySync() 会根据自己推算的时间执行业务操作，这个时间的推算会有偏差，我们可以通过传入一个时间增量来校准 Wilddog 时钟。

参数

  • ms u32 : 增加的时间(单位为毫秒)。

    返回值

void

示例

  2. while(1){
  3.     sleep(1);
  4.     //this isr is been called per ms。
  5.     wilddog_increaseTime(1000);
  6.     wilddog_trySync();
  7. }

Wilddog(Properties)

wilddog_getParent()

定义

Wilddog_T wilddog_getParent(Wilddog_T wilddog)

说明

获取父节点引用的id。如果当前节点是root节点，创建失败，返回0。

参数

  • wilddog Wilddog_T : 当前节点引用的id。

    返回值

返回父节点引用的id，如果创建失败，返回0。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //定位到user
  5. Wilddog_T parent = wilddog_getParent(wilddog);

wilddog_getRoot()

定义

Wilddog_T wilddog_getRoot(Wilddog_T wilddog)

说明

获取根节点引用的id。

参数

  • wilddog Wilddog_T : 当前节点引用的id。

    返回值

Wilddog_T root : 根节点引用的id，如果失败，返回0。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //定位到root("/")
  5. Wilddog_T root = wilddog_getRoot(wilddog);

wilddog_getChild()

定义

Wilddog_T wilddog_getChild(Wilddog_T wilddog, Wilddog_Str_T *childName)

说明

获取当前引用下名字为 childName 的子节点引用的id。

参数

wilddog Wilddog_T : 当前引用的id。

childName Wilddog_Str_T* : 子节点的相对路径，多级子节点需用’/‘隔开，即使子节点不存在也能创建。

返回值

Wilddog_T 子节点引用的id，如果创建失败，返回0。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //定位到user/jackxy/aaa
  5. Wilddog_T child = wilddog_getChild(wilddog, "aaa");

wilddog_getKey()

定义

Wilddog_Str_T *wilddog_getKey(Wilddog_T wilddog)

说明

获取当前引用的key。

参数

wilddog Wilddog_T : 当前引用的id。

返回值

Wilddog_Str_T 当前引用的key值，如果获取失败，返回NULL。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //获取Key值（即jackxy）
  5. Wilddog_Str_T *key = wilddog_getKey(wilddog);

wilddog_getHost()

定义

Wilddog_Str_T *wilddog_getHost(Wilddog_T wilddog)

说明

获取当前引用的host。

参数

wilddog Wilddog_T : 当前引用的id。

返回值

Wilddog_Str_T 当前引用的host，如果获取失败，返回NULL。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //获取host（即<SyncAppID>.wilddogio.com）
  5. Wilddog_Str_T *host = wilddog_getHost(wilddog);

wilddog_getPath()

定义

Wilddog_Str_T *wilddog_getPath(Wilddog_T wilddog)

说明

获取当前节点的path。

参数

wilddog Wilddog_T : 当前节点的引用id。

返回值

Wilddog_Str_T 当前引用的path，如果获取失败，返回NULL。

示例

  1. //定位到user/jackxy
  2. Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy");
  4. //获取path（即/user/jackxy）
  5. Wilddog_Str_T *path = wilddog_getPath(wilddog);

Node(Methods)

wilddog_node_createObject()

定义

Wilddog_Node_T * wilddog_node_createObject(Wilddog_Str_T *key)

说明

创建一个 Object 类型的节点，Object 类型的节点，通俗的来说就是非叶子节点，这种类型的节点的子节点就是它们的值。

参数

  • key Wilddog_Str_T* : 节点的 key 值。

    返回值

创建成功则返回该节点的指针，失败返回 NULL。

示例

  1. Wilddog_Node_T *p_node = wilddog_node_createObject((Wilddog_Str_T *)"123");

wilddog_node_createUString()

定义

Wilddog_Node_T * wilddog_node_createUString(Wilddog_Str_T *key, Wilddog_Str_T *value)

说明

创建一个字符串类型节点。

参数

  • key Wilddog_Str_T* : 节点的key值。

  • value Wilddog_Str_T* : 指向utf-8字符串的指针。

    返回值

Wilddog_Node_T 创建成功则返回节点的指针，失败返回NULL。

示例

  1. Wilddog_Node_T *p_node = wilddog_node_createUString((Wilddog_Str_T *)"this is key",(Wilddog_Str_T *)"this is value");

wilddog_node_createBString()

定义

Wilddog_Node_T * wilddog_node_createBString(Wilddog_Str_T *key, u8 *value, int len)

说明

创建一个二进制数组类型节点。

参数

  • key Wilddog_Str_T* : 节点的key值。
  • value u8* : 二进制数组的指针。

  • len int : 数据的长度(字节)。

    返回值

Wilddog_Node_T* 创建成功则返回节点的指针，失败返回NULL。

示例

  1. u8 data[8] = {0};
  2. ...
  3. Wilddog_Node_T *p_node = wilddog_node_createBString((Wilddog_Str_T *)"this is key", data, 8);

wilddog_node_createFloat()

定义

Wilddog_Node_T * wilddog_node_createFloat(Wilddog_Str_T *key, wFloat num)

说明

创建一个浮点类型的节点。

参数

  • key Wilddog_Str_T * : 节点的key值。

  • num wFloat : 浮点数据(8位机器为32bits, 其他为64bits)。

    返回值

Wilddog_Node_T * 创建成功则返回节点的指针，失败返回NULL。

示例

  1. wFloat data = 1.234;
  2. Wilddog_Node_T *p_node = wilddog_node_createFloat((Wilddog_Str_T *)"this is key", data);

wilddog_node_createNum()

定义

Wilddog_Node_T * wilddog_node_createNum(Wilddog_Str_T *key, s32 num)

说明

创建一个整数类型节点，只支持32位整型。

参数

  • key Wilddog_Str_T* : 节点的key值。

  • num s32 : 32位有符号整数。

    返回值

Wilddog_Node_T 创建成功则返回节点的指针，失败返回NULL。

示例

  1. s32 data = 1;
  2. Wilddog_Node_T *p_node = wilddog_node_createNum((Wilddog_Str_T *)"this is key", data);

wilddog_node_createNull()

定义

Wilddog_Node_T * wilddog_node_createNull(Wilddog_Str_T *key)。

说明

创建一个Null类型节点，对应到JSON中即其值为 null 。

参数

  • key Wilddog_Str_T* : 节点的key值。

    返回值

Wilddog_Node_T 创建成功则返回节点的指针，失败返回NULL。

示例

  1. Wilddog_Node_T *p_node = wilddog_node_createNull((Wilddog_Str_T *)"this is key");

wilddog_node_createTrue()

定义

Wilddog_Node_T * wilddog_node_createTrue(Wilddog_Str_T *key)。

说明

创建一个TRUE类型节点，对应到JSON中即其值为 true。

参数

  • key Wilddog_Str_T* : 节点的key值。

    返回值

Wilddog_Node_T 创建成功则返回节点的指针，失败返回NULL。

示例

  1. Wilddog_Node_T *p_node = wilddog_node_createTrue((Wilddog_Str_T *)"this is key");

wilddog_node_createFalse()

定义

Wilddog_Node_T * wilddog_node_createFalse(Wilddog_Str_T *key)。

说明

创建一个FALSE类型节点，对应到JSON中即其值为 false。

参数

  • key Wilddog_Str_T* : 节点的key值。

    返回值

Wilddog_Node_T 创建成功则返回节点的指针，失败返回NULL。

示例

  1. Wilddog_Node_T *p_node = wilddog_node_createFalse((Wilddog_Str_T *)"this is key");

wilddog_node_addChild()

定义

Wilddog_Return_T wilddog_node_addChild(Wilddog_Node_T *parent, Wilddog_Node_T *child)。

说明

向一个节点添加子节点，成功后，child 节点成为父节点 parent 的子节点，parent 节点可以通过parent->p_wn_child或者parent->p_wn_child->p_wn_next（可能有多次p_wn_next，由 parent 节点的组成决定）的链表顺序查找方式找到。

参数

  • parent Wilddog_Node_T* : 指向父节点的指针，如果父节点不是 Object 类型，会自动转换为 Object 类型，原有的值会丢失。

  • child Wilddog_Node_T* : 指向要添加的子节点的指针。

    返回值

Wilddog_Return_T 成功返回 0, 失败返回 <0的值。

示例

  1. Wilddog_Node_T *p_father = wilddog_node_createObject((Wilddog_Str_T *)"123");
  2. Wilddog_Node_T *p_child = wilddog_node_createFalse((Wilddog_Str_T *)"this is key");
  3. wilddog_node_addChild(p_father, p_child);

wilddog_node_delete()

定义

Wilddog_Return_T wilddog_node_delete( Wilddog_Node_T *head)

说明

删除节点及其所有子节点。

参数

  • head Wilddog_Node_T* : 要删除节点的指针。

    返回值

Wilddog_Return_T 成功返回 0, 失败返回 <0的值。

示例

  1. Wilddog_Node_T *p_father = wilddog_node_createObject((Wilddog_Str_T *)"123");
  2. Wilddog_Node_T *p_child = wilddog_node_createFalse((Wilddog_Str_T *)"this is key");
  3. wilddog_node_addChild(p_father, p_child);
  5. wilddog_node_delete(p_father); //会将 p_father 和子节点 p_child 全部删除

wilddog_node_clone()

定义

Wilddog_Node_T * wilddog_node_clone( Wilddog_Node_T *head)

说明

拷贝当前节点及其下所有子节点。

参数

  • head Wilddog_Node_T* : 指向节点的指针。

    返回值

Wilddog_Node_T 成功返回当前节点副本的指针, 失败返回NULL。

示例

  1. Wilddog_Node_T *p_father = wilddog_node_createObject((Wilddog_Str_T *)"123");
  2. Wilddog_Node_T *p_child = wilddog_node_createFalse((Wilddog_Str_T *)"this is key");
  3. wilddog_node_addChild(p_father, p_child);
  5. Wilddog_Node_T *p_clone = wilddog_node_clone(p_father); //会复制一个一模一样的副本，需要单独调用wilddog_node_delete 释放

wilddog_node_find()

定义

Wilddog_Node_T *wilddog_node_find( Wilddog_Node_T *root, char *path)

说明

root中查找相对路径下的节点。

参数

  • root Wilddog_Node_T* : 指向根节点的指针。

  • path char* : 指向相对路径的指针。

    返回值

Wilddog_Node_T 成功返回节点指针, 失败返回NULL。

示例

  1. Wilddog_Node_T *p_father = wilddog_node_createObject((Wilddog_Str_T *)"123");
  2. Wilddog_Node_T *p_child = wilddog_node_createFalse((Wilddog_Str_T *)"this is key");
  3. wilddog_node_addChild(p_father, p_child);
  5. Wilddog_Node_T *p_find = wilddog_node_find(p_father, "this is key"); //p_find和p_child是同一个节点

wilddog_node_getValue()

定义

Wilddog_Str_T wilddog_node_getValue(Wilddog_Node_T \node, int *len)

说明

获取当前节点的value值，其中，值为true，false，null的节点无法通过这种方式获取，而应该直接根据节点的d_wn_type得出其类型，类型在wildog.h中定义。

参数

  • node Wilddog_Node_T* : 指向节点的指针。

  • len int* : 输出参数，将存储value值的长度(字节)。

    返回值

Wilddog_Node_T 成功返回指向节点value的指针(可根据type和传出的len来转化)，失败返回NULL。

示例

  1. Wilddog_Node_T *p_child = wilddog_node_createNum((Wilddog_Str_T *)"this is key",234);
  2. int len = 0;
  3. s32 value;
  4. Wilddog_Str_T *p_data = wilddog_node_getValue(p_father, &len); //len 应和sizeof(s32)相同
  5. value = (s32)(*p_data);

wilddog_node_setValue()

定义

Wilddog_Return_T (Wilddog_Node_T *node, u8 *value, int len)

说明

设置当前节点的value值,其中，值为true，false，null的节点无法通过这种方式设置，整数类型和浮点类型的节点，len 应该为sizeof(s32)和sizeof(wFloat)。

参数

  • node Wilddog_Node_T* : 指向节点的指针。
  • value u8* : 指向新value值的指针。

  • len int : 新value的长度。

    返回值

Wilddog_Return_T 成功返回 0, 失败返回 <0 的数。

示例

  1. Wilddog_Node_T *p_child = wilddog_node_createNum((Wilddog_Str_T *)"this is key",234);
  2. int len = sizeof(s32);
  3. s32 value = 456;
  4. wilddog_node_setValue(p_father, &value, len);

AuthData (Methods)

wilddog_auth()

定义

Wilddog_Return_T wilddog_auth(Wilddog_Str_T *p_host, u8 *p_auth, int len, onAuthFunc onAuth, void *args)

说明

发送auth数据到服务器进行认证，每个 host 只需要认证一次。

参数

p_host Wilddog_Str_T : 进行auth认证的host字符串，如 "<SyncAppID>.wilddogio.com"。

p_auth u8* : 指向auth数据的指针，auth 数据可以使用其他端 sdk 的 token，或者通过 wilddog token 生成器生成。

int len : auth数据的长度。

onAuthFunc onAuth : 服务端回应认证或者认证超时触发的回调函数，类型是void (*onAuthFunc)(void* arg, Wilddog_Return_T err)，其中arg为用户传递的值，（即下面的args），err为状态码，具体见Wilddog_Return_T定义。

args void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 发送成功返回0，发送失败则返回负数。注意该返回值仅表明发送是否成功，确认是否在云端认证成功需要在回调函数中判断。

示例

  1. void myOnAuthFunc(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_ERR_NOERR || err >= WILDDOG_HTTP_BAD_REQUEST){
  3.         printf("auth fail!\n");
  4.         return;
  5.     }
  6.     printf("auth success! %d\n", *(int*)arg);
  7.     return;
  8. }
  10. //aquired a new auth token
  11. char* newToken="ABCD1234567890";
  13. wilddog_auth("aaa.wilddogio.com", newToken, strlen(newToken), myOnAuthFunc, NULL);
  14. ...

wilddog_unauth()

定义

Wilddog_Return_T wilddog_unauth(Wilddog_Str_T *p_host, onAuthFunc onAuth, void *args)

说明

取消和服务器的auth认证，，每个 host 只需要取消认证一次。

参数

p_host Wilddog_Str_T : 进行auth认证的host字符串，如 "<SyncAppID>.wilddogio.com"。

onAuthFunc onAuth : 服务端回应认证或者认证超时触发的回调函数，类型是void (*onAuthFunc)(void* arg, Wilddog_Return_T err)，其中arg为用户传递的值，（即下面的args），err为状态码，具体见Wilddog_Return_T定义。

args void* : 用户给回调函数传入的参数。

返回值

Wilddog_Return_T 发送成功返回0，发送失败则返回负数。注意该返回值仅表明发送是否成功，是否成功取消认证需要在回调函数中判断。

示例

  1. void myOnAuthFunc(void* arg, Wilddog_Return_T err){
  2.     if(err < WILDDOG_ERR_NOERR || err >= WILDDOG_HTTP_BAD_REQUEST){
  3.         printf("auth fail!\n");
  4.         return;
  5.     }
  6.     printf("hello world! %d\n", (int)arg);
  7.     return;
  8. }
  10. wilddog_unauth("aaa.wilddogio.com", myOnAuthFunc, NULL);
  11. ...