title: 数据修改和同步

和 Wilddog 云端同步的方法。

方法

wilddog_getValue

定义

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

说明

获取当前路径的数据，数据格式为 Wilddog_Node_T (类似 JSON )。

参数

参数名 说明
wilddog Wilddog_T 类型。当前路径对应 Wilddog Sync 实例。
callback onQueryFunc 类型。服务端回应数据或者回应超时触发的回调函数。
arg void 指针类型。可为 NULL，用户给回调函数传入的参数。

返回值

成功返回 0，否则返回对应 错误码，同时会触发回调函数，错误码也能够在回调函数中查询。

示例

  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){
  26.             //打印得到的节点数据
  27.             _wilddog_debug_printnode(p_node);
  28.             ...
  29.             wilddog_node_delete(p_node);
  30.         }
  31.         wilddog_trySync();
  32.     }
  33.     ...
  34.     wilddog_destroy(&wilddog);
  35. }


wilddog_setValue

定义

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

说明

设置当前路径的数据到云端，数据格式为Wilddog_Node_T(类似 JSON )。

参数

参数名 说明
wilddog Wilddog_T 类型。当前路径对应 Wilddog Sync 实例。
p_node Wilddog_Node_T 指针类型。指向当前路径对应 Wilddog_Node_T 节点数据的指针，注意，头节点即为当前路径。
callback onSetFunc 类型。服务端回应数据或者回应超时触发的回调函数。
arg void 指针类型。可为 NULL，用户给回调函数传入的参数。

返回值

成功返回 0，否则返回对应 错误码，同时会触发回调函数，错误码也能够在回调函数中查询。

示例

  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.     return;
  8. }
  9. int main(void){
  10.     Wilddog_T wilddog = 0;
  11.     Wilddog_Node_T * p_node = NULL;
  13.     //创建一个字符串类型节点，值为 123456，key 为 NULL （这个节点的 key 是当前路径的 key，因此无需设置） 
  14.     p_node = wilddog_node_createUString(NULL,"123456");
  16.     //<url>即希望设置数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  17.     wilddog = wilddog_initWithUrl(<url>);
  19.     //注意，这里省略了对wilddog_setValue返回值的检查
  20.     wilddog_setValue(wilddog, p_node, onSetCallback, NULL);
  22.     //数据已经设置到云端，删除刚才建立的节点
  23.     wilddog_node_delete(p_node);
  25.     while(1){
  26.         wilddog_trySync();
  27.     }
  28.     wilddog_destroy(&wilddog);
  29. }


wilddog_push

定义

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

说明

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

参数

参数名 说明
wilddog Wilddog_T 类型。当前节点对应 Wilddog Sync 实例。
p_node Wilddog_Node_T 指针类型。指向当前路径对应 Wilddog_Node_T 节点数据的指针，注意，头节点即为当前路径。
callback onPushFunc 类型。服务端回应数据或者回应超时触发的回调函数。
arg void 指针类型。可为 NULL，用户给回调函数传入的参数。

返回值

成功返回 0，否则返回对应 错误码，同时会触发回调函数，错误码也能够在回调函数中查询。

示例

  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.     return;
  8. }
  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, *p_head = NULL;
  17.     //建立一个object节点，即类似json中的{}
  18.     p_head = wilddog_node_createObject(NULL);
  20.     //建立一个key为2，value为数字1234的节点
  21.     p_node = wilddog_node_createNum("2",1234);
  23.     //将节点p_node添加到object中
  24.     wilddog_node_addChild(p_head, p_node);
  26.     //<url>即希望推送数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  27.     wilddog = wilddog_initWithUrl(<url>);
  29.     //注意，这里省略了对wilddog_push返回值的检查
  30.     wilddog_push(wilddog, p_head, onPushCallback, NULL);
  32.     //数据已经推送，删除刚才建立的节点
  33.     wilddog_node_delete(p_head);
  35.     while(1){
  36.         wilddog_trySync();
  37.     }
  38.     wilddog_destroy(&wilddog);
  39. }


wilddog_removeValue

定义

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

说明

删除当前路径及其子路径下所有数据。

参数

参数名 说明
wilddog Wilddog_T 类型。当前路径对应 Wilddog Sync 实例。
callback onRemoveFunc 类型。服务端回应数据或者回应超时触发的回调函数。
arg void 指针类型。可为 NULL，用户给回调函数传入的参数。

返回值

成功返回 0，否则返回对应 错误码，同时会触发回调函数，错误码也能够在回调函数中查询。

示例

  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.     return;
  8. }
  9. int main(void){
  10.     Wilddog_T wilddog;
  12.     //<url>即希望删除数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  13.     wilddog = wilddog_initWithUrl(<url>);
  15.     //注意，这里省略了对wilddog_removeValue返回值的检查
  16.     wilddog_removeValue(wilddog, onDeleteCallback, NULL);
  18.     while(1){
  19.         wilddog_trySync();
  20.     }
  21.     wilddog_destroy(&wilddog);
  22. }


wilddog_addObserver

定义

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

说明

监听当前路径的数据变化。一旦该数据发生改变, onDataChange 函数将被调用。

参数

参数名 说明
wilddog Wilddog_T 类型。当前路径对应 Wilddog Sync 实例。
event Wilddog_EventType_T类型。监听的事件类型。
callback onRemoveFunc 类型。服务端回应数据或者回应超时触发的回调函数。
arg void 指针类型。可为 NULL，用户给回调函数传入的参数。

返回值

成功返回 0，否则返回对应 错误码，同时会触发回调函数，错误码也能够在回调函数中查询。

示例

  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.     Wilddog_T wilddog = 0;
  11.     STATIC int count = 0;
  13.     //<url>即希望订阅数据的url，如coaps://<SyncAppID>.wilddogio.com/a/b/c
  14.     wilddog = wilddog_initWithUrl(<url>);
  16.     //注意，这里省略了对wilddog_addObserver返回值的检查
  17.     wilddog_addObserver(wilddog, WD_ET_VALUECHANGE, onObserverCallback, NULL);
  19.     while(1){
  20.         wilddog_trySync();
  21.     }
  22.     wilddog_destroy(&wilddog);
  23. }


wilddog_removeObserver

定义

  1. Wilddog_Return_T wilddog_removeObserver(Wilddog_T wilddog, Wilddog_EventType_T event)

说明

取消对当前路径下某个事件的监听（对应于 wilddog_addObserver ）。

参数

参数名 说明
wilddog Wilddog_T 类型。当前路径对应 Wilddog Sync 实例。
event Wilddog_EventType_T 类型。 取消的事件类型。

返回值

成功返回 0，否则返回对应 错误码。

示例

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


wilddog_auth

注意：

  • wilddog_auth 函数需在调用 wilddog_initWithUrl 初始化该 SyncAppID 并获取实例后调用，否则将不生效。

定义

  1. 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 unsigned char 指针类型。指向 auth 数据的指针，auth 数据可以使用其他端 SDK 的 token，或者使用 Server SDK 生成。
len int 类型。auth 数据的长度。
onAuth onAuthFunc 类型。服务端回应认证或者认证超时触发的回调函数。
args void 指针类型。用户给回调函数传入的参数。

返回值

成功返回 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. char* newToken="ABCD1234567890";
  12. wilddog_auth("aaa.wilddogio.com", newToken, strlen(newToken), myOnAuthFunc, NULL);


wilddog_unauth

注意：

  • wilddog_unauth 函数需在调用 wilddog_initWithUrl 初始化该 SyncAppID 并获取实例后调用，否则将不生效。

定义

  1. 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"。
onAuth onAuthFunc 类型。服务端回应认证或者认证超时触发的回调函数。
args void 指针类型。用户给回调函数传入的参数。

返回值

成功返回 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.     return;
  7. }
  9. wilddog_unauth("aaa.wilddogio.com", myOnAuthFunc, NULL);


wilddog_trySync

定义

  1. void wilddog_trySync(void)

说明

和云端维持连接、接收云端数据、管理数据重传，应该在空闲时调用。

示例

  1. int main(){
  2.     //初始化实例，<SyncAppID> 为你的应用ID，路径为/user/jackxy/device/light/10abcde
  3.     Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy/device/light/10abcde");
  4.     //do something
  5.     ...
  6.     while(1){
  7.         wilddog_trySync();
  8.     }
  9. }


wilddog_increaseTime

定义

  1. void wilddog_increaseTime(u32 ms)

说明

用于校准 Wilddog 的时钟(可以在定时器中调用)。wilddog_trySync() 被调用时会自动增加 Wilddog 时钟，但该时间的计算会有偏差，可以通过传入一个时间增量来校准 Wilddog 时钟。

示例

  1. int main(){
  2.     //初始化实例，<SyncAppID> 为你的应用ID，路径为/user/jackxy/device/light/10abcde
  3.     Wilddog_T wilddog=wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/user/jackxy/device/light/10abcde");
  4.     //do something
  5.     ...
  6.     while(1){
  7.         wilddog_trySync();
  8.         //休眠1秒
  9.         sleep(1);
  10.         //给wilddog 时钟增加1秒增量
  11.         wilddog_increaseTime(1000);
  12.     }
  13. }