C++ API接口

  • ZSMQ系列文档――API编程手册 For C++
    C++ API编程手册
    (C++语言)
    -- ZSMQ系列文档 --
    ZSMQ系列文档――API编程手册 For C++
     
    目 录
    一章 ZSMQ API FOR C++ 概述
    1.1. ZSMQ API FOR C++ 编译器
    1.2. ZSMQ API FOR C++ 编程步骤
    二章ZSMQ API FOR C++ 函数参考
    2.1. CONNECTZSMQ(连接交换管理平台)
    2.2. DISCONNECTZSMQ(断开与交换管理平台的连接)
    2.3. ZSMQGETLASTERROR(取得错误描述信息).
    2.4. ZSMQGETERRORTYPECODE(取得错误类型码)
    2.5. ZSMQGETERRORREASONCODE(取得错误原因代码)
    2.6. COMMIT(提交操作).
    2.7. ROLLBACK(回滚操作)
    2.8. DTCOMMIT(二次提交)
    2.9. SENDBUFFER(发送内存缓冲).
    2.10. SENDFILE(发送文件)
    2.11. GETFILE(收取文件).
    2.12. CREATEMESSAGE(建立消息)
    2.13. GETMESSAGEINTERFACE(取得消息).
    2.14. DESTORYMESSAGEINTERFACE (销毁消息接口)
    2.15. DELETEMESSAGE(删除消息)
    2.16. LOCKQUEUE(锁队列)..
    2.17. UNLOCKQUEUE(解锁队列)
    2.18. GETQUEUECOUNT(取得队列数量)
    2.19. GETQUEUENAME(取得队列的名称).
    2.20. GETQUEUEDATATYPECOUNT(取得队列中数据类型的数量)
    2.21. GETQUEUEDATATYPENAME(取得数据类型的名称).
    2.22. GETQUEUEDEPTH(取得队列的深度)
    2.23. GETMESSAGELENGTH(取得消息长度)
    2.24. GETREMAINMESSAGELENGTH(取得剩余消息长度).
    2.25. GETDATAFROMMESSAGE(从消息中取得数据) 20
    2.26. WRITEDATAFROMMESSAGE(在消息中写入数据)..
    2.27. SEEKMESSAGE(在消息中移动指针).
    三章ZSMQ API FOR C++ 例子程序.
    3.1. SENDTEST(文件发送
    3.2. RCVTEST(接收文件).
    3.3. DELETETEST(删除消息)
    3.4. BROWSETEST(浏览队列)
    附录:ZSMQ 代码信息参考
    4.1. 错误类型参考
    4.2. 错误原因参考
    ZSMQ系列文档――API编程手册 For C++

    一章 ZSMQ API FOR C++ 概述
    1.1. ZSMQ API FOR C++ 编译器
    ZSMQ API FOR C++ 支持VC60、VC7.0、VC7.1、G++ 等常用的C++编译器,
    通过加载动态库的方式可以支持任意C++编译器如Xlc、Borland C++等。
    1.2. ZSMQ API FOR C++ 编程步骤
    1. 包含头文件#include “ZSMQapi.h”
    2. 调用函数ConnectZSMQ 得到数据交换管理平台接口IZSMQInterface
    3. 使用接口IZSMQInterface 提供的方法进行操作,如发送文件、接收文件、
    提交操作、回滚操作等。当调用的方法返回失败的时候,可以调用
    ZSMQGetLastError 函数查看错误信息、调用ZSMQGetErrorTypeCode
    函数查看错误类型、调用ZSMQGetErrorReasonCode函数查看错误原
    因代码。
    4. 最后调用DisConnectZSMQ 关闭与数据交换管理平台之间的连接通道,
    并释放相关资源。
    ZSMQ系列文档――API编程手册 For C++

    二章ZSMQ API FOR C++ 函数参考
    2.1. ConnectZSMQ(连接交换管理平台)
    函数说明:ConnectZSMQ() 用来连接交换管理平台,在客户端与服务器之间建立
    连接通道,如果成功返回IZSMQInterface 接口,以后对平台的所有操作均通过
    IZSMQInterface接口完成;如果失败函数返回NULL,可以调用ZSMQGetLastError
    查看错误信息、调用ZSMQGetErrorTypeCode 查看错误类型、调用
    ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:const char* szQueueManagerName 队列管理器名称
    unsigned short usListenerPort 队列服务监听端口
    输出参数:函数本身输出IZSMQInterface接口
    备注信息:szQueueManagerName 输入NULL 表示连接缺省队列管理器,
    usListenerPort输入0表示连接默认的监听端口
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    if (!pZSMQI)
    {
    printf("连接ZSMQ失败{错误描述%s} ",ZSMQGetLastError());
    printf("错误类型码[%d] 错误码
    [%d] ",ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    return -1;
    }
    else
    {
    printf(“连接ZSMQ成功 ”);
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    2.2. DisConnectZSMQ(断开与交换管理平台的连接)
    函数说明:DisConnectZSMQ() 用来断开与交换管理平台之间的连接,并释放所
    有申请的内存。
    输入参数:pZSMQInterface IZSMQInterface接口
    输出参数:无
    备注信息:无
    例子程序: 参考2.1的例子程序
    ZSMQ系列文档――API编程手册 For C++

    2.3. ZSMQGetLastError(取得错误描述信息)
    函数说明:ZSMQGetLastError() 用来取得错误的描述信息,当调用API中任意一
    个函数失败后,均可以通过这个函数取得错误的描述信息。
    输入参数:无
    输出参数:函数本身返回const char* 指向错误的描述信息
    备注信息:无
    例子程序: 参考2.2.1的例子程序
    2.4. ZSMQGetErrorTypeCode(取得错误类型码)
    函数说明:ZSMQGetErrorTypeCode() 用来取得错误的类型码,当调用API中任
    意一个函数失败后,均可以通过这个函数取得错误的类型码,来确定下一步应用
    程序如何进行处理。
    输入参数:无
    输出参数:函数本身返回const long 为错误类型码
    备注信息:错误类型码 0 表示没有错误
    错误类型码10000表示函数调用的时候输入的参数出现错误
    错误类型码20000表示服务器返回错误,需查看错误原因码
    错误类型码40000表示磁盘IO方面出现错误
    错误类型码80000表示与服务器连接方面出现错误
    例子程序: 参考2.1的例子程序
    2.5. ZSMQGetErrorReasonCode(取得错误原因代码)
    函数说明:ZSMQGetErrorReasonCode() 用来取得错误的原因代码,当调用API
    中任意一个函数失败后,均可以通过这个函数取得错误的原因代码。
    输入参数:无
    输出参数:函数本身返回const long 为错误原因代码
    备注信息:请参考本文档中ZSMQ代码信息参考章节获得详细的信息
    例子程序: 参考2.1的例子程序
    ZSMQ系列文档――API编程手册 For C++
     5
    2.6. Commit(提交操作)
    函数说明:Commit() 用来提交操作,当进行消息操作(取出、建立)时,需要
    要进行提交才能真正的生效。成功返回true,如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:无
    输出参数:函数本身返回函数的执行结果
    备注信息:支持无限级提交
    例子程序: 无
    2.7. Rollback(回滚操作)
    函数说明:Rollback() 用来回滚操作,当进行消息操作(取出、建立)时,为了
    保证事务的一致性可以通过回滚来撤销之前的所有操作。成功返回true,如果失
    败函数返回false,可以调用ZSMQGetLastError 查看错误信息、调用
    ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode 查看
    错误原因代码。
    输入参数:无
    输出参数:函数本身返回函数的执行结果
    备注信息:支持无限级回滚,注意当客户端断开与服务器的连接时,所有未提交
    的操作会被自动回滚。
    例子程序: 无
    2.8. DTCommit(二次提交)
    函数说明:DTCommit() 用来提交操作,DTCommit与Commit的功能相同,当
    进行消息操作(取出、建立)时,需要要进行提交才能真正的生效。DTCommit
    支持二次提交操作,应用程序将提交的回调函数传入DTCommit,DTCommit
    在内部调用回调函数进行应用层的提交,并保证两个事务的一致性。成功返回
    true,如果失败函数返回false,可以调用ZSMQGetLastError查看错误信息、调用
    ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode 查看
    错误原因代码。
    输入参数:int(*)()
    输出参数:函数本身返回函数的执行结果
    备注信息:支持无限级提交
    例子程序: 无
    ZSMQ系列文档――API编程手册 For C++
     6
    2.9. SendBuffer(发送内存缓冲)
    函数说明:SendBuffer() 通过IZSMQInterface接口进行调用,作用是向交换管理
    平台发送一段缓冲,成功返回true,如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szTargetID 目的地地址
    usTargetIDCount 目的地地址个数
    szTargetQueueName 目的地接收队列名称
    szDataType 数据类型
    cPriority 优先级别 0 ~ 9
    cEncrypt 加密算法 0 为没有加密 保留字段
    cCompress 压缩算法 0 为没有压缩 保留字段
    cSendType 发送类型 0 保留字段
    cReply 是否回执 保留字段
    ulTimeOut 超时时间 0 为吮昙俏扌?单位秒
    pBuffer 要发送的缓存
    ulBufferLen 缓存的大小
    szDataQueueName 数据队列名称
    输出参数:函数输出发送内存缓冲的结果
    备注信息:每个目的地长度的最大值为10个字节,当有多个目的地地址的时候
    目的地地址之间用’’分割,数据类型最大长度为10个字节。
    szTargetQueueName 目的地接收队列的名称,输入0或者””表示默

    cEncrypt、cCompress、cSendType、cReply 为保留字段,在传输
    过程中全程保留输入的值,应用程序可以根据需要自行填写。
    ulTimeOut 为超时时间单位是秒,输入0表示这个数据不会因为超时
    而被数据交换平台抛弃,存活时间的算法从建立消息开始计时,超过
    存活时间,消息会被交换平台删除,且这种删除是不可恢复的。
    数据队列名称表示这段buffer发向哪一个队列,输入0表示默认的发
    送队列,输入其他队列的名称会被放置到相应的队列中,注意只有发
    送队列中的数据才能够别交换管理平台发送走。
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    if (!pZSMQI)
    {
    printf(“连接ZSMQ失败{错误描述%s} ”,ZSMQGetLastError());
    printf(“错误类型码[%d] 错误码
    [%d] ”,ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    return -1;
    }
    else
    {
    ZSMQ系列文档――API编程手册 For C++
     7
    printf(“连接ZSMQ成功 ”);
    }
    if (!pZSMQI-> SendBufferToPlat(“targetid”,//目的地
    1,//目的地地址个数
    “”,//目的地队列
    “datatype”,//数据类型
    5,//优先级别(0~9)
    0,0,0,0,//4个保留字段
    0,//超时时间 0为永远不超时
    “Hello World!”,//Buffer
    Sizeof(“Hello World!”)+1,//BufferLen
    0))//发送到默认队列中
    {
    printf(“发送Buffer失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    else
    {
    if (!pZSMQI->Commit())//平台支持多级事务,如数据库类似发送一段buffer后需要调用Commit
    {
    printf(“提交操作失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    printf(“发送Buffer成功! ”);
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    ZSMQ系列文档――API编程手册 For C++
     8
    2.10. SendFile(发送文件)
    函数说明:SendFile() 通过IZSMQInterface接口进行调用,作用是向交换管理平
    台发送一个文件,成功返回true,如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szTargetID 目的地
    usTargetIDCount 目的地地址个数
    szTargetQueueName 目的地接收队列名称
    szDataType 数据类型
    cPriority 优先级别 0 ~ 9
    cEncrypt 加密算法 0 为没有加密 保留字段
    cCompress 压缩算法 0 为没有压缩 保留字段
    cSendType 发送类型 0 保留字段
    cReply 是否回执 保留字段
    ulTimeOut 超时时间 0 为此标记无效 单位秒
    szFileDir 发送文件所在的目录
    szFileName 发送文件的名称
    szDataQueueName 数据队列名称
    输出参数:函数输出发文件的结果
    备注信息:每个目的地长度的最大值为10个字节,当有多个目的地地址的时候
    目的地地址之间用’’分割,数据类型最大长度为10个字节。
    szTargetQueueName 目的地接收队列的名称,输入0或者””表示默

    cEncrypt、cCompress、cSendType、cReply 为保留字段,在传输
    过程中全程保留输入的值,应用程序可以根据需要自行填写。
    ulTimeOut 为超时时间单位是秒,输入0表示这个数据不会因为超时
    而被数据交换平台抛弃,存活时间的算法从建立消息开始计时,超过
    存活时间,消息会被交换平台删除,且这种删除是不可恢复的。数据
    队列名称表示文件发向哪一个队列,输入0表示默认的发送队列,输
    入其他队列的名称会被放置到相应的队列中,注意只有发送队列中的
    数据才能够别交换管理平台发送走,发送文件名称的最大长度为75
    字节。
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    if (!pZSMQI)
    {
    printf(“连接ZSMQ失败{错误描述%s} ”,ZSMQGetLastError());
    printf(“错误类型码[%d] 错误码
    [%d] ”,ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    return -1;
    }
    ZSMQ系列文档――API编程手册 For C++
     9
    else
    {
    printf(“连接ZSMQ成功 ”);
    }
    if (!pZSMQI-> SendFileToPlat(“targetid”,//目的地
    1,//目的地个数
    “”,//目的地队列
    “datatype”,//数据类型
    5,//优先级别(0~9)
    0,0,0,0,//4个保留字段
    0,//超时时间 0为永远不超时
    “d:/senddir”,//发送文件所在的目录
    “hello word.txt”,//文件名称
    0))//发送到默认队列中
    {
    printf(“发送文件失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    else
    {
    if (!pZSMQI->Commit())//调用Commit提交操作
    {
    printf(“提交操作失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    printf(“发送文件成功! ”);
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    ZSMQ系列文档――API编程手册 For C++
     10
    2.11. GetFile(收取文件)
    函数说明:GetFile() 通过IZSMQInterface接口进行调用,作用是从交换管理平台
    中收取一个文件,成功返回true,如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szDatatype 数据类型
    szFileDir 文件所在的目录
    szDataQueueName 数据队列名称
    bOverWrite 如果有同名文件已经存在是否覆盖
    输出参数:函数返回收取文件的结果
    szFileName 输出文件名称
    pGWHead 输出网关头信息
    备注信息:如果接收的消息文件名称为空(发送的时候以消息方式发送),则系
    统会自动为这个消息生成一个文件名称。
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    char szFileName[256];
    if (!pZSMQI-> GetFile(“xxxxx”, //! 数据类型
    “/rcvdir”, //! 文件所在的目录
    szFileName, //! 输出文件名 最长75字节
    0, //! 数据队列名称 (如果填写,数据将从本地数据队列中取出)
    0, //! 输出数据的网关头(输入NULL的时候,就不输出网关头)
    true) //! 重名是否覆盖
    {
    printf(“接收文件失败[%s]{%d,%d} ”,
    ZSMQGetLastError,ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    else
    {
    if (!pZSMQI->Commit())//调用Commit提交操作
    {
    printf(“提交操作失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    }
    printf(“接收文件[%s]成功! ”, szFileName);
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    ZSMQ系列文档――API编程手册 For C++
     11
    2.12. CreateMessage(建立消息)
    函数说明:CreateMessage()通过IZSMQInterface接口进行调用,可以在交换管
    理平台中建立一个消息,这是一个低级函数,使用起来非常灵活,SendBuffer
    函数和SendFile 函数也是通过本函数编写而成。如果函数调用成功,会返回所
    建消息的访问接口IZSMQMessageInterface,通过该访问接口可以对消息进行读
    写操作;如果失败函数返回NULL,可以调用ZSMQGetLastError查看错误信息、
    调用ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode
    查看错误原因代码。
    输入参数:szTargetID 目的地
    szTargetQueueName 目的地接收队列名称
    szDataType 数据类型
    cPriority 优先级别 0 ~ 9
    cEncrypt 加密算法 0 为没有加密 保留字段
    cCompress 压缩算法 0 为没有压缩 保留字段
    cSendType 发送类型 0 保留字段
    cReply 是否回执 保留字段
    ulTimeOut 超时时间 0 为此标记无效 单位秒
    ulMessageLength 消息长度
    szFileName 文件名称
    szDataQueueName 数据队列名称
    bClone 是否要建立一个消息的克隆消息
    pulMsgNO 克隆消息的编号
    pulMsgOffset 克隆消息的偏移量
    szDataQueueName 数据队列名称
    输出参数:函数本身返回消息访问接口IZSMQMessageInterface,如果失败返回
    null
    pulMsgNO 返回消息的编号
    pulMsgOffset 返回消息的偏移量
    备注信息:关于消息的克隆,克隆可以使多条消息共用同一个数据块,例如同一
    个消息需要发送给若干个目的地,可以让多个目的地共同使用同一个数据块,数
    据交换管理平台会分别为每一个消息块进行计数,这样做可以节省大量的IO 操
    作,这个特性对于广播发送尤其有效。克隆的使用方法也很简单,在建立一个
    消息的时候bClone = false ,并传入两个long 指针,如果函数调用成功,
    pulMsgNO, pulMsgOffset 会返回所建消息的消息编号以及偏移量,以后再建立
    消息的时候,bClone = true,并传入pulMsgNO, pulMsgOffset即可。关于其他备
    注信息请参考SendBuffer 和 SendFile 中的说明。
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    IZSMQMessageInterface* pMessageInterface = pZSMQI-> CreateMessage(
    “targetid”,//目的地
    ZSMQ系列文档――API编程手册 For C++
     12
    1,//目的地个数
    “”,//目的地队列
    “datatype”,//数据类型
    5,//优先级别(0~9)
    0,0,0,0,//4个保留字段
    0,//超时时间 0为永远不超时
    12,//消息长度
    “”//文件名称
    );
    if (!pMessageInterface)
    {
    printf(“建立消息失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    if (!pMessageInterface-> WriteDataToMessage(“hello word !”,12))
    {
    printf(“写入消息失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    //关闭消息接口
    DestoryMessageInterface(pMessageInterface);
    if (!pZSMQI->Commit())//调用Commit提交操作
    {
    printf(“提交操作失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    ZSMQ系列文档――API编程手册 For C++
     13
    2.13. GetMessageInterface(取得消息)
    函数说明:GetMessageInterface()通过IZSMQInterface接口进行调用,可以从交
    换平台中取得消息。这是一个低级函数,提供给用户一种更为灵活的方式取得消
    息,GetFile 函数也是调用这个函数编写而成。如果函数调用成功,会返回所取
    消息的访问接口,通过该访问接口可以对消息进行读写操作;如果失败函数返回
    NULL,可以调用ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode
    查看错误类型、调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szDatatype 数据类型
    szDataQueueName 数据队列名称
    bBrowseQueue 是否遍历队列
    pMsgHandle 消息句柄(遍历的时候使用)
    bDeleteFromQueue 取出消息后是否删除
    输出参数:函数本身返回执行的结果
    pGWHead 输出网关头信息
    pMsgHandle 输出消息句柄
    备注信息:使用GetMessageInterface取得消息,返回消息操作接口,使用得当
    的话可以减少磁盘IO,尤其是带有数据头的消息。GetMessageInterface可以遍
    历整个队列,在一些特殊的应用中可以利用这个特性进行消息处理。遍历队列的
    方法为:首先找到一条消息,输入bBrowseQueue =false bDeleteFromQueue=
    false 一条消息不是浏览消息且取出消息后不要删除这条消息,这时
    pMsgHandle会返回该消息的句柄,取下一条消息的时候,输入bBrowseQueue
    = true bDeleteFromQueue= false 以及一条消息的返回的pMsgHandle,即可
    得到下一条消息了,如果下一条消息存在pMsgHandle变成了该消息的句柄,这
    样就可以循环调用本函数达到遍历整个队列的目的了。
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    GWHead m_GWHead;
    long lMsgHandle;
    IZSMQMessageInterface* pMessageInterface = pZSMQI-> GetMessageInterface (
    “szDataType”,//数据类型
    “”,//队列名称
    “datatype”,//数据类型
    false,//是否遍历队列
    &m_GWHead,//网关头
    &lMsgHandle,//消息句柄
    12,//消息长度
    false//取出消息后是否删除
    );
    if (!pMessageInterface)
    {
    printf(“qude消息失败[%s]{%d,%d} ”,
    ZSMQ系列文档――API编程手册 For C++
     14
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    long lMsgLen = pMessageInterface-> GetMessageLength();
    char pData = new char[lMsgLen];
    if (lMsgLen != pMessageInterface-> GetDataFromMessage (pData, lMsgLen))
    {
    printf(“读取消息失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    printf(“%s ”, pData);
    delete pData;
    //关闭消息接口
    DestoryMessageInterface(pMessageInterface);
    //删除该消息
    if (!pZSMQI -> DeleteMessage(
    “szDataType”,//数据类型
    “”,//数据队列名称
    &m_GWHead,//数据网关头
    lMsgHandle,//消息句柄
    ))
    {
    printf(“删除消息失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    ZSMQ系列文档――API编程手册 For C++
     15
    2.14. DestoryMessageInterface (销毁消息接口)
    函数说明:DestoryMessageInterface()通过IZSMQInterface接口进行调用,用来
    关闭CreateMessage() 或者GetMessageInterface()取得消息接口。
    输入参数:pMessageInterface 消息接口
    输出参数:无
    备注信息:无
    例子程序: 无
    2.15. DeleteMessage(删除消息)
    函数说明:DeleteMessage()通过IZSMQInterface 接口进行调用,用来删除一个
    消息,本函数与GetMessageInterface函数配合使用,删除以浏览方式取得的消
    息。GetMessageInterface 得到该消息的GWHead 与pMsgHandle,输入这两
    个参数和该消息的数据类型就可以删除该消息了。如果函数调用成功,会返回
    true;如果失败函数返回false,可以调用ZSMQGetLastError查看错误信息、调用
    ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode 查看
    错误原因代码。
    输入参数:szDatatype 数据类型
    szDataQueueName 数据队列名称
    pGWHead 输出网关头信息
    lMsgHandle 消息句柄
    输出参数:函数本身返回执行的结果
    备注信息:删除消息前一定要先关闭该消息的访问接口
    例子程序: 参考2.9的例子程序
    ZSMQ系列文档――API编程手册 For C++
     16
    2.16. LockQueue(锁队列)
    函数说明:LockQueue()通过IZSMQInterface接口进行调用,用来锁定队列,对
    于多线程、多进程同时操作队列时提供一个锁的机制。如果函数调用成功,会返
    回true;如果失败函数返回false,可以调用ZSMQGetLastError查看错误信息、调
    用ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode 查
    看错误原因代码。
    输入参数:szDatatype 数据类型
    szDataQueueName 数据队列名称
    输出参数:函数本身返回执行的结果
    备注信息:该锁是逻辑锁不是物理锁
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    if (!pZSMQI->LockQueue(“XXXXX”,//数据类型
    “”//数据队列名称))
    {
    printf(“锁队列失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    if (!pZSMQI->UnlockQueue(“XXXXX”,//数据类型
    “”//数据队列名称))
    {
    printf(“解锁队列失败[%s]{%d,%d} ”,
    ZSMQGetLastError(),ZSMQGetErrorTypeCode(),BHGetErrorReasongCode());
    return 0;
    }
    DisConnectZSMQ(pZSMQI);//断开连接、释放内存
    2.17. UnlockQueue(解锁队列)
    函数说明:UnlockQueue()通过IZSMQInterface接口进行调用,用来解锁队列,
    如果函数调用成功,会返回true;如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szDatatype 数据类型
    szDataQueueName 数据队列名称
    输出参数:函数本身返回执行的结果
    备注信息:无
    例子程序: 参考2.15的例子程序
    ZSMQ系列文档――API编程手册 For C++
     17
    2.18. GetQueueCount(取得队列数量)
    函数说明:GetQueueCount()通过IZSMQInterface接口进行调用,用来取得队列
    管理器中管理的队列数量。如果失败函数返回false,可以调用ZSMQGetLastError
    查看错误信息、调用ZSMQGetErrorTypeCode 查看错误类型、调用
    ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:无
    输出参数:函数本身返回队列的数量
    备注信息:队列管理器中至少含有两个队列发送队列和接收队列,0为发送队列、
    1为接收队列
    例子程序:请参考2.21
    2.19. GetQueueName(取得队列的名称)
    函数说明:GetQueueName()通过IZSMQInterface接口进行调用,用来取得队列
    的名称。如果失败函数返回false,可以调用ZSMQGetLastError查看错误信息、调
    用ZSMQGetErrorTypeCode 查看错误类型、调用ZSMQGetErrorReasonCode 查
    看错误原因代码。
    输入参数:lQueueNO 队列的编号
    输出参数:函数本身返回执行的结果
    szQueueName 数据队列名称
    备注信息:发送队列 sendqueue 接收队列rcvqueue
    例子程序:请参考2.21
    2.20. GetQueueDataTypeCount(取得队列中数据类型的数量)
    函数说明:GetQueueDataTypeCount()通过IZSMQInterface接口进行调用,用来
    取得队列中数据类型的数量。如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szDataQueueName 数据队列名称
    输出参数:函数本身返回队列中含有的数据类型数量
    备注信息:发送队列返回的是队列中的方向数
    例子程序: 请参考2.21
    ZSMQ系列文档――API编程手册 For C++
     18
    2.21. GetQueueDataTypeName(取得数据类型的名称)
    函数说明:GetQueueDataTypeName()通过IZSMQInterface接口进行调用,用来
    取得队列中某一数据类型的名称。如果失败函数返回false,可以调用
    ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错误类型、
    调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:szDataQueueName 数据队列名称
    lDataTypeNO 数据类型编号
    输出参数:函数本身返回执行的结果
    szDataTypeName 数据类型名称
    备注信息:无
    例子程序:请参考2.21
    2.22. GetQueueDepth(取得队列的深度)
    函数说明:GetQueueDepth()通过IZSMQInterface接口进行调用,用来取得队列
    的深度,深度即队列中含有的消息数量
    输入参数:szDatatype 数据类型
    szDataQueueName 数据队列名称
    ucPriority 优先级别
    输出参数:函数本身返回队列的深度
    备注信息:优先级别输入’*’ (47)表示优先级全部
    例子程序:
    IZSMQInterface* pZSMQI = ConnectZSMQ(szQMName);
    long lQueueCount = pZSMQI->GetQueueCount();
    if (lQueueCount < 0)
    {
    printf("执行命令失败!{错误描述:[%s] 错误类型[%d] 错误码
    [%d]} ",ZSMQGetLastError(),ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    }
    char szQueueName[256];
    for (int i=0;i {
    if (pZSMQI->GetQueueName(i,szQueueName))
    {
    printf("队列[%s] ",szQueueName);
    //取数据类型数
    long lDataTypeCount = pZSMQI->GetQueueDataTypeCount(szQueueName);
    if (lDataTypeCount < 0)
    {
    printf("执行命令失败!{错误描述:[%s] 错误类型[%d] 错误码
    ZSMQ系列文档――API编程手册 For C++
     19
    [%d]} ",ZSMQGetLastError(),ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    break;
    }
    else
    {
    for (int m=0;m {
    char szDataTypeName[256];
    if (!pZSMQI->GetQueueDataTypeName(szQueueName,m,szDataTypeName))
    {
    printf("执行命令失败!{错误描述:[%s] 错误类型[%d] 错误码
    [%d]} ",ZSMQGetLastError(),ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    break;
    }
    else
    {
    if (i == 0)
    {
    printf(" 传输方向[%s]",szDataTypeName);
    }
    else
    {
    printf(" 数据类型[%s]",szDataTypeName);
    }
    for (int n=strlen(szDataTypeName);n<18;n++)
    {
    printf(" ");
    }
    printf("深度
    [%d] ",pZSMQI->GetQueueDepth(szDataTypeName,szQueueName));
    }
    }
    }
    }
    else
    {
    printf("执行命令失败!{错误描述:[%s] 错误类型[%d] 错误码
    [%d]} ",ZSMQGetLastError(),ZSMQGetErrorTypeCode(),ZSMQGetErrorReasonCode());
    break;
    }
    }
    ZSMQ系列文档――API编程手册 For C++
     20
    2.23. GetMessageLength(取得消息长度)
    函数说明:GetMessageLength()通过IZSMQMessageInterface 接口进行调用,
    用来取得消息长度。
    输入参数:无
    输出参数:函数本身返回消息长度
    备注信息:无
    例子程序:无
    2.24. GetRemainMessageLength(取得剩余消息长度)
    函数说明:GetRemainMessageLength()通过IZSMQMessageInterface接口进行
    调用,用来取得剩余的消息长度。
    输入参数:无
    备注信息:取消息、写入消息以及移动消息指针会对这个值产生影响
    例子程序:无
    2.25. GetDataFromMessage(从消息中取得数据)
    函数说明:GetDataFromMessage()通过IZSMQMessageInterface接口进行调用,
    用来从消息中取得数据。如果失败函数返回值与输入的ulDataLength不相等,可
    以调用ZSMQGetLastError查看错误信息、调用ZSMQGetErrorTypeCode查看错
    误类型、调用ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:pData 数据缓冲
    ulDataLength 要取得的长度
    输出参数:函数本身返回取得的字节数
    备注信息:取得的数据的同时会向后移动消息指针
    例子程序:无
    2.26. WriteDataFromMessage(在消息中写入数据)
    函数说明:WriteDataToMessage()通过IZSMQMessageInterface接口进行调用,
    用来在消息中写入数据。如果失败函数返回false,可以调用ZSMQGetLastError
    查看错误信息、调用ZSMQGetErrorTypeCode 查看错误类型、调用
    ZSMQGetErrorReasonCode查看错误原因代码。
    输入参数:pData 数据缓冲
    ulDataLength 要写入的长度
    输出参数:函数本身返回执行结果
    备注信息:写入数据的同时会向后移动消息指针
    例子程序:无
    ZSMQ系列文档――API编程手册 For C++
     21
    2.27. SeekMessage(在消息中移动指针)
    函数说明:SeekMessage()通过IZSMQMessageInterface接口进行调用,用来在
    消息中移动指针,这个函数与C语言中的lseek函数类似
    输入参数:ulOffset 数据的相对位置
    iSeekMode 移动的模式
    输出参数:函数本身返回执行结果
    备注信息:iSeekMode SEEK_SET 从开始计算相对位置 SEEK_CUR 从当前位
    置计算相对位置 SEEK_END 从最后计算相对位置
    例子程序:无
    ZSMQ系列文档――API编程手册 For C++
     22
    三章ZSMQ API FOR C++ 例子程序
    3.1. sendtest(文件发送)
    sendtest 主要实现文件的发送,程序所在位置: ZSMQSamples/C++/sendtest
    #include
    #include
    #include
    #include
    #include "i_explatapi.h"
    #ifdef WIN
    #include
    #else
    #include
    #endif
    int main(int argc,char** argv)
    {
    if (argc != 9 )
    {
    printf("用法:%s 源发地 本地数据队列名称 目的地 数据类型 优先级(0~9) 路径 文件名 循
    环次数 ",argv[0]);
    printf("如果要发送数据到目的地,本地数据队列名称填写为 sendqueue ");
    return -1;
    }
    IZSMQInterface* pZSMQI = ConnectZSMQ(argv[1]);
    if (!pZSMQI)
    {
    printf("连接交换管理平台失败{%s} ",ZSMQGetLastError());
    return -1;
    }
    unsigned long ulCount = 0;
    unsigned long ulShouldTime = (unsigned long) atol(argv[8]);
    char* pDataQueueName;
    if (!stricmp(argv[2],"sendqueue"))
    {
    pDataQueueName = NULL;
    }
    else
    ZSMQ系列文档――API编程手册 For C++
     23
    {
    pDataQueueName = argv[2];
    }
    while(1)
    {
    if
    (!pZSMQI->SendFile(argv[3],1,"",argv[4],atoi(argv[5]),0,0,0,0,0,argv[6],argv[7],pDataQueueNam
    e))
    {
    printf("发送文件失败{%s} ",ZSMQGetLastError());
    pZSMQI->Rollback();
    #ifdef WIN
    Sleep(1000);
    #else
    sleep(1);
    #endif
    continue;
    }
    if (!pZSMQI->Commit())
    {
    printf("提交失败{%s} ",ZSMQGetLastError());
    return -1;
    }
    ++ulCount;
    //if (ulCount%100 == 0)
    {
    printf("发送了 %d 个文件 ", ulCount);
    }
    //printf("Press Any Key  ");
    //getch();
    if (ulShouldTime)
    {
    if (ulCount >= ulShouldTime)
    {
    break;
    }
    }
    }
    DisConnectZSMQ(pZSMQI);
    return 0;
    }
    ZSMQ系列文档――API编程手册 For C++
     24
    3.2. rcvtest(接收文件)
    rcvtest 主要实现文件的接收,程序所在位置: ZSMQSamples/C++/rcvtest
    #include
    #include
    #include
    #include
    #include "i_explatapi.h"
    #ifdef WIN
    #include
    #else
    #include
    #endif
    int main(int argc,char** argv)
    {
    if (argc != 7 )
    {
    printf("用法:%s 队列管理器 数据队列名称 数据类型 路径 次数 没有数据是否退出
    ",argv[0]);
    printf("如果要从接收队列取数据,数据队列名称 填写为 rcvqueue ");
    return -1;
    }
    unsigned long ulCount = 0;
    unsigned long ulShouldTime = (unsigned long) atol(argv[5]);
    bool bQuitIfNoFileExists = atoi(argv[6])?true:false;
    GWHead m_GWHead;
    char szFileName[256];
    bool bReturn;
    IZSMQInterface* pZSMQI = ConnectZSMQ(argv[1]);
    if (!pZSMQI)
    {
    printf("连接交换管理平台失败{%s} ",ZSMQGetLastError());
    return -1;
    }
    char* pDataQueueName = NULL;
    if (stricmp(argv[2],"rcvqueue"))
    {
    pDataQueueName = argv[2];
    }
    while (1)
    ZSMQ系列文档――API编程手册 For C++
     25
    {
    bReturn = pZSMQI->GetFile(argv[3],argv[4],szFileName,pDataQueueName,&m_GWHead);
    if (bReturn)
    {
    ulCount ++;
    printf("接收文件[%s]->[%s]成功!总计个数[%d] ",szFileName,argv[4],ulCount);
    if (!pZSMQI->Commit())
    {
    printf("提交失败");
    }
    if (ulShouldTime)
    {
    if (ulCount >= ulShouldTime)
    {
    break;
    }
    }
    }
    else
    {
    if (bQuitIfNoFileExists)
    {
    printf("没有数据类型为[%s]的消息 ",argv[3]);
    DisConnectZSMQ(pZSMQI);
    return 0;
    }
    //printf("没有文件,等待1秒 ");
    #ifdef WIN
    Sleep(1000);
    #else
    sleep(1);
    #endif
    }
    }
    DisConnectZSMQ(pZSMQI);
    return 0;
    }
    ZSMQ系列文档――API编程手册 For C++
     26
    3.3. deletetest(删除消息)
    deletetest 主要实现删除消息,程序所在位置: ZSMQSamples/C++/deletetest
    #include
    #include
    #include
    #include
    #include "i_explatapi.h"
    #ifdef WIN
    #include
    #else
    #include
    #endif
    int main(int argc,char** argv)
    {
    if (argc != 6 )
    {
    printf("用法:%s 队列管理器 队列名称 数据类型 消息编号 数据标识 ",argv[0]);
    return -1;
    }
    char szDataID[1024];
    strcpy(szDataID,argv[5]);
    GWHead m_GWHead;
    memset(&m_GWHead,0,sizeof(GWHead));
    long lMsgHandle = atol(argv[4]);
    int istrlen = strlen(szDataID);
    if (istrlen<16)
    {
    printf("删除消息失败,数据ID长度错误 ");
    return -1;
    }
    char* p = szDataID + (istrlen-5);
    m_GWHead.usNO = (unsigned short) atoi(p);
    *p = 0;
    p = szDataID + (istrlen - 15);
    m_GWHead.lCreateTime = atol(p);
    *p = 0;
    strcpy(m_GWHead.SourceID,szDataID);
    IZSMQInterface* pZSMQI = ConnectZSMQ(argv[1]);
    if (!pZSMQI)
    ZSMQ系列文档――API编程手册 For C++
     27
    {
    printf("连接交换管理平台失败{%s} ",ZSMQGetLastError());
    return -1;
    }
    if (!pZSMQI->DeleteMessage(argv[3],argv[2],&m_GWHead,lMsgHandle))
    {
    printf("%s ",ZSMQGetLastError());
    }
    else
    {
    printf("删除消息成功 ");
    }
    DisConnectZSMQ(pZSMQI);
    return 0;
    }
    ZSMQ系列文档――API编程手册 For C++
     28
    3.4. browsetest(浏览队列)
    browsetest 主要实现浏览消息,程序所在位置: ZSMQSamples/C++/browsetest
    #include
    #include
    #include
    #include
    #include "i_explatapi.h"
    #ifdef WIN
    #include
    #else
    #include
    #endif
    #define VT_COUNT 0
    #define VT_DETAIL 1
    #define VT_ALL 2
    int main(int argc,char** argv)
    {
    if (argc != 6 )
    {
    printf("用法:%s 队列管理器 队列名称 数据类型 [COUNT|DETAIL|ALL] 返回的消息数(0表示
    全部) ",argv[0]);
    return -1;
    }
    int iViewType = VT_COUNT;
    if (!stricmp(argv[4],"COUNT"))
    {
    iViewType = VT_COUNT;
    }
    else if (!stricmp(argv[4],"DETAIL"))
    {
    iViewType = VT_DETAIL;
    }
    else if (!stricmp(argv[4],"ALL"))
    {
    iViewType = VT_ALL;
    }
    else
    {
    printf("用法:%s 队列管理器 队列名称 数据类型 [COUNT|DETAIL|ALL] 返回的消息数(0表示
    ZSMQ系列文档――API编程手册 For C++
     29
    全部) ",argv[0]);
    return 0;
    }
    unsigned long ulShouldCount = (unsigned long) atol(argv[5]);
    IZSMQInterface* pZSMQI = ConnectZSMQ(argv[1]);
    if (!pZSMQI)
    {
    printf("连接交换管理平台失败{%s} ",ZSMQGetLastError());
    return -1;
    }
    if (iViewType == VT_COUNT)
    {
    long lQueueDepth = pZSMQI->GetQueueDepth(argv[3],argv[2]);
    DisConnectZSMQ(pZSMQI);
    if (lQueueDepth < 0)
    {
    printf(ZSMQGetLastError());
    }
    else
    {
    printf("队列管理器[%s]队列[%s]数据类型[%s]的深度为
    [%d] ",argv[1],argv[2],argv[3],lQueueDepth);
    }
    return 0;
    }
    GWHead m_GWHead;
    long lMsgHandle;
    IZSMQMessageInterface* pMessage =
    pZSMQI->GetMessageInterface(argv[3],argv[2],false,&m_GWHead,&lMsgHandle,false);
    unsigned long ulCount = 0;
    while (pMessage)
    {
    if (iViewType == VT_DETAIL)
    {
    printf("消息编号[%d] 文件名称[%s] 数据标识
    [%s%010d%05d] ",lMsgHandle,m_GWHead.FileName,m_GWHead.SourceID,m_GWHead.lCreateTime,m_GWHea
    d.usNO);
    }
    else
    {
    printf("消息编号[%d] 文件名称[%s] 文件大小[%d] 源发地[%s] 目的地
    [%s] ",lMsgHandle,m_GWHead.FileName,m_GWHead.ulMessageLength,m_GWHead.SourceID,m_GWHead.Tar
    ZSMQ系列文档――API编程手册 For C++
     30
    getID);
    printf("优先级别[%d] 数据标识
    [%s%010d%05d] ",m_GWHead.cPriority,m_GWHead.SourceID,m_GWHead.lCreateTime,m_GWHead.usNO);
    }
    pZSMQI->DestoryMessageInterface(pMessage);
    ulCount ++;
    if (ulShouldCount)
    {
    if (ulCount >= ulShouldCount)
    {
    break;
    }
    }
    pMessage =
    pZSMQI->GetMessageInterface(argv[3],argv[2],true,&m_GWHead,&lMsgHandle,false);
    }
    printf("共计[%d]条消息 ",ulCount);
    DisConnectZSMQ(pZSMQI);
    return 0;
    }
    ZSMQ系列文档――API编程手册 For C++
     31
    附录:ZSMQ 代码信息参考
    4.1. 错误类型参考
    错误类型 错误类型标识 错误类型描述
    0 ZSMQERROR_NOERROR 没有错误
    10000 ZSMQERROR_PARAMETERERROR 参数输入错误
    20000 ZSMQERROR_SERVERERROR 运行期错误
    40000 ZSMQERROR_IOERROR 磁盘IO错误
    80000 ZSMQERROR_NETERROR 网络层错误
    4.2. 错误原因参考
    错误原因码 错误类型 错误描述
    10001 参数输入错误 目的地不能为空
    10002 参数输入错误 目的地长度范围错误
    10003 参数输入错误 目的地队列名称长度
    10004 参数输入错误 不能直接将消息发送到目的地的发送队列中
    10005 参数输入错误 数据类型不能为空
    10006 参数输入错误 数据类型长度范围错误
    10007 参数输入错误 文件名称长度范围错误
    10008 参数输入错误 数据队列名称长度范围错误
    10009 参数输入错误 队列管理器名称长度范围错误
    10010 参数输入错误 优先级别取值范围错误
    10011 参数输入错误 以浏览的方式取得消息必须输入网关头
    10012 参数输入错误 以浏览的方式取得消息必须输入消息句柄
    10013 参数输入错误 以浏览的方式取得消息不能直接删除
    10014 参数输入错误 要发送的文件不存在
    10015 参数输入错误 接收目录不存在
    10016 参数输入错误 GB2312字符集不存在(Java API 使用)
    10017 参数输入错误 文件名称不能为空
    10018 参数输入错误 要发送的缓存不能为空
    20001 运行期错误 没有消息
    20002 运行期错误 服务器返回信息错误
    20003 运行期错误 文件已经存在
    40001 磁盘IO错误 打开文件失败
    40002 磁盘IO错误 读取文件失败
    40003 磁盘IO错误 写入文件失败
    40004 磁盘IO错误 移动文件指针失败
    40005 磁盘IO错误 关闭文件失败
    40006 磁盘IO错误 队列文件的大小错误
    ZSMQ系列文档――API编程手册 For C++
     
    80001 网络层错误 向服务器发送请求出错
    80002 网络层错误 服务器响应超时
    80003 网络层错误 等待服务器应答出错
    80004 网络层错误 读取服务器发应答出错
    80005 网络层错误 建立SOCKET失败
    80006 网络层错误 连接服务器监听端口失败