标题第一行

Size: px

Start display at page:

Download "标题第一行"

簪杉步
5 years ago
Views:

2 修订记录日期修订版本修订内容作者初稿拟制林文良第 2 页共 27 页

3 目录前言 DSTSDK 应用开发手册介绍目的术语约定 DSTSDK 简介 DSTSDK 开发使用环境 DSTSDK 的常量定义 DSTSDK 的类型声明枚举类型复合类型 DSTSDK 事件说明 DSTSDK 的函数声明函数列表函数详细功能 dstsdk_init dstsdk_deinit dstsdk_getevent dstsdk_setlogintimeout dstsdk_setlinkidletime dstsdk_setactivecycle dstsdk_setmaxactive dstsdk_setbufferlen dstsdk_sessionsend dstsdk_getsessionprotocol 第 3 页共 27 页

4 dstsdk_closesession dstsdk_cleansession dstsdk_setsessionidlemode *dstsdk_getsessionterminalid dstsdk_getsessionterminallen dstsdk_setsessionopt *dstsdk_getsessionopt DSTSDK 的示例源程序事件模式轮询模式第 4 页共 27 页

5 前言欢迎您使用巨龙 DTU 系列产品 SDK, 为易于您轻松快捷的掌握巨龙 DTU 系列产品 SDK 的使用, 本手册为您详细介绍巨龙 DTU 系列产品 SDK 的使用本产品由厦门市巨龙软件工程有限公司开发, 手册版权归属厦门市巨龙软件工程有限公司, 禁止任何人擅自将本手册的部分或全部内容复制并用于商业目的, 违者将承担法律责任希望用户阅读本帮助手册, 能全面快速了解巨龙 DTU 系列产品 SDK, 通过短时间的操作能很快的熟悉该 SDK 若您对本手册有任何意见建议或问题, 欢迎您来信或来电, 我们将竭诚为您服务地址 : 厦门市火炬高新区创新二路 1 号邮编 : 电话 : 传真 : support@dragonsoft.com.cn 公司网址 : 第 5 页共 27 页

6 1 DSTSDK 应用开发手册介绍本章主要描述了本手册已经具备的功能和作用, 同时也告诉了读者如何去阅读本手册, 使其作为研发人员使用 SDK 开发的最佳指导文档本章由以下三节组成 : 1. 目的 2. 术语 3. 约定 1.1 目的本操作手册用于指导研发人员基于巨龙物联网数据终端实现快速开发数据中心应用 1.2 术语 APN 接入点名称 DTU 数据终端单元 FLASH 存储芯片 GPRS 移动数据业务 GSM 全球移动通信系统 IP 互联网协议 M2M 终端统一管理平台 POS 销售终端 RTU 远方终端单元 RS232 RX SIM 异步传输标准接口通信接收单元用户标识模块第 6 页共 27 页

7 SMS SRAM TCP TX 短消息业务静态随机存储器传输控制协议通信发送单元 UDP 用户自带寻址信息协议 UIM 用户标识模块 1.3 约定为了方便使用, 快速阅读本操作手册, 在本手册中我们有一些简称图示说明安全警示使用技巧等约定如下 : 约定项释义说明备注 DSTSDK 2 DSTSDK 简介是指巨龙物联网终端系列产品的应用编程接口提示 : 开发需要注意的一些细节出现在第二章节之后的过程中出现在本手册指南第一章之外的说明过程中 DSTSDK 是用于无线数据传输设备 (DTU) 与数据中心 (DSC) 之间进行数据分发的应用编程接口动态库包括了数据中心应用开发所需要的 API 函数, 包括服务的启动服务的停止数据的发送数据的接收参数的配置参数的查询等, 可满足快速开发数据中心应用的需求 3 DSTSDK 开发使用环境 DSTSDK 开发包是以动态链接库的形式发布, 支持 Windows 和 Linux 操作系统 Windows 版本 : 支持 98/2000/2003/XP/WIN7/WIN8, 无需 MFC 库的支第 7 页共 27 页

8 持 ; Linux 版本 : 支持及 3.0 内核, 需要 pthread 库支持 4 DSTSDK 的常量定义常量名常量值注释 MAX_DSTSDK_TERMINALID_LEN 128 字节最大终端长度 DEFAULT_DSTSDK_BUFFER_LEN 4096 字节默认缓冲区长度 DEFAULT_DSTSDK_MAXLINKIDLETIME 30 秒链路超时时间 DEFAULT_DSTSDK_ACTIVECYCLE 5 秒心跳周期数 DEFAULT_DSTSDK_MAXACTIVE 5 秒最大的心跳数 DEFAULT_DSTSDK_LOGINTIMEOUT 30 秒登录超时时间 5 DSTSDK 的类型声明 5.1 枚举类型类型名称类型值注释 DSTSDK_OK = 0 成功 t_dstsdk_result 函数执行结果类型 DSTSDK_INVALID DSTSDK_BUSY DSTSDK_EMPTY, 无效失败遇忙失败空失败第 8 页共 27 页

