TongLINKQ8.1客户端使用手册

《TongLINKQ8.1客户端使用手册》由会员分享，可在线阅读，更多相关《TongLINKQ8.1客户端使用手册（42页珍藏版）》请在金锄头文库上搜索。

1、 TongTech TongLINK/Q8.1 客户端使用客户端使用手册手册 2011 年 5 月 TongLINK/Q V8.1 客户端使用手册 北京东方通科技股份有限公司 地址：北京市海淀区彩和坊路 10 号 1+1 大厦 2、3 层 客户服务热线：400-650-7088 Email： 版权声明 版权版权 2006-2016 东方通科技版权所有。 版权保护说明版权保护说明 未经东方通科技公司书面许可，本文档不得整体或部分地复印、复制、翻译或缩减成任 何电子介质或计算机可以阅读的格式。本文档中的信息可能不加通知进行修改。 商标商标 2006-2016 东方通科技版权所有。、TongTech

2、、TongLINK、TongLINK/Q、 TongIntegrator、TongSEC、TongWeb、TongEASY、TongWorkflow 是东方通科技的注册商标。 其他所有的公司和产品名称可能为第三方所有。 前言 本手册主要介绍客户端有关概述、TLQ系统UNIX安装、TLQ系统Windows安装、TLQ的客户端目录结构、TLQ的客户端参数配置、客户端代理操作、连接上下文参数设计、客户端应用程序编写、客户端应用程序编译、通讯安全、系统日志等。 1. 阅读对象阅读对象 本手册面向消息中间件TongLINKQ8.1产品用户以及对消息中间件感兴趣的读者。 2.2. 手册约定手册约定 本手册

3、遵循以下约定： 手册中所有的队列控制单元简称为QCU。 手册中所有的消息中间件TongLINK/Q8.1简称为TLQ。 此手册适用于UNIX Tlq_InitConnContext( connContext.BrokerId=1; 2 第二种 TLQCONNCONTEXT connContext; Tlq_InitConnContext( connContext.BrokerId=-1; strcpy(connContext. HostName,”193.9.200.3”); connContext. ListenPort=10240; 第 9 章 客户端应用程序编写 22 第第9章章 客户端

4、客户端应用程序编写应用程序编写 9.1 客户端客户端应用程序编写概述应用程序编写概述 客户端应用必须首先连接到 Server 端的客户端代理上。打开相关的队列控制单元后；进行消息相 关的操作，如发送消息、接收消息等；消息操作完毕后，需要关闭队列控制单元；最后客户端应用必须 断开跟客户端代理的连接。 9.1.1 Client 端应用程序流程端应用程序流程 打开队列控制单元消息相关操作关闭队列控制单元断开与客户端的连接连接到客户端代理图 9-1 程序模板如下：程序模板如下： Tlq_InitConnContext(); /*设置连接上下文的各个域*/ Tlq_SetConnContext()/*设

5、置连接上下文*/ Tlq_Conn()/*连接到客户端代理*/ Tlq_OpenQCU()/*打开队列控制单元*/ . 消息相关处理 . Tlq_CloseQCU()/*关闭队列控制单元*/ Tlq_DisConn()/*断开与客户端的连接*/ 第 9 章 客户端应用程序编写 23 9.1.2 程序总体架构程序总体架构 设置连接上下文：设置连接上下文： 仅对客户端应用有效。 在连接建立之前，必须为连接的建立设置上下文，以指明连接的相关属性。首先调用 Tlq_InitConnContext 对连接上下文进行，然后可以根据实际情况对其中的某些域进行重新赋值，最后调 用设置上下文设置函数 Tlq_S

6、etConnContext 使上下文生效。 程序开始：程序开始： 任何一个应用程序开始时，必须调用连接函数 Tlq_Conn： int Tlq_Conn(TLQ_ID *gid,TLQError *err); 返回0 则连接失败，无法进行后面的操作；只有返回 0（成功） ，后面的操作才能进行，才能开始 会话操作。 程序结束：程序结束： 在应用程序结束时，必须调用断开连接函数 Tlq_DisConn： int Tlq_DisConn(TLQ_ID *gid,TLQError *err); 返回值0，则表示断开连接失败，需要用户手动去检查错误信息返回以发现失败的原因；返回 0 （成功） ，表示一个

7、应用正常结束。 在断开连接之前，应该关闭所有打开状态的会话。 实例开始：实例开始： 应用连接成功后，可以开始一个实例，即打开队列控制单元 Tlq_OpenQCU。所有消息相关的操作 必须限制在实例范围内。开始会话时，需要提供相关队列控制单元的名字。 只有队列控制单元打开成功才能进行后面的消息操作，如果失败，则不能进行消息操作。 int Tlq_OpenQCU(TLQ_ID *gid,TLQ_QCUHDL *qcuHandle,char *QCUName,TLQError *err); 消息处理：消息处理： 可以进行消息相关的操作。 实例结束：实例结束： 消息操作结束后，应该结束实例，即关闭队列

8、控制单元 Tlq_CloseQCU。 int Tlq_CloseQCU(TLQ_ID *gid,TLQ_QCUHDL *qcuHandle,TLQError *err); 9.1.3 程序编程特别说明程序编程特别说明 一个应用中可以有多个实例。 一个瘦客户端应用打开的队列控制单元只能为同一个， 即所连接 的客户端代理所属的队列控制单元。 一个应用中，如果有多个实例存在，则各个函数所使用的 QCU 句柄，即打开队列控制单元的 第二个变量 qcuHandle 必须声明为不同的变量，如果多个实例使用同一个 QCU 句柄，则可能 造成不可预知的问题。 9.1.4 编程模式编程模式 TLQ 支持多种程序

9、模式，Client 端应用支持的模式少于 Server 端应用支持的模式。模式类型如下： 第 9 章 客户端应用程序编写 24 1 普通方式普通方式 main() Tlq_SetConnContext( /*设置连接上下文的各个域*/ Tlq_SetConnContext();/*设置连接上下文*/ Tlq_Conn();/*连接到客户端代理*/ Tlq_OpenQCU();/*打开队列控制单元*/ . Tlq_Retransfer();/*客户端文件消息的断点续传*/ . Tlq_CloseQCU();/*关闭队列控制单元*/ Tlq_DisConn();/*断开与客户端的连接*/ 9.2.

10、2 流程流程说明说明 在连接建立前，必须调用 Tlq_SetConnContext 设置上次被打断的连接标识 ConnId； 调用续传函数进行续传。 第 9 章 客户端应用程序编写 26 【提示提示】 若想在消息传输被打断后能够续传，则最初发送时必须使用 ConnId 作为此次连接的标识。9.2.3 代码举例代码举例 TLQCONNCONTEXT cliinfo; Tlq_InitConnContext( strcpy(cliinfo. ConnId,”12345”); Tlq_SetConnContext( /*建立跟 server 的连接，打开队列控制单元*/ . /*续传*/ ret=T

11、lq_Retransfer（ if(ret0) /*error handle*/ else /*message handle */ 9.2.4 特别说明特别说明 1. 客户端标识 ConnId： 1) 要支持消息的续传，消息在传输前必须指定 ConnId，否则不能续传。 2) 续传文件时，必须指明上次故障的客户端标识 ConnId。 3) 续传和不续传两种模式不能穿插使用，一次只能使用续传或不续传。 4) 以 ConnId 是否为空来判断 PutMsg/GetMsg 是否需要续传。 5) 客户端进行文件消息续传功能时，不能对一个 ConnId 做 Tlq_PutMsg 或 Tlq_GetMsg

12、 并发 操作，如并发会导致历史文件被覆盖。 6) 若一个应用实例在没有退出之前，又启动一个使用相同 ConnId 的应用实例，则客户端代 理拒绝后来的连接要求，API 返回错误信息。 7) 若系统恢复后，对于某个 ConnId 有未完成的文件传输，在被续传之前有一个应用实例使 用此 ConnId 做新的消息传输，则会将历史文件中的历史记录覆盖重写，造成未完成文件 无法续传。 8) 对于同一个客户端代理的多个不同客户端或同一个客户端下的多个应用实例，必须保证 ConnId 瞬时唯一性，一个 ConnId 对应一个瘦客户端历史文件；若想使用同一个 ConnId， 则就不要同时运行。 2. 不支持自

13、定义属性长度不能超过 1K。 3. 客户端与服务端进行文件接收消息时，为了安全接收消息，建议接收消息调用 Tlq_GetMsg（） 函数时，使用手动模式 TLQACK_USER 接收消息。 第 9 章 客户端应用程序编写 27 4. 续传的客户端 Tlq_Retransfer()时，若没有找到相应的历史文件，则报错退出；若发现 ConnId 对应的历史文件，则复用该历史文件。续传过程中，若有文件消息未续传完成，则历史文件保 留，报错退出，下次还可以调用此接口；若有文件消息续传完成，则历史文件清空。 5. 支持本地队列、远程队列和发送队列的续传，不支持集群队列的续传。 第 10 章 客户端应用程

14、序编译 28 第第10章章 客户端客户端应用应用程序编译程序编译 10.1 头文件头文件 Client 端应用所使用的头文件有 tlq_api.h，在使用 C 编写应用时必须包含此文件。 代码举例：代码举例： include “tlq_api.h” #include “tlq_error.h” 10.2 编译选项编译选项 编译客户端应用时，必须使用编译选项 T_CLI。 10.3 Windows 系统下的系统编译系统下的系统编译 客户端应用编译时连接的动态库名为 tl_tcapi.dll，连接的函数库名为 tl_tcapi.lib。 10.4 Unix 系统下的系统编译系统下的系统编译 编译时

15、必须指明头文件的路径以及所连接的函数库；系统安装后，如果没有人为改动，则头文件的 路径应该为$(TLQHOMEDIR)/incl，函数库的路径应该为$(TLQHOMEDIR)/lib。 Makefile 举例如下： all: sendmsg_cli sendmsg_cli: sendmsg_cli.c cc -o sendmsg_cli sendmsg_cli.c I$(TLQHOMEDIR)/incl -L$(TLQHOMEDIR)/lib ltl_tcapi 第 11 章 通讯安全 29 第第11章章 通讯安全通讯安全 客户端应用跟客户端代理之间的通讯安全，TLQ 提供了三种机制。即操作系

16、统级认证、安全出口 和 SSL。 11.1 操作系统级认证操作系统级认证 客户端以用户名和口令登录，此用户名和口令是由代理方的配置决定。客户端与代理建立连接时， 通过代理端有效验证客户端登录的用户名和口令是否正确，若不正确，则代理拒绝连接请求。 采用操作系统级认证的好处就是通过用户名和口令保证网络上的安全性。 11.2 安全出口安全出口 若一个客户端应用使用安全出口进行连接的认证或数据的加解密， 则必须提供客户端连接标识， 即 在连接到代理之前，必须设置此连接的连接标识。 根据用户自已的需要来选择客户端标识设置条件。即客户端的连接标识可以在配置文件中进行设 置，也可以在客户端应用中进行设置。 可以通过第三方的安全出口实现第三方的安全，包括连接建立、网络传输和消息。 可以使用客户端连接标识 ConnId 来分别使用不同的出口模式，如果不指定，则使用缺省的出口模 式 11.3 SSL 的使用的使用 11.3.1 启用启用 SSL 时的相关时的相关配置配