c/c++ sdk接口说明

简介

   本篇章介绍客户端使用sdk接入cppcloud的接口api使用,主要头文件是client_c.hpp提供出给外部调用的接口,讲解函数的功能作用,参数输入输出代表的意思,sdk底层是与cppcloud的tcp通信,通信的协议在[服务端]通信协议介绍TCP里有定义,需了解可以点击链接进入阅读。 有如下分类。

  • sdk流程部分
  • 分布式配置
  • 服务提供
  • 服务消费

源文件组织结构

仅列主要的
├── common
│   ├── const.h                         -- 约定常量定义
│   ├── msgid.h                         -- tcp协议命令字定义
│   ├── exception.h                     -- 业务异常定义
│   ├── switchhand.h                    -- 线程切换到epoll-io线程辅助类
│   ├── repadjson                       -- json工具类(来自腾讯开发)
├── cpp_sdk
│   ├── client_c.cpp
│   ├── client_c.hpp                    -- sdk主入口头文件,开发者主要关注这个
│   ├── climanage.cpp
│   ├── climanage.h
│   ├── cloudapp.cpp                    -- cloudapp.h的实现
│   ├── cloudapp.h                      -- 与serv通信的客户连接实例封装类
│   ├── config_json.cpp
│   ├── config_json.h                   -- json配置文件的处理封装
│   ├── config_mgr.cpp
│   ├── config_mgr.h                    -- 分布式配置管理类
│   ├── iohand.cpp                      -- tcp协议通信的封装类实现
│   ├── iohand.h                        -- tcp协议通信的封装类
│   ├── listen.cpp
│   ├── listen.h                        -- tcp服务提供时的监听处理
│   ├── Makefile                        -- 编译构建出libsdk_cppcloud.so
│   ├── msgprop.h                       -- tcp报文格式结构定义
│   ├── provd_mgr.cpp
│   ├── provd_mgr.h                     -- 服务提供者管理
│   ├── sample_*.cpp                    -- 示例demo程序
│   ├── shttp_invoker_mgr.cpp
│   ├── shttp_invoker_mgr.h
│   ├── svrconsumer.cpp
│   ├── svrconsumer.h                   -- 服务消费者管理
│   ├── svr_stat.cpp
│   ├── svr_stat.h                      -- 服务提供和消费的统计处理
│   ├── tcpaio_invoker_mgr.h            -- 异步高效tcp消费者管理
│   └── tcp_invoker_mgr.h               -- 同步方式tcp消费者管理

准备工作

   在cpp_sdk目录编译出sdk动态库,直接make即可,或者make all把sample示例也一起生成(make时是依赖公共库的libhocomm.so,这是在common目录下make生成),编译细节就不多说了,有问题在线源码或技术blog上留言。
   开发是在你的代码中包括sdk头文件, #include "client_c.hpp" 所需调用的接口放在namespace client_c里,想直接引用可以using namespace client_c;,然后根据业务需求调用后面介绍的API函数。

sdk流程部分

初始化

函数原型

int Init( const string& appName, const string& servHostPort, int appid=0, const > string& tag=nilstr )

功能说明

使用sdk首个要调用函数,进行sdk的一些初始化工作,其间会尝试连接后台cppcloud_serv,并上报自己身份信息,此函数返回成功才可以进行后面其他API调用。

参数说明

参数名 说明
appName 当前应用名称,后台要区分不同客户接入,应取一个和自身功能相关的名字
servHostPort 要连接的cppcloud_serv的地址,主机+端口形式,譬如"192.168.228.5:4800","www.cppcloud.cn:4800"
appid 当前应用的ID,整数值,区分不同客户应用,可以传0代表让serv帮自动分配
tag 为当前应用指定一个标签值。 当要在元配置_meta.json利用指定不同客户设置不同的主配置(mconf)或设定客户所属机房时用
返回值 成功返回0

sdk运行函数

功能说明

必须调用Run,sdk才会背后持续工作。一般是初始化之后,读配置完成了,该设置的参数也OK了,就调用Run让sdk工作起来。这里说的持续工作会作很多事情,包括接收配置变化,与serv断开自动重连,接收一些实时通知(关闭应用,获取负载壮况),上报服务统计等等,想了解细节就看源码了。

函数原型

int Run( bool runBackgroud )

参数说明

参数名 说明
runBackgroud True时会开个新线程进行io通信操作,立即返回;false时应在当前调用线程做事,阻塞住不返回,直到应用需要退出(web上通知关闭或当NotifyExit调用)才返回

通知应用结束

函数原型

int NotifyExit( void* ptr )

销毁和退出

功能说明

sdk结束,和Init相对应。

函数原型

void Destroy( void );

分布式配置

获取主配置文件名

功能说明

为配置方面更灵活好用,尽量减少客户端的配置;每个应用都可以指定一个主配置mconf,即对应一个json文件名,这个函数是获取,元配置里有设置才会返回,否则返回空字符串;如何设置点击这里链接

函数原型

string GetMConfName( void )

参数说明

成功返回文件名,譬如"abc.json",否则空字符串。

加载配置指定文件

功能说明

指定要加载哪些配置文件,把之后运行过程需要访问的配置文件名进行加载;只要先加载,后面的查询接口Query才能使用。注意主配置文件默认会自动加载,无需在此加载,当然重复加载也可以。

函数原型

int LoadConfFile( const string& fname )

参数说明

参数名 说明
fname 以空格分隔的文件名列表字符串,譬如"app1-dev.json dev2.json"
返回值 成功返回0

分布式配置查询

功能说明

查询json里面的配置

函数原型

template<class T> int Query( T& oval, const string& fullqkey, bool wideVal )

参数说明

参数名 说明
T 模板参数,取值[string, int, map, map, vector, vector]其中一个
oval 输出,返回查询值
fullqkey 查询字符串,格式是"conffile.json/key1/key2",当查当前主配置文件时,主配置文件名可省略即"/key1/key2"
wideVal 是否泛式查询,譬如当oval类型是string时,json里的值不是字符串形式,则会进行转换填充到oval;如果wideVal=false时则要严格匹配格式,T要和json里相对应类型才成功
返回值 成功时返回0

设置配置变化回调

功能说明

设置一个回调函数,当已加载了的配置文件中serv中发生变化后,会收到通知,进行cb调用。(可选的)

函数原型

void SetConfChangeCallBack( CONF_CHANGE_CB cb )

参数说明

参数名 说明
cb cb签名是typedef void (*CONF_CHANGE_CB)(const string& confname), 回调是传进变化的文件名

服务提供

创建tcp服务提供者

功能说明

创建并初始化一个tcp服务提供者,可选其中一个重载版本。

函数原型

int InitTcpProvider( int listenPort );  
int InitTcpProvider( const string& host, int listenPort, int qlen );

参数说明

参数名 说明
listenPort 监听端口,必填
host 所在主机的ip,不填则默认0.0.0.0,在所有网卡接口上有效
qlen tcp accept里的队列长度
返回值 成功返回0

添加tcp服务处理回调函数

功能说明

添加tcp服务处理回调函数,当有请求到来时,触发此回调。

函数原型

int AddProvdFunction( CMD_HAND_FUNC func )
int AddCmdFunction( unsigned cmdid, CMD_HAND_FUNC func )

参数说明

参数名 说明
func 函数签名typedef int (*CMD_HAND_FUNC)(msg_prop_t*, const char*),回调函数的第1个参数,传入当前消息的属性(有命令字cmdid,序号seqid);第2参数是消息报文体,一般是json字符串
cmdid AddCmdFunction是订阅指定的消息命令字,用cmdid给出;AddProvdFunction是使用默认的命令字,即CMD_TCP_SVR_REQ 0x001B(27)

服务提供者回复消息

函数原型

int ProvdSendMsg( const msg_prop_t* msgprop, const string& msg )
int ProvdSendMsgAsync( const msg_prop_t* msgprop, const string& msg )

参数说明

参数名 说明
msgprop 消息发往目标,对应回调时传入的第一个参数放入;当同步返回时用ProvdSendMsg,异步返回时用ProvdSendMsgAsync;同步是把回调return前进行数据回复,异步是指先记录下当前请求,可以放入某个队列,立即返回,之后由其他线程去处理耗时业务,处理完时回复数据使用Async那个函数回复;
msg 响应报文体字符串

发布服务

函数原型

int RegProvider( const string& regname, int prvdid, short protocol, int port, const string& path=nilstr )
int RegProvider( const string& regname, int prvdid, short protocol, const string& url )

参数说明

参数名 说明
regname 服务名,同类服务同个名
prvdid 编号,当同一进程有多个服务时用
protocol 协议编号:tcp=1 udp=2 http=3 https=
port 端口
path tcp服务不需要,http服务时可用,url路径部分
url 直接指定url,譬如"tcp://192.168.1.44:4806","http://172.16.4.8:4803/mypath";当使用无url那个版本时,sdk根据参数自动生成url,host/ip部分是取与serv连接的socket的地址,如果不适合还是请用下面版本指定url,当内外网部署,不同应用所在网段不同时还是必须指定url才行。
返回值 成功返回0

相关API

void setUrl( const string& regname, int prvdid, const string& url )
void setDesc( const string& regname, int prvdid, const string& desc )
void setWeight( const string& regname, int prvdid, short weight )
void setVersion( const string& regname, int prvdid, short ver )
void setEnable( const string& regname, int prvdid, bool enable )
int PostOut( const string& regname, int prvdid ) // 发布,经过setXXX改变后发布才生效
int PostEnable( const string& regname, int prvdid, bool enable ) // 禁用还是开启服务

这些都是运行是动态改变服务提供者信息接口,看字面意思就可以了解功能了,不一一列解了。 注意要改用PostOut或PostEnbale后才会发到serv端,其他消费者才发现到变化。

增加服务提供者统计计数

功能说明

一般是处理一条客户请求后,反馈给后台成功或失败

函数原型

void AddProviderStat( const string& regname, int prvdid, bool isOk, int dcount=1 )

参数说明

参数名 说明
regname 服务名称
prvdid 编号
isOk 成功传true,失败传false
dcount 计数
返回值 成功返回0

服务消费

消费者初始化

功能说明

传递所有运行过程要消费的服务名称

函数原型

int InitInvoker( const string& svrList )

参数说明

参数名 说明
svrList 所有运行过程要消费的服务名称,空格分隔
返回值 成功返回0

参数设置

功能说明

设置请求的超时值SetRequestTimeout
设置刷新服务提供者列表的时间间隔SetRefreshTimeOut
设置上报统计信息周期SetReportStatTime

函数原型

void SetRequestTimeout(int sec, const string& svrname ) // svrname='' 设置所有
void SetRefreshTimeOut( int sec )
void SetReportStatTime( int sec )

参数说明

参数比较简单,不说明了。

增加服务消费统计计数

功能说明

消费一次服务,反馈给后台成功或失败

函数原型

void AddInvokerStat( const svr_item_t& pvd, bool isOk, int dcount=1 )

参数说明

参数名 说明
pvd 对应的提供者项
isOk 成功传true,失败传false
dcount 计数
返回值 成功返回0

获取一个服务提供者

功能说明

获取一个服务提供者,如果直接调用后面的TcpRequest或TcpAioRequestHttpGet或HttpPost可以无需调用此函数;当你用自定义方式处理服务消费时就可以使用这函数,或者自行实现udp消费流程,udp目前本sdk还提提供。

函数原型

int GetSvrPrvd( svr_item_t& pvd, const string& svrname )

参数说明

参数名 说明
pvd 输出,服务提供者信息
svrname 要消费的服务名
返回值 成功返回0

消费TCP服务

功能说明

消费TCP服务,每次调用都根据服务提供者列表的每项权重(weight)选出一提供者,然后向其发TCP协议请求报文,最后等待回复,解析包体到resp返回。

函数原型

int TcpRequest( string& resp, const string& reqmsg, const string& svrname )
int TcpAioRequest( string& resp, const string& reqmsg, const string& svrname )

参数说明

参数名 说明
resp 输出,响应报文体
reqmsg 请求报文体
svrname 服务名称
返回值 成功返回0

消费Http服务

功能说明

消费Http服务,每次调用都根据服务提供者列表的每项权重(weight)选出一提供者,然后向其发http请求,最后等待回复,解析包体到resp返回。

函数原型

int HttpGet( string& resp, const string& path, const string& queryStr, const string& svrname )
int HttpPost( string& resp, const string& path, const string& reqBody, const string& svrname )

参数说明

参数名 说明
resp 输出,响应报文体
path http的路径部分,譬如http://www.cppcloud.cn:4810/proj/1,path=“/proj/1”
svrname 服务名称
queryStr GET请求时,查询串,譬如"v1=123&v2=hello"
reqBody POST请求时包体
返回值 成功返回0