客户端API

概述

DPS是自包含服务，不需要额外的开发和编译，SDK含预编译客户端可与安全运营中心互动消息和控制。此外，SDK依然提供客户端API使设备应用将自有上云通分享给DPS使用，无需另外建立网络连接。

客户端API有两种集成方法，C版本API和C++版本API。基础C版本API让DPS复用应用上云通道；C++版本API则抽象化DPS的接入方式，使其他应用能模仿DPS与应用对接，分享上云通道。

C版本API

C版本API架构图如下所示。

C版本API让DPS服务复用上云通道，上云通道为具备有和服务器连接能力的协议。C版本API可参考的SDK文件如下。

• include/dps_core.h：列出应用对接DPS所需接口。
• example/client-sample/main.c：使用dps_core.h配合Linkkit MQTT上云完成的应用范例。

应用透过dps_init初始化与DPS服务的通讯句柄。

void* dps_init(const char *product_key, const char *device_key);

应用透过dps_connection注册消息处理器，此处理器当DPS消息到来时被调用，您可在处理器中将DPS消息发送往服务器，或者存到队列等待后续发送。

typedef bool (*pub_handle)(const char *, const char *, int , void *);

void dps_connection(void *session, pub_handle pub_topic, void *context);

当您确认上云通道一切就绪时，即可透过dps_on_connected告知DPS，此时DPS服务即可使用此通道将消息发往服务器端，抵达安全运营中心。

bool dps_on_connected( void *session);

当您发现有来自安全运营中心的消息，即可透过dps_on_message直接将消息传送给DPS服务。

bool dps_on_message( void *session, const char *message, int length);

终止服务。

void dps_final(void *session)

C++版本API

C++版本API使各种应用能模仿DPS与应用对接的方式，共同分享上云通道。

C++版本API可参考的SDK文件如下。

• include/DPSClient.h：以下做说明。
• example/cloud-agent/*：使用 DPSClient.h 配合 Linkkit MQTT 上云完成的应用范例。

DPSConnection类：

DPS用来上云的消息通道抽象接口。应用需要继承并实现此接口，使DPS客户端可以复用应用的上云通道。

enum DPSConnectionStatus
{
  DPS_CONNECTION_DISCONNECTED = 0,
  DPS_CONNECTION_CONNECTED,
};

class DPSConnectionClient
{
public:
  virtual ~DPSConnectionClient();

  virtual bool onMessage( const char *message, int length) = 0;
  virtual bool onConnectionStatus(  DPSConnectionStatus status) = 0;
};

class DPSConnection
{
public:
    virtual ~DPSConnection();

    virtual bool subscribe(const char * topic) = 0;
    virtual bool publish(const char *topic, const char *event, int length) = 0;
};

DPSClient类：

应用和DPS客户端交互的接口。

class DPSClient : public DPSConnectionClient
{
public:
  DPSClient( const char *product_key, const char *device_key);

  static DPSClient *create(const char *product_key, const char * device_name);

  /* DPSConnectionClient implements */
  bool onMessage( const char *message, int length);
  bool onConnectionStatus( DPSConnectionStatus satus);
};

代码示例如下所示。

• AppSampleConnection.h

  #include "DPSClient.h"
  class AppSampleConnection : public DPSConnection {
  public:
    AppSampleConnection( DPSClient *client);
  
    bool subscribe(const char * topic);
    bool publish(const char *topic, const char *event, int length);
  
  private:
    DPSClient *mClient;
    enum ConnectionState {
      CONNECTED,
      CLOSED,
    } mState;
    ...
  };

• AppSampleConnection.cpp

  #include "AppSampleConnection.h"
  /**
   * DPS publishs events to the cloud.
   * /
  bool AppSampleConnection::subscribe(const char *topic)
  {
  ...
  }
  
  /**
   * DPS subscribes a event topic.
   * /
  bool AppSampleConnection::publish(const char *topic, const char *event, int length)
  {
  ...
  }

1. 创建DPSClient实例，并开始服务。

   #include "DPSClient.h"
   const char *product_key = "sample";
   const char *device_name = "test-1";
   DPSClient *client = DPSClient.create(product_key, device_name);
   
   AppSampleConnection *connection = new AppSampleConnection(client);
   client.start( connection);
   
   // MQTT messaging loop
   ...

2. 分发处理DPS消息。

   char message[DPS_MESSAGE_MAX_LENGTH];
   ...
   // Application received a new message with length
   ...
   mClient->onMessage(message, length);