9 e_dstsdk_listen DSTSDK_ERROR DSTSDK_MAX DSTSDK_LISTEN_TCP 失败未知 TCP 监听 SOCKET 监听类型 e_dstsdk_protocol 协议类型 e_dstsdk_event 事件类型 e_dstsdk_idle 会话空闲类型 DSTSDK_LISTEN_UDP UDP 监听 DSTSDK_PROTOCOL_DTU DTU 协议 DSTSDK_PROTOCOL_M2M M2M 协议 DSTSDK_PROTOCOL_MAX 无效协议 DSTSDK_EVENT_CONNECT 会话连接事件 DSTSDK_EVENT_DISCONN 会话断开事件 DSTSDK_EVENT_READ 会话接收到数据事件 DSTSDK_EVENT_IDLE 会话空闲事件 DSTSDK_EVENT_MAX 会话未知事件 DSTSDK_IDLE_NONE, DSTSDK_IDLE_READ, DSTSDK_IDLE_WRITE, 不触发接收空闲触发发送空闲触发收发空闲都触发 DSTSDK_IDLE_BOTH 5.2 复合类型类型名称类型值注释第 9 页共 27 页

10 应用实例 DSTSDK_HANDLER DSTSDK 句柄会话类型 DSTSDK_SESSION DSTSDK 会话事件处理函数原型, (*t_dstsdk_handler)(dstsdk_session 事件处理函数原型 session, e_dstsdk_event event, unsigned int param1, unsigned int param2) 事件描述 6 DSTSDK 事件说明 struct _dstsdk_event{ DSTSDK_SESSION session; e_dstsdk_event event; unsigned int param1; unsigned int param2; t_dstsdk_event, *p_dstsdk_event; 事件类型 (event) 事件描述终端会话连接事件参数 : session: 会话类型 event: 事件类型 param1: 终端标识地址 param2: 终端标识长度事件描述结构体, 参数 : session: 会话类型 event: 事件类型 param1: 终端标识地址 param2: 终端标识长度 DSTSDK_EVENT_CONNECT DTU 终端连接并登陆完成后触发本事件参数 1 char *, 终端设备号第 10 页共 27 页

11 参数 2 int, 终端设备号长度终端会话断开事件 DTU 主动断开或调用 dstsdk_closesession 主动断开连接触发该事件应用中需要调用 dstsdk_cleansession 函数实现对会话的清除 ; DSTSDK_EVENT_DISCONN 由于 DSTSDK_EVENT_CONNECT 事件在 DTU 登陆完成后才触发, 所以该本事件触发之前可能未触发 DSTSDK_EVENT_CONNECT 事件 DSTSDK_EVENT_READ DSTSDK_EVENT_IDLE 参数 1 参数 2 NULL NULL 终端会话接收到数据事件 SDK 接收到 DTU 发送的数据后触发该事件参数 1 参数 2 char *, 数据缓冲区指针 int, 接收到的数据长度终端会话空闲事件会话创建时, 默认不会触发该事件, 可通过调用 dstsdk_setsessionidlemode 函数配置空闲事件触发模型及触发周期参数 1 NULL 参数 2 NULL 第 11 页共 27 页

12 7 DSTSDK 的函数声明 7.1 函数列表函数名注释 dstsdk_init 初始化应用实例 dstsdk_deinit 销毁应用实例 dstsdk_getevent 读取事件 ( 非阻塞式 ) dstsdk_setlogintimeout 设置登录超时时间 dstsdk_setlinkidletime 设置链路超时时间 dstsdk_setactivecycle 设置心跳周期 dstsdk_setmaxactive 设置最大心跳次数 dstsdk_setbufferlen 设置缓冲区大小 dstsdk_sessionsend 发送数据 dstsdk_getsessionprotocol 获取会话协议类型 dstsdk_closesession 关闭会话 dstsdk_cleansession 清除已关闭的会话 dstsdk_setsessionidlemode 设置会话空闲触发模式 *dstsdk_getsessionterminalid 获取会话的终端标识 dstsdk_getsessionterminallen 获取会话的终端标识第 12 页共 27 页

13 dstsdk_setsessionopt 设置会话的选项 *dstsdk_getsessionopt 获取会话的选项 7.2 函数详细功能 dstsdk_init 功能描述初始化应用实例, 该函数在一个应用中仅需调用一次, 在应用退出时需要调用 dstsdk_deinit 进行销毁输入参数返回值参数名 listentype ip port eventhandler 监听类型注释监听 IP 地址, 值为 NULL 或 " " 为本机所有 IP 监听端口事件处理函数, 非空时为事件处理模型 ; 为空时为轮询模式 ( 即需要通过 dstsdk_getevent 获取事件 ) 失败返回 0, 否则返回实例句柄 extern DSTSDK_HANDLER dstsdk_init(e_dstsdk_socket listentype, const char *ip, int port, t_dstsdk_handler eventhandler); dstsdk_deinit 功能描述第 13 页共 27 页

14 输入参数巨龙物联网应用终端 / 无线数据终端应用开发手册销毁应用实例, 该函数在应用退出时需要调用进行销毁参数名注释 handler 应用句柄返回值无 extern dstsdk_getevent 功能描述 void dstsdk_deinit(dstsdk_handler handler); 读取事件 ( 非阻塞式 ) 输入参数参数名注释 handler 应用句柄 event 事件结构体指针返回值成功返回 DSTSDK_OK extern t_dstsdk_result dstsdk_getevent(dstsdk_handler handler, t_dstsdk_event *event); 第 14 页共 27 页

15 7.2.4 dstsdk_setlogintimeout 功能描述设置登录超时时间输入参数参数名注释 session value 返回值无会话句柄设置值, 单位 : 秒 extern void dstsdk_setlogintimeout(dstsdk_handler handler, int value); dstsdk_setlinkidletime 功能描述设置链路超时时间输入参数参数名 session value 注释会话句柄设置值, 单位 : 秒返回值无第 15 页共 27 页

16 extern value); void dstsdk_setlinkidletime(dstsdk_handler handler, int dstsdk_setactivecycle 功能描述设置心跳周期输入参数参数名 session value 返回值无会话句柄设置值, 单位 : 秒注释 extern void dstsdk_setactivecycle(dstsdk_handler handler, int value); dstsdk_setmaxactive 功能描述设置最大心跳次数输入参数参数名注释 session value 会话句柄设置值, 单位 : 秒第 16 页共 27 页

17 返回值无 extern value); void dstsdk_setmaxactive(dstsdk_handler handler, int dstsdk_setbufferlen 功能描述设置缓冲区大小输入参数参数名注释 session value 返回值无会话句柄设置值, 单位 : 秒 extern void dstsdk_setbufferlen (DSTSDK_HANDLER handler, int value); dstsdk_sessionsend 功能描述输入参数发送数据参数名注释第 17 页共 27 页

18 session data datalen 会话句柄待发送数据数据长度返回值发送的数据长度 extern int dstsdk_sessionsend(dstsdk_session session, const char *data, int datalen); dstsdk_getsessionprotocol 功能描述获取会话协议类型输入参数参数名注释返回 session e_dstsdk_protocol 会话句柄 extern e_dstsdk_protocol dstsdk_getsessionprotocol(dstsdk_session session); dstsdk_closesession 功能描述关闭会话第 18 页共 27 页

19 输入参数参数名注释 session 会话句柄返回值成功返回 DSTSDK_OK extern t_dstsdk_result dstsdk_closesession(dstsdk_session session); dstsdk_cleansession 功能描述清除已关闭的会话, 该函数仅在 DSTSDK_EVENT_DISCONN 事件中调用输入参数参数名 session 会话句柄注释返回值失败返回 0, 否则返回实例句柄 extern t_dstsdk_result dstsdk_cleansession(dstsdk_session session); dstsdk_setsessionidlemode 功能描述设置会话空闲触发模式第 19 页共 27 页

20 输入参数参数名注释 session 会话句柄 idle 空闲模式 second 空闲触发秒数, 最小值为 1 返回值无 extern void dstsdk_setsessionidlemode(dstsdk_session session, e_dstsdk_idle idle, int second); *dstsdk_getsessionterminalid 功能描述获取会话的终端标识输入参数参数名注释 session 会话句柄返回值终端标识指针, 失败返回 NULL extern const char *dstsdk_getsessionterminalid(dstsdk_session session); 第 20 页共 27 页

21 dstsdk_getsessionterminallen 功能描述获取会话的终端标识输入参数参数名注释 session 会话句柄返回值终端标识长度, 无效返回 0 extern int dstsdk_getsessionterminallen(dstsdk_session session); dstsdk_setsessionopt 功能描述设置会话的选项输入参数参数名注释返回值 session opt 会话句柄选项指针无 extern *opt); void dstsdk_setsessionopt(dstsdk_session session, void 第 21 页共 27 页

22 *dstsdk_getsessionopt 功能描述获取会话的选项输入参数参数名 session 会话句柄注释 opt 选项指针返回值成功返回选项指针, 否则返回 NULL extern void *dstsdk_getsessionopt(dstsdk_session session); 8 DSTSDK 的示例源程序 8.1 事件模式 //DSTSDK 事件处理函数 void dstsdk_handler(dstsdk_session session, e_dstsdk_event event, switch (event) { unsigned int param1, unsigned int param2) { case DSTSDK_EVENT_CONNECT:{ // 会话连接事件 char *terminalid = (char *)param1; // 终端编号 int termianallen =param2; // 终端编号长度 // 设置会话空闲触发模式第 22 页共 27 页

23 dstsdk_setsessionidlemode(session, DSTSDK_IDLE_BOTH, 5); // 根据需要执行其它操作 UserStruct *us = new UserStruct(); dstsdk_setsessionopt(session, us); break; case DSTSDK_EVENT_DISCONN: // 会话断开事件 // 清除已关闭的会话 if (dstsdk_getsessionopt(session)!= NULL) { UserStruct *us = NULL; us = (UserStruct *) dstsdk_getsessionopt(session);. free(us); dstsdk_cleansession(session); break; case DSTSDK_EVENT_READ:{ // 接收到数据事件 char *recvdata = (char *)param1; int datalen =param2; UserStruct *us = (UserStruct *) dstsdk_getsessionopt(session); // 对业务数据进行操作 break; case DSTSDK_EVENT_IDLE: { // 会话空闲事件 UserStruct *us = (UserStruct *) dstsdk_getsessionopt(session); // 检测是否有需要下发的业务数据第 23 页共 27 页

24 if (isdeliverdata(us)){ // 下发业务数据 dstsdk_sessionsend(session, "123456\n", strlen("123456\n")); break; default: break; int main(int args, char **argv) { DSTSDK_HANDLER handler; // 初始化并采用事件模式 handler = dstsdk_init(dstsdk_socket_tcp, " ", 1234, dstsdk_handler); if (handler == NULL ) // 初始化失败, 退出应用 return 0; dstsdk_setbufferlen(handler, 4096);// 设置 4K 缓冲区 dstsdk_setlinkidletime(handler, 60);// 设置链路超时时间 60 秒 dstsdk_setmaxactive(handler,5 ); // 设置最大心跳次数 while (1){ Sleep(1); 8.2 轮询模式 int main(int args, char **argv) { DSTSDK_HANDLER handler; 第 24 页共 27 页

25 t_dstsdk_event event; // 初始化并采用轮询模式 handler = dstsdk_init(dstsdk_socket_tcp, " ", 1234, NULL ); if (handler == NULL ) // 初始化失败, 退出应用 return 0; dstsdk_setbufferlen(handler, 4096);// 设置 4K 缓冲区 dstsdk_setlinkidletime(handler, 60);// 设置链路超时时间 60 秒 dstsdk_setmaxactive(handler,5 ); // 设置最大心跳次数 while (handler) { usleep(1); // 读取事件 ( 非阻塞模式 ) if (dstsdk_getevent(handler, &event) == DSTSDK_OK) { switch (event.event) { case DSTSDK_EVENT_CONNECT:{ // 会话连接事件 char *terminalid = (char *) event.param1; // 终端编号 int termianallen = event.param2; // 终端编号长度 // 设置会话空闲触发模式 dstsdk_setsessionidlemode(event.session, DSTSDK_IDLE_BOTH, 5); // 根据需要执行其它操作 UserStruct *us = new UserStruct(); dstsdk_setsessionopt(event.session, us); break; case DSTSDK_EVENT_DISCONN: // 会话断开事件 // 清除已关闭的会话 if (dstsdk_getsessionopt(event.session)!= NULL) { UserStruct *us = NULL; 第 25 页共 27 页

26 us = (UserStruct *) dstsdk_getsessionopt(event.session);. free(us); dstsdk_cleansession(event.session); break; case DSTSDK_EVENT_READ:{ // 接收到数据事件 char *recvdata = (char *) event.param1; int datalen = event.param2; UserStruct *us = (UserStruct *) dstsdk_getsessionopt(event.session); // 对业务数据进行操作 break; case DSTSDK_EVENT_IDLE: { // 会话空闲事件 UserStruct *us = (UserStruct *) dstsdk_getsessionopt(event.session); // 检测是否有需要下发的业务数据 if (isdeliverdata(us)){ // 下发业务数据 dstsdk_sessionsend(event.session, "123456\n", strlen("123456\n")); break; default: break; 第 26 页共 27 页

27 // 销毁应用实例 dstsdk_deinit(handler); puts("!!!hello World!!!"); return EXIT_SUCCESS; 第 27 页共 27 页

CC213

CC213 : (Ken-Yi Lee), E-mail: feis.tw@gmail.com 49 [P.51] C/C++ [P.52] [P.53] [P.55] (int) [P.57] (float/double) [P.58] printf scanf [P.59] [P.61] ( / ) [P.62] (char) [P.65] : +-*/% [P.67] : = [P.68] : ,