title: 离线功能

本篇文档介绍 Wilddog Sync 的高级特性，用于实现更丰富的场景需求。

C/嵌入式 SDK 为每个引用建立长连接，所有该引用的通讯都是基于这个连接。

SDK 内部的实现机制使你的设备在弱网环境下仍能继续工作。它包括离线事件、监控连接状态等特性。

监听连接状态

/.info/connected 是 Wilddog Sync 提供的一个保留路径，用于存储客户端与云端的连接状态。

注意：

SDK 初始化时，处于离线状态。此外，/.info/connected 的值是 boolean 类型。

例如，监测客户端是否连接到云端：

  1. STATIC void on_callback
  2.     (
  3.     const Wilddog_Node_T* p_snapshot, 
  4.     void* arg, 
  5.     Wilddog_Return_T err
  6.     ){
  7.     if(err < WILDDOG_HTTP_OK || err >= WILDDOG_HTTP_NOT_MODIFIED){
  8.         wilddog_debug("getValue fail!");
  9.         return;
  10.     }
  12.     if(p_snapshot){
  13.         if(p_snapshot->d_wn_type == WILDDOG_NODE_TYPE_TRUE){
  14.             wilddog_debug("online!");
  15.         }else if(p_snapshot->d_wn_type == WILDDOG_NODE_TYPE_FALSE){
  16.             wilddog_debug("offline!");
  17.         }
  18.     }
  19.     return;
  20. }
  22. int main(){
  23.     Wilddog_T wilddog = wilddog_initWithUrl("coap://<SyncAppID>.wilddogio.com/.info/connected");
  25.     wilddog_addObserver(wilddog,WD_ET_VALUECHANGE, on_callback, NULL);
  26.     while(1){
  27.         wilddog_trySync();
  28.     }
  29.     return 0;
  30. }

离线事件

离线事件是云端与客户端断开连接时自动触发的事件。

断开连接包括客户端主动断开连接，或者意外的网络中断。触发事件即执行特定的数据操作，它支持离线写入，更新和删除数据方法：

方法 说明
wilddog_onDisconnectSetValue() 当客户端离线时，对当前节点执行写操作。
wilddog_onDisconnectPush() 当客户端离线时，在当前节点下新增一个子节点，子节点的 key 由云端生成。
wilddog_onDisconnectRemoveValue() 当客户端离线时，删除当前节点的数据。
wilddog_cancelDisconnectOperations() 取消之前所设置的离线事件。

注意：

客户端若没有调用 wilddog_goOffline()，直接关机或者断网，离线事件的触发有 3 分钟的延迟。

例如，当用户的网络连接中断时，使用wilddog_onDisconnectSetValue() 方法，记录这个用户已经离线：

  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.     return;
  8. }
  9. int main(void){
  10.     Wilddog_T wilddog = 0;
  11.     Wilddog_Node_T * p_node = NULL;
  13.     //本地组装节点 "disconnect"，当离线时设置为 "yes"
  14.     p_node = wilddog_node_createUString(NULL,"yes");
  16.     //<SyncAppID>即你应用的 SyncAppID，"/disconnect" 为节点的路径
  17.     wilddog = wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com/disconnect");
  19.     //注意，这里省略了对wilddog_onDisconnectSetValue返回值的检查
  20.     wilddog_onDisconnectSetValue(wilddog, p_node, onSetCallback, NULL);
  21.     wilddog_node_delete(p_node);
  23.     while(1){
  24.         wilddog_trySync();
  25.     }
  26.     wilddog_destroy(&wilddog);
  27. }

手动建立或断开连接

wilddog_goOffline()，wilddog_goOnline() 方法用于手动建立连接和断开连接。

例如：

  1. int main(void){
  2.     //计数器，自加到1000 主动断线。
  3.     int cnt = 0;
  4.     Wilddog_T wilddog = 0;
  6.     //<SyncAppID>即你应用的 SyncAppID
  7.     wilddog = wilddog_initWithUrl("coaps://<SyncAppID>.wilddogio.com");
  9.     wilddog_goOnline();
  10.     while(1){
  11.         if(++cnt > 1000){
  12.             wilddog_goOffline();
  13.             break;
  14.         }
  15.         wilddog_trySync();
  16.     }
  17.     wilddog_destroy(&wilddog);
  18. }

注意：

一个应用可以创建多个 Wilddog Sync 实例，但多个实例只会复用同一个长连接。 并且 wilddog_goOffline() 和 wilddog_goOnline() 方法会控制全局的在线和离线。

离线功能的实现机制

客户端会周期的向云端发一个心跳包，云端用此检测与客户端的连接是否正常。心跳包发送的周期由 SDK 根据当前网络状况计算。

当前网络状况的探测和心跳包的发送是在 wilddog_trySync() 中实现的，在程序空闲时务必频繁调用，如下：

  1.     while(1){
  2.         wilddog_trySync();
  3.     }

一些异常情况，如程序崩溃、断电、手机没有信号等导致客户端断开连接，云端只能等到心跳超时后才确定客户端已经离线。由于云端心跳包的超时时间为 3 分钟，因而离线事件的执行在这些异常情况下会有 3 分钟的延迟。

另一方面，客户端网络恢复正常后，会自动尝试与云端建连，一旦成功，之前设置的监听仍然有效。