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或TcpAioRequest，HttpGet或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