API参考 ​

介绍 ​

本文主要介绍UBS Comm对外提供的API。可以从两个不同的角度，对UBS Comm的API进行分类：

• 编程语言

  UBS Comm主体使用C++语言开发，对外提供C++ API。为了方便不同场景的开发者使用，UBS Comm还对C++ API做了一层封装，对外提供C API。

• 功能架构

  考虑性能及易用性，UBS Comm使用了“传输层”和“服务层”两层架构。传输层追求极致性能，服务层追求极致易用性。传输层和服务层均提供API，使用传输层或服务层的API均可以独立完成通信功能。传输层仅提供了高性能的通信基础功能，服务层还提供了链路重连、限流、超时检测等常用的高级功能。

由于UBS Comm对外提供的API较多，为方便开发者阅读及理解，本文分为如下几个大章节介绍UBS Comm的API。

• 基础API参考

  介绍应用开发过程中最常用和基础的API，建议使用UBS Comm的开发者对这些API都有所了解。

• 高级API参考

  介绍应用开发过程中不常用的API，开发者可以根据自身场景需要进行查阅。

• 环境变量

  介绍UBS Comm对外提供的环境变量。

• 错误码

  介绍UBS Comm的错误码名称、取值及部分常见错误码的处理方法。

基础API参考 ​

C++ API ​

服务层API ​

UBSHcomService::Create ​

函数定义

根据类型、名字和可选配置项创建一个服务层的NetService对象。

实现方法

static UBSHcomService* UBSHcomService::Create(UBSHcomServiceProtocol t, const std::string &name, const UBSHcomServiceOptions &opt = {});

参数说明

表 1 参数说明

返回值

成功则返回NetService类型的实例，否则返回空。

UBSHcomService::Destroy ​

函数定义

销毁服务，会清理全局map并根据名字销毁对象。

实现方法

static int32_t UBSHcomService::Destroy(const std::string &name);

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示销毁成功。

UBSHcomService::Bind ​

函数定义

服务端绑定监听的url和端口号

实现方法

int32_t UBSHcomService::Bind(const std::string &listenerUrl, const UBSHcomServiceNewChannelHandler &handler)

参数说明

表 1 参数说明

返回值

绑定成功返回0，失败返回对应错误码

UBSHcomService::Start ​

函数定义

启动服务

实现方法

int32_t UBSHcomService::Start()

参数说明

无

返回值

启动成功返回0，启动失败返回失败错误码。

UBSHcomService::Connect ​

函数定义

客户端向服务端发起建链。

实现方法

int32_t UBSHcomService::Connect(const std::string &serverUrl, UBSHcomChannelPtr &ch, const UBSHcomConnectOptions &opt = {})

参数说明

表 1 参数说明

返回值

无

UBSHcomService::Disconnect ​

函数定义

断开链接。

实现方法

void UBSHcomService::Disconnect(const UBSHcomChannelPtr &ch)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterMemoryRegion ​

函数定义

• 注册一个内存区域，内存将在UBS Comm内部分配。
• 将用户申请的内存，注册到UBS Comm中。

实现方法

• int32_t UBSHcomService::RegisterMemoryRegion(uint64_t size, UBSHcomRegMemoryRegion &mr)
• int32_t UBSHcomService::RegisterMemoryRegion(uintptr_t address, uint64_t size, UBSHcomRegMemoryRegion &mr)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示注册成功。

UBSHcomService::DestroyMemoryRegion ​

函数定义

销毁一个内存区域。

实现方法

void UBSHcomService::DestroyMemoryRegion(UBSHcomRegMemoryRegion &mr)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterChannelBrokenHandler ​

函数定义

给UBSHcomService注册断链回调函数。

实现方法

void UBSHcomService::RegisterChannelBrokenHandler(const UBSHcomServiceChannelBrokenHandler &handler, const UBSHcomChannelBrokenPolicy policy)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterIdleHandler ​

函数定义

给此UBSHcomService注册worker闲时回调函数

实现方法

void UBSHcomService::RegisterIdleHandler(const NetServiceIdleHandler &h)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterRecvHandler ​

函数定义

注册回调函数以处理异步通信收到消息事件。

实现方法

void UBSHcomService::RegisterRecvHandler(const UBSHcomServiceRecvHandler &recvHandler)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterSendHandler ​

函数定义

注册回调函数以处理消息发送完成事件。

实现方法

void UBSHcomService::RegisterSendHandler(const UBSHcomServiceSendHandler &sendHandler)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::RegisterOneSideHandler ​

函数定义

注册回调函数以处理单边读/写完成事件。

实现方法

void UBSHcomService::RegisterOneSideHandler(const UBSHcomServiceOneSideDoneHandler &oneSideDoneHandler)

参数说明

表 1 参数说明

返回值

无

UBSHcomChannel::Send ​

函数定义

• 向对端异步发送一个双边请求消息，并且不等待响应。
• 向对端同步发送一个双边请求消息，并且不等待响应。

实现方法

• int32_t UBSHcomChannel::Send(const UBSHcomRequest &req, const Callback *done)
• int32_t UBSHcomChannel::Send(const UBSHcomRequest &req)

参数说明

表 1 参数说明

返回值

表示函数执行结果，0表示发送成功。

UBSHcomChannel::Call ​

函数定义

• 异步模式下，发送一个UBSHcomRequest消息，并等待对方回复UBSHcomResponse响应消息。
• 同步模式下，发送一个UBSHcomRequest消息，并等待对方回复UBSHcomResponse响应消息。

实现方法

• int32_t UBSHcomChannel::Call(const UBSHcomRequest &req, UBSHcomResponse &rsp, const Callback *done)
• int32_t UBSHcomChannel::Call(const UBSHcomRequest &req, UBSHcomResponse &rsp)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示发送成功。

UBSHcomChannel::Reply ​

函数定义

• 异步模式下，向对端回复一个消息，配合Call接口使用

• 同步模式下，向对端回复一个消息，配合Call接口使用

实现方法

• int32_t UBSHcomChannel::Reply(const UBSHcomReplyContext &ctx, const UBSHcomRequest &req, const Callback *done)

• int32_t UBSHcomChannel::Reply(const UBSHcomReplyContext &ctx, const UBSHcomRequest &req)

参数说明

表 1 参数说明

返回值

表示函数执行结果，0表示发送成功。

UBSHcomChannel::Get ​

函数定义

• 同步模式下，发送一个读请求给对方。
• 异步模式下，发送一个读请求给对方。

实现方法

-int32_t UBSHcomChannel::Get(const UBSHcomOneSideRequest &req, const Callback *done)

• int32_t UBSHcomChannel::Get(const UBSHcomOneSideRequest &req)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示读请求成功。

UBSHcomChannel::Put ​

函数定义

• 同步模式下，发送一个写请求给对方。
• 异步模式下，发送一个写请求给对方。

实现方法

• int32_t UBSHcomChannel::Put(const UBSHcomOneSideRequest &req, const Callback *done)

• int32_t UBSHcomChannel::Put(const UBSHcomOneSideRequest &req)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示写请求成功。

UBSHcomChannel::Recv ​

函数定义

只用于接收RNDV请求。

实现方法

int32_t Recv(const UBSHcomServiceContext &context, uintptr_t address, uint32_t size, const Callback *done = nullptr)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示接收请求成功。

UBSHcomChannel::SetFlowControlConfig ​

函数定义

设置限流。

实现方法

int32_t SetFlowControlConfig(const FlowCtrlOptions &opt)

参数说明

表 1 参数说明

返回值

返回0表示成功

UBSHcomChannel::SetChannelTimeOut ​

函数定义

给该channel设置超时时间。未设置时默认超时时间30s。

实现方法

void UBSHcomChannel::SetChannelTimeOut(int16_t oneSideTimeout, int16_t twoSideTimeout)

参数说明

表 1 参数说明

返回值

无

UBSHcomChannel::SetUBSHcomTwoSideThreshold ​

函数定义

设置双边操作阈值。

实现方法

int32_t SetUBSHcomTwoSideThreshold(const UBSHcomTwoSideThreshold &threshold)

参数说明

表 1 参数说明

返回值

返回0表示成功。

UBSHcomChannel::GetId ​

函数定义

获得channel ID。

实现方法

uint64_t UBSHcomChannel::GetId()

参数说明

无

返回值

uint64_t id信息。

UBSHcomChannel::GetPeerConnectPayload ​

函数定义

获得建链的payLoad信息。

实现方法

std::string UBSHcomChannel::GetPeerConnectPayload()

参数说明

无

返回值

playLoad信息。

UBSHcomChannel::SetTraceId ​

函数定义

设置trace id。

实现方法

void SetTraceId(const std::string &traceId)

参数说明

表 1 参数说明

返回值

无

UBSHcomServiceContext::Result ​

函数定义

获得ctx的结果，表示通信操作的成功与否。

实现方法

SerResult UBSHcomServiceContext::Result() const

参数说明

无

返回值

ctx的结果。

UBSHcomServiceContext::Channel ​

函数定义

获得ctx的NetChannel，可以用于向对端回复消息。

实现方法

const UBSHcomChannelPtr &UBSHcomServiceContext::Channel() const

参数说明

无

返回值

ctx的NetChannel。

UBSHcomServiceContext::OpType ​

函数定义

获得ctx的操作类型。

实现方法

Operation UBSHcomServiceContext::OpType() const

参数说明

无

返回值

ctx的操作类型。

UBSHcomServiceContext::RspCtx ​

函数定义

获得ctx的rspCtx，可以用于接收对端发送call消息后回复消息时当作参数使用。

实现方法

uintptr_t UBSHcomServiceContext::RspCtx() const

参数说明

无

返回值

ctx的rspCtx。

UBSHcomServiceContext::ErrorCode ​

函数定义

获得ctx的errorCode。

实现方法

const int32_t UBSHcomServiceContext::ErrorCode()

参数说明

无

返回值

ctx的errorCode

UBSHcomServiceContext::OpCode ​

函数定义

获得ctx的opCode。

实现方法

uint16_t UBSHcomServiceContext::OpCode() const

参数说明

无

返回值

ctx的opCode。

UBSHcomServiceContext::MessageData ​

函数定义

获得ctx的消息，为对端发送过来的消息。

实现方法

void *UBSHcomServiceContext::MessageData() const

参数说明

无

返回值

ctx的消息。

UBSHcomServiceContext::MessageDataLen ​

函数定义

获得ctx的消息长度。

实现方法

uint32_t UBSHcomServiceContext::MessageDataLen() const

参数说明

无

返回值

ctx的消息长度。

UBSHcomServiceContext::Clone ​

函数定义

将ctx的内容拷贝。

实现方法

static SerResult UBSHcomServiceContext::Clone(UBSHcomServiceContext &newOne, const UBSHcomServiceContext &oldOne, bool copyData = true)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

UBSHcomServiceContext::IsTimeout ​

函数定义

获得ctx是否超时，表示此次操作是否超时。

实现方法

bool UBSHcomServiceContext::IsTimeout() const

参数说明

无

返回值

ctx是否超时。

UBSHcomServiceContext::Invalidate ​

函数定义

将ctx的内容失效。

实现方法

void UBSHcomServiceContext::Invalidate()

参数说明

无

返回值

无

UBSHcomService::SetEnableMrCache ​

函数定义

设置RegisterMemoryRegion是否将mr放入pgTable管理。

实现说明

void SetEnableMrCache(bool enableMrCache);

参数说明

表 1 参数说明

返回值

无

C API ​

服务层API ​

ubs_hcom_service_create ​

函数定义

根据类型和名字创建一个服务层的NetService对象。

实现方法

int Service_Create(ubs_hcom_service_type t, const char *name, ubs_hcom_service_options options, ubs_hcom_service *service);

参数说明

表 1 参数说明

返回值

返回值为0则表示发送消息成功。

ubs_hcom_service_bind ​

函数定义

根据类型和名字创建一个服务层的NetService对象。

实现方法

int ubs_hcom_service_bind(ubs_hcom_service service, const char *listenerUrl, ubs_hcom_service_channel_handler h);

参数说明

表 1 参数说明

返回值

返回值为0则表示bind成功。

ubs_hcom_service_start ​

函数定义

根据类型和名字创建一个服务层的NetService对象。

实现方法

int ubs_hcom_service_start(ubs_hcom_service service);

参数说明

表 1 参数说明

返回值

返回值为0则表示创建成功。

ubs_hcom_service_destroy ​

函数定义

销毁服务，会清理全局map根据名字销毁对象。

实现方法

int ubs_hcom_service_destroy(ubs_hcom_service service, const char *name);

参数说明

表 1 参数说明

ubs_hcom_service_connect ​

函数定义

建立与远程服务器的连接，并返回连接通道。

实现方法

int ubs_hcom_service_connect(ubs_hcom_service service, const char *serverUrl, ubs_hcom_channel *channel, Service_UBSHcomConnectOptions options);

参数说明

表 1 参数说明

返回值

返回值为0则表示建链成功。

ubs_hcom_service_disconnect ​

函数定义

切断与远程服务器的连接。

实现方法

int ubs_hcom_service_disconnect(ubs_hcom_service service, ubs_hcom_channel channel);

参数说明

表 1 参数说明

返回值

返回值为0则表示断链成功。

ubs_hcom_service_register_memory_region ​

函数定义

注册一个内存区域，内存将在UBS Comm内部分配。

实现方法

int ubs_hcom_service_register_memory_region(ubs_hcom_service service, uint64_t size, ubs_hcom_memory_region *mr);

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示注册成功。

ubs_hcom_service_get_memory_region_info ​

函数定义

获得mr的内容。

实现方法

int ubs_hcom_service_get_memory_region_info(ubs_hcom_memory_region mr, ubs_hcom_mr_info *info);

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示注册成功。

ubs_hcom_service_register_assign_memory_region ​

函数定义

注册一个内存区域，内存将在UBS Comm外部分配。

实现方法

int ubs_hcom_service_register_assign_memory_region(ubs_hcom_service service, uintptr_t address, uint64_t size, ubs_hcom_memory_region *mr);

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示注册成功。

ubs_hcom_service_destroy_memory_region ​

函数定义

销毁一个内存区域，内存将在UBS Comm内部分配。

实现方法

int ubs_hcom_service_destroy_memory_region(ubs_hcom_service service, ubs_hcom_memory_region mr);

参数说明

表 1 参数说明

返回值

无

ubs_hcom_service_register_broken_handler ​

Service_RegisterChannelHandler

函数定义

注册通道Channel的回调函数，以处理通道建链和断连事件。

实现方法

void ubs_hcom_service_register_broken_handler(ubs_hcom_service service, ubs_hcom_service_channel_handler h,

ubs_hcom_service_channel_policy policy, uint64_t usrCtx);

参数说明

表 1 参数说明

返回值

uintptr_t，返回内部句柄地址。

ubs_hcom_service_register_idle_handler ​

函数定义

设置NetService的worker闲时回调函数。

实现方法

void ubs_hcom_service_register_idle_handler(ubs_hcom_service service, ubs_hcom_service_idle_handler h, uint64_t usrCtx);

参数说明

表 1 参数说明

返回值

内部回调函数地址。

ubs_hcom_service_register_handler ​

函数定义

注册回调函数，以处理通道双边发送完成、单边发送完成、双边收消息事件。

实现方法

void ubs_hcom_service_register_handler(ubs_hcom_service service, ubs_hcom_service_handler_type t, ubs_hcom_service_request_handler h,

uint64_t usrCtx);

参数说明

表 1 参数说明

返回值

无

ubs_hcom_service_set_enable_mrcache ​

函数定义

设置RegisterMemoryRegion是否将mr放入pgTable管理。

实现方法

void ubs_hcom_service_set_enable_mrcache(ubs_hcom_service service, bool enableMrCache);

参数说明

表 1 参数说明

返回值

无

ubs_hcom_channel_refer ​

函数定义

将此NetChannel增加一次引用计数。

实现方法

void ubs_hcom_channel_refer(ubs_hcom_channel channel)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_channel_derefer ​

函数定义

将此ubs_hcom_channel 减少一次引用计数。

实现方法

void ubs_hcom_channel_derefer(ubs_hcom_channel channel)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_channel_send ​

函数定义

发送双边消息，不需要对端回复。

实现方法

int ubs_hcom_channel_send(ubs_hcom_channel channel, ubs_hcom_channel_request req, ubs_hcom_channel_callback *cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_call ​

函数定义

发送双边消息并等待回复，需要对端配合Reply使用。

实现方法

int ubs_hcom_channel_call(ubs_hcom_channel channel, ubs_hcom_channel_request req, ubs_hcom_channel_response *rsp, ubs_hcom_channel_callback *cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_reply ​

函数定义

回复双边消息，接收端配合Call使用。

实现方法

int ubs_hcom_channel_reply(ubs_hcom_channel channel, ubs_hcom_channel_request req, ubs_hcom_channel_reply_context ctx, ubs_hcom_channel_callback*cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_put ​

数据定义

发送单边写请求。

实现方法

int ubs_hcom_channel_put(ubs_hcom_channel channel, ubs_hcom_oneside_request req, ubs_hcom_channel_callback*cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_get ​

函数定义

发送单边读请求。

实现方法

int ubs_hcom_channel_get(ubs_hcom_channel channel, ubs_hcom_oneside_request req, ubs_hcom_channel_callback*cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_recv ​

函数定义

只用于接收RNDV请求。

实现方法

int ubs_hcom_channel_recv(ubs_hcom_channel channel, ubs_hcom_service_context ctx, uintptr_t address, uint32_t size, ubs_hcom_channel_callback *cb);

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_set_flowctl_cfg ​

函数定义

给此NetChannel设置流控参数。

实现方法

int Channel_ConfigFlowControl(ubs_hcom_channel channel, ubs_hcom_flowctl_opts options)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_channel_set_timeout ​

函数定义

设置ubs_hcom_channel 的双边超时时间。

实现方法

void ubs_hcom_channel_set_timeout(ubs_hcom_channel channel, int32_t timeout)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_channel_set_twoside_threshold ​

函数定义

设置拆包和rndv的阈值。

实现方法

int ubs_hcom_channel_set_twoside_threshold(ubs_hcom_channel channel, ubs_hcom_twoside_threshold threshold);

参数说明

表 1 参数说明

返回值

无

ubs_hcom_channel_get_id ​

函数定义

获取channelId。

实现方法

int ubs_hcom_channel_get_id(ubs_hcom_channel channel);

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_channel ​

函数定义

通过ctx获得ubs_hcom_channel。

实现方法

int ubs_hcom_context_get_channel(ubs_hcom_service_context context, ubs_hcom_channel *channel);

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_type ​

函数定义

通过ctx获得操作类型。

实现方法

int ubs_hcom_context_get_type(ubs_hcom_service_context context, ubs_hcom_service_context_type *type);

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_result ​

函数定义

通过ctx获得操作结果。

实现方法

int ubs_hcom_context_get_result(ubs_hcom_service_context context, int *result)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_rspctx ​

函数定义

通过ctx获得回复消息所需的rspCtx。

实现方法

int ubs_hcom_context_get_rspctx(ubs_hcom_service_context context, ubs_hcom_channel_reply_context *rspCtx);

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_opcode ​

函数定义

通过ctx获得OpCode。

实现方法

uint16_t ubs_hcom_context_get_opcode(ubs_hcom_service_context context);

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_context_get_data ​

函数定义

通过ctx获得接收到的消息。

实现方法

void *ubs_hcom_context_get_data(ubs_hcom_service_context context)

参数说明

表 1 参数说明

返回值

返回接收到的消息。

ubs_hcom_context_get_datalen ​

函数定义

通过ctx获得接收到的消息长度。

实现方法

uint32_t ubs_hcom_context_get_datalen(ubs_hcom_service_context context)

参数说明

表 1 参数说明

返回值

返回接收到的消息长度。

传输层API ​

ubs_hcom_driver_create ​

函数定义

根据类型和名字创建一个传输层的HcomDriver对象。

实现方法

int ubs_hcom_driver_create(ubs_hcom_driver_type t, const char *name, uint8_t startOobSvr, ubs_hcom_driver *driver)

参数说明

表 1 参数说明

返回值

返回值为0则表示创建HcomDriver成功。

ubs_hcom_driver_set_ipport ​

函数定义

给HcomDriver对象设置OOB的IP和Port。

实现方法

void ubs_hcom_driver_set_ipport(ubs_hcom_driver driver, const char *ip, uint16_t port)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_get_ipport ​

函数定义

得到HcomDriver对象的OOB的IP和Port。

实现方法

bool ubs_hcom_driver_get_ipport(ubs_hcom_driver driver, char ***ipArray, uint16_t **portArray, int *length)

参数说明

表 1 参数说明

返回值

返回值为true则表示成功。

ubs_hcom_driver_set_udsname ​

函数定义

给HcomDriver对象设置的OOB type为UDS时的name。

实现方法

void ubs_hcom_driver_set_udsname(ubs_hcom_driver driver, const char *name)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_add_uds_opt ​

函数定义

给HcomDriver对象设置的OOB type为UDS时的name和一些参数。

实现方法

void ubs_hcom_driver_add_uds_opt(ubs_hcom_driver driver, ubs_hcom_driver_uds_listen_opts option)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_add_oob_opt ​

函数定义

设置HcomDriver对象的OOB的IP和Port。

实现方法

void ubs_hcom_driver_add_oob_opt(ubs_hcom_driver driver, ubs_hcom_driver_listen_opts options)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_initizalize ​

函数定义

根据类型和名字创建一个传输层的HcomDriver对象。

实现方法

int ubs_hcom_driver_initizalize(ubs_hcom_driver driver, ubs_hcom_driver_opts options)

参数说明

表 1 参数说明

返回值

返回值为0则表示初始化HcomDriver成功。

ubs_hcom_driver_start ​

函数描述

根据类型和名字创建一个传输层的HcomDriver对象。

函数定义

int ubs_hcom_driver_start(ubs_hcom_driver driver)

参数说明

表 1 参数说明

返回值

返回值为0则表示开启HcomDriver成功。

ubs_hcom_driver_connect ​

函数定义

建立与远程服务器的连接，并返回连接创建的EP。

实现方法

• int ubs_hcom_driver_connect(ubs_hcom_driver driver, const char *payloadData, ubs_hcom_endpoint *ep, uint32_t flags)
• int ubs_hcom_driver_connect_with_grpno(ubs_hcom_driver driver, const char *payloadData, ubs_hcom_endpoint *ep, uint32_t flags, uint8_t serverGrpNo, uint8_t clientGrpNo)
• int ubs_hcom_driver_connect_to_ipport(ubs_hcom_driver driver, const char *serverIp, uint16_t serverPort, const char *payloadData, ubs_hcom_endpoint *ep, uint32_t flags)
• int ubs_hcom_driver_connect_to_ipport_with_grpno(ubs_hcom_driver driver, const char *serverIp, uint16_t serverPort, const char *payloadData, ubs_hcom_endpoint *ep, uint32_t flags, uint8_t serverGrpNo, uint8_t clientGrpNo)
• int ubs_hcom_driver_connect_to_ipport_with_ctx(ubs_hcom_driver driver, const char *serverIp, uint16_t serverPort, const char *payloadData, ubs_hcom_endpoint *ep, uint32_t flags, uint8_t serverGrpNo, uint8_t clientGrpNo, uint64_t ctx)

参数说明

表 1 参数说明

返回值

返回值为0则表示连接成功。

ubs_hcom_driver_stop ​

函数定义

停止服务和内部启动的线程。

实现方法

void ubs_hcom_driver_stop(ubs_hcom_driver driver)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_uninitialize ​

函数定义

清理服务创建时的相关资源。

实现方法

void ubs_hcom_driver_uninitialize(ubs_hcom_driver driver)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_destroy ​

函数定义

销毁HcomDriver。

实现方法

void ubs_hcom_driver_destroy(ubs_hcom_driver driver)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_register_ep_handler ​

函数定义

注册EP的回调函数，以处理EP建链和断连事件。并把回调函数句柄放入全局句柄管理器。

实现方法

uintptr_t ubs_hcom_driver_register_ep_handler(ubs_hcom_driver driver, ubs_hcom_ep_handler_type t, ubs_hcom_ep_handler h, uint64_t usrCtx)

参数说明

表 1 参数说明

返回值

uintptr_t类型，返回内部句柄地址。

ubs_hcom_driver_register_op_handler ​

函数定义

注册回调函数，以处理通道双边发送完成、单边发送完成、双边收消息事件。并把回调函数句柄放入全局句柄管理器。

实现方法

uintptr_t ubs_hcom_driver_register_op_handler(ubs_hcom_driver driver, ubs_hcom_op_handler_type t, ubs_hcom_request_handler h, uint64_t usrCtx)

参数说明

表 1 参数说明

返回值

uintptr_t类型，返回内部句柄地址。

ubs_hcom_driver_register_idle_handler ​

函数定义

给HcomDriver对象设置EP闲时回调函数。并把回调函数句柄放入全局句柄管理器。

实现方法

uintptr_t ubs_hcom_driver_register_idle_handler(ubs_hcom_driver driver, ubs_hcom_idle_handler h, uint64_t usrCtx)

参数说明

表 1 参数说明

返回值

内部回调函数地址。

ubs_hcom_driver_register_secinfo_provider ​

函数定义

给HcomDriver对象设置EP安全信息提供函数。

实现方法

uintptr_t ubs_hcom_driver_register_secinfo_provider(ubs_hcom_driver driver, ubs_hcom_secinfo_provider provider)

参数说明

表 1 参数说明

返回值

内部回调函数地址。

ubs_hcom_driver_register_secinfo_validator ​

函数定义

给HcomDriver对象设置EP安全信息校验函数。

实现方法

uintptr_t ubs_hcom_driver_register_secinfo_validator(ubs_hcom_driver driver, ubs_hcom_secinfo_validator validator)

参数说明

表 1 参数说明

返回值

内部回调函数地址。

ubs_hcom_driver_unregister_ep_handler ​

函数定义

从全局回调函数句柄管理器中去掉某一个回调函数句柄。

实现方法

void ubs_hcom_driver_unregister_ep_handler(ubs_hcom_ep_handler_type t, uintptr_t handle)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_unregister_op_handler ​

函数定义

从全局回调函数句柄管理器中去掉某一个回调函数句柄。

实现方法

void ubs_hcom_driver_unregister_op_handler(ubs_hcom_op_handler_type t, uintptr_t handle)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_unregister_idle_handler ​

函数定义

从全局回调函数句柄管理器中去掉某一个回调函数句柄。

实现方法

void ubs_hcom_driver_unregister_idle_handler(uintptr_t handle)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_create_memory_region ​

函数定义

通过HcomDriver对象来创建一个Memory region。

实现方法

int ubs_hcom_driver_create_memory_region(ubs_hcom_driver driver, uint64_t size, ubs_hcom_memory_region *mr)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_driver_create_assign_memory_region ​

函数定义

通过HcomDriver对象来创建一个Memory region。

实现方法

int ubs_hcom_driver_create_assign_memory_region(ubs_hcom_driver driver, uintptr_t address, uint64_t size, ubs_hcom_memory_region *mr)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_driver_destroy_memory_region ​

函数定义

通过HcomDriver对象来销毁一个Memory region。

实现方法

void ubs_hcom_driver_destroy_memory_region(ubs_hcom_driver driver, ubs_hcom_memory_region mr)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_driver_get_memory_region_info ​

函数定义

获取一个MR的信息。

实现方法

int ubs_hcom_driver_get_memory_region_info(ubs_hcom_memory_region mr, ubs_hcom_memory_region_info *info)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_ep_set_context ​

函数定义

给EP设置本端回调函数可使用的ctx。

实现方法

void ubs_hcom_ep_set_context(ubs_hcom_endpoint ep, uint64_t ctx)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_ep_get_context ​

函数定义

获得EP的ctx。

实现方法

uint64_t ubs_hcom_ep_get_context(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

EP的context。

ubs_hcom_ep_get_worker_idx ​

函数定义

获取EP所在的worker group的worker索引。

实现方法

uint16_t ubs_hcom_ep_get_worker_idx(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

返回worker group的worker索引。

ubs_hcom_ep_get_workergroup_idx ​

函数定义

获取EP所在的worker group索引。

实现方法

uint8_t ubs_hcom_ep_get_workergroup_idx(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

返回worker group索引。

ubs_hcom_ep_get_listen_port ​

函数定义

获取EP建链时所监听的端口号。

实现方法

uint32_t ubs_hcom_ep_get_listen_port(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

返回端口号。

ubs_hcom_ep_version ​

函数定义

获取EP的版本。

实现方法

uint8_t ubs_hcom_ep_version(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

返回EP的版本。

ubs_hcom_ep_set_timeout ​

函数定义

设置EP的超时时间。

实现方法

void ubs_hcom_ep_set_timeout(ubs_hcom_endpoint ep, int32_t timeout)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_ep_post_send ​

函数定义

向对端发送一个带有op信息的请求。

实现方法

int ubs_hcom_ep_post_send(ubs_hcom_endpoint ep, uint16_t opcode, ubs_hcom_send_request *req)

参数说明

表 1 参数说明

返回值

返回值为0则表示发送成功。

ubs_hcom_ep_post_send_with_opinfo ​

函数定义

使用EP发送PostSend消息，带有opInfo。

实现方法

int ubs_hcom_ep_post_send_with_opinfo(ubs_hcom_endpoint ep, uint16_t opcode, Hcom_SendRequest *req, ubs_hcom_opinfo *opInfo)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_ep_post_send_with_seqno ​

函数定义

使用EP发送PostSend消息，带有seqNo。

实现方法

int ubs_hcom_ep_post_send_with_seqno(ubs_hcom_endpoint ep, uint16_t opcode, ubs_hcom_send_request *req, uint32_t replySeqNo)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_ep_post_read ​

函数定义

向对端发送一个读请求。

实现方法

int ubs_hcom_ep_post_read(ubs_hcom_endpoint ep, ubs_hcom_readwrite_request *req)

参数说明

表 1 参数说明

返回值

返回值为0则表示读成功。

ubs_hcom_ep_post_write ​

函数定义

向对端发送一个写请求。

实现方法

int ubs_hcom_ep_post_write(ubs_hcom_endpoint ep, ubs_hcom_readwrite_request *req)

参数说明

表 1 参数说明

返回值

返回值为0则表示写成功。

ubs_hcom_ep_wait_completion ​

函数定义

等待send，read，write消息完成，只有在EP是NET_EP_SELF_POLLING时生效。

实现方法

int ubs_hcom_ep_wait_completion(ubs_hcom_endpoint ep, int32_t timeout)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_ep_receive ​

函数定义

接收对端发送过来的消息。

实现方法

int ubs_hcom_ep_receive(ubs_hcom_endpoint ep, int32_t timeout, ubs_hcom_response_context **ctx)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_ep_refer ​

函数定义

给EP增加一次引用。

实现方法

void ubs_hcom_ep_refer(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_ep_close ​

函数定义

关闭EP。

实现方法

void ubs_hcom_ep_close(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_ep_destroy ​

函数定义

销毁EP。

实现方法

void ubs_hcom_ep_destroy(ubs_hcom_endpoint ep)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_err_str ​

函数定义

得到errorCode的解释。

实现方法

const char *ubs_hcom_err_str(int16_t errCode)

参数说明

表 1 参数说明

返回值

返回错误码翻译。

ubs_hcom_mem_allocator_create ​

函数定义

创建一个内存分配器。

实现方法

int ubs_hcom_mem_allocator_create(ubs_hcom_memory_allocator_type t, ubs_hcom_memory_allocator_options *options, ubs_hcom_memory_allocator *allocator)

参数说明`

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_mem_allocator_destroy ​

函数定义

销毁一个内存分配器。

实现方法

int ubs_hcom_mem_allocator_destroy(ubs_hcom_memory_allocator allocator)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_mem_allocator_set_mr_key ​

函数定义

给分配器设置memory region key。

实现方法

int ubs_hcom_mem_allocator_set_mr_key(ubs_hcom_memory_allocator allocator, uint32_t mrKey)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_mem_allocator_get_offset ​

函数定义

得到地址在分配器内存的偏移值。

实现方法

int ubs_hcom_mem_allocator_get_offset(ubs_hcom_memory_allocator allocator, uintptr_t address, uintptr_t *offset)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_mem_allocator_get_free_size ​

函数定义

得到分配器剩余的内存大小。

实现方法

int ubs_hcom_mem_allocator_get_free_size(ubs_hcom_memory_allocator allocator, uintptr_t *size)

参数说明

表 1 参数说明

返回值

返回0为成功。

ubs_hcom_mem_allocator_allocate ​

函数定义

从内存分配器中分配出指定大小的内存。

实现方法

int ubs_hcom_mem_allocator_allocate(ubs_hcom_memory_allocator allocator, uint64_t size, uintptr_t *address, uint32_t *key)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_mem_allocator_free ​

函数定义

将从内存分配器中分配的内存释放给分配器。

实现方法

int ubs_hcom_mem_allocator_free(ubs_hcom_memory_allocator allocator, uintptr_t address)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

ubs_hcom_set_log_handler ​

函数定义

设置外部日志。

实现方法

void ubs_hcom_set_log_handler(ubs_hcom_log_handler h)

参数说明

表 1 参数说明

返回值

无

ubs_hcom_check_local_supporr ​

函数定义

校验本机是否支持所提供协议，若为RDMA协议且支持的情况下，会返回设备信息。

实现方法

int ubs_hcom_check_local_supporr(ubs_hcom_driver_type t, ubs_hcom_device_info *info)

参数说明

表 1 参数说明

返回值

返回值为1则表示支持此协议。

ubs_hcom_get_remote_uds_info ​

函数定义

仅支持服务端且OOB type为UDS时，查询此EP的对端UDS ID信息。

实现方法

int ubs_hcom_get_remote_uds_info(ubs_hcom_endpoint ep, ubs_hcom_uds_id_info *idInfo)

参数说明

表 1 参数说明

返回值

返回值为0则表示成功。

高级API参考 ​

C++API ​

服务层 ​

UBSHcomService::AddWorkerGroup ​

函数定义

向Service中增加内存池。

实现说明

void UBSHcomService::AddWorkerGroup(uint16_t workerGroupId, uint32_t threadCount,const std::pair<uint32_t, uint32_t> &cpuIdsRange, int8_t priority = 0, uint16_t multirailIdx = 0);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::AddListener ​

函数定义

向Service中增加listener。

实现说明

void UBSHcomService::AddListener(const std::string &url, uint16_t workerCount = UINT16_MAX);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetConnectLBPolicy ​

函数定义

设置建链负载均衡策略

实现说明

void UBSHcomService::SetConnectLBPolicy(UBSHcomServiceLBPolicy lbPolicy)

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetUBSHcomTlsOptions ​

函数定义

设置TLS可选配置项。

实现说明

void UBSHcomService::SetUBSHcomTlsOptions(const UBSHcomTlsOptions &opt);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetConnSecureOpt ​

函数定义

链接安全配置项

实现说明

void UBSHcomService::SetConnSecureOpt(const UBSHcomConnSecureOptions &opt);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetTcpUserTimeOutSec ​

函数定义

设置TCP套接字选项TCP_USER_TIMEOUT。

实现说明

void UBSHcomService::SetTcpUserTimeOutSec(uint16_t timeOutSec);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetTcpSendZCopy ​

函数定义

设置TCP发送是否要做内存拷贝。

实现说明

void UBSHcomService::SetTcpSendZCopy(bool tcpSendZCopy);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetDeviceIpMask ​

函数定义

设置设备ipMask，用于rdma/ub。

实现说明

void UBSHcomService::SetDeviceIpMask(const std::vector<std::string> &ipMasks);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetDeviceIpGroups ​

函数定义

设置设备ipGroup。

实现说明

void UBSHcomService::SetDeviceIpGroups(const std::vector<std::string> &ipGroups);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetCompletionQueueDepth ​

函数定义

设置cq队列深度。

实现说明

void UBSHcomService::SetCompletionQueueDepth(uint16_t depth);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetSendQueueSize ​

函数定义

设置发送队列深度。

实现说明

void UBSHcomService::SetSendQueueSize(uint32_t sqSize);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetRecvQueueSize ​

函数定义

设置接收队列深度。

实现说明

void UBSHcomService::SetRecvQueueSize(uint32_t rqSize);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetPollingBatchSize ​

函数定义

设置批量polling的大小。

实现说明

void UBSHcomService::SetPollingBatchSize(uint16_t pollSize);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetEventPollingTimeOutUs ​

函数定义

设置event polling的超时时间。

实现说明

void UBSHcomService::SetEventPollingTimeOutUs(uint16_t pollTimeout);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetTimeOutDetectionThreadNum ​

函数定义

设置周期任务处理线程数。

实现说明

void UBSHcomService::SetTimeOutDetectionThreadNum(uint32_t threadNum);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetMaxConnectionCount ​

函数定义

设置最大链接数。

实现说明

void UBSHcomService::SetMaxConnectionCount(uint32_t maxConnCount);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetUBSHcomHeartBeatOptions ​

函数定义

设置心跳参数配置项。

实现说明

void UBSHcomService::SetUBSHcomHeartBeatOptions(const UBSHcomHeartBeatOptions &opt);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetUBSHcomMultiRailOptions ​

函数定义

设置多路径参数配置项。

实现说明

void UBSHcomService::SetUBSHcomMultiRailOptions(const UBSHcomMultiRailOptions &opt);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetQueuePrePostSize ​

函数定义

设置提前下发wr的数量，不设置的话默认64。

实现说明

void UBSHcomService::SetQueuePrePostSize(uint32_t prePostSize);

参数说明

表 1 参数说明

返回值

无

UBSHcomService::SetMaxSendRecvDataCount ​

函数定义

设置发送数据块最大数量，不设置的话默认8192。

实现说明

void SetMaxSendRecvDataCount(uint32_t maxSendRecvDataCount);

参数说明

表 1 参数说明

返回值

无

UBSHcomRegMemoryRegion::GetMemoryKey ​

函数定义

获得所有内存池的keys。

实现说明

void UBSHcomRegMemoryRegion::GetMemoryKey(UBSHcomMemoryKey &mrKey)；

参数说明

表 1 参数说明

返回值

无

UBSHcomRegMemoryRegion::GetAddress ​

函数定义

获得首个内存池地址。

实现说明

uintptr_t UBSHcomRegMemoryRegion::GetAddress()；

参数说明

无

返回值

地址值。

UBSHcomRegMemoryRegion::GetSize ​

函数定义

获得首个内存池长度。

实现说明

uint64_t UBSHcomRegMemoryRegion::GetSize()；

参数说明

无

返回值

内存池的长度。

UBSHcomRegMemoryRegion::GetHcomMrs ​

函数定义

获得内存池组。

实现说明

std::vector<UBSHcomMemoryRegionPtr>& UBSHcomRegMemoryRegion::GetHcomMrs()；

参数说明

无

返回值

返回std::vector<UBSHcomMemoryRegionPtr>类型的数组。

UBSHcomNewCallback ​

函数定义

创建Callback函数。

实现说明

template <typename... Args> Callback *UBSHcomNewCallback(Args... args)；

参数说明

表 1 参数说明

返回值

返回Callback *函数。

传输层 ​

UBSHcomNetDriver::RegisterTLSCaCallback ​

接口使用方法 ​

函数定义

注册建链双向认证的回调函数，用于获取CA证书。

实现方法

void UBSHcomNetDriver::RegisterTLSCaCallback(const UBSHcomTLSCaCallback &cb);

参数说明

表 1 参数说明

返回值

无

代码样例

int Verify(void *x509, const char *path)
{
    return 0;
}

bool CACallback(const std::string &name, std::string &caPath, std::string &crlPath,
    UBSHcomPeerCertVerifyType &peerCertVerifyType, UBSHcomTLSCertVerifyCallback &cb)
{
    caPath = certPath + "/CA/cacert.pem";
    cb = std::bind(&Verify, std::placeholders::_1, std::placeholders::_2);
    return true;
}

driver->RegisterTLSCaCallback(std::bind(&CACallback, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4, std::placeholders::_5));

UBSHcomTLSCaCallback函数类型 ​

函数定义

using UBSHcomTLSCaCallback = std::function<bool(const std::string &name, std::string &capath, std::string &crlPath, UBSHcomPeerCertVerifyType &verifyPeerCert, UBSHcomTLSCertVerifyCallback &cb)>;

参数说明

表 1 参数说明

返回值

Bool类型，表示回调函数是否执行成功。

• 返回值为true：表示成功。
• 返回值为false：表示失败。

代码样例

bool CACallback(const std::string &name, std::string &caPath, std::string &crlPath,
    UBSHcomPeerCertVerifyType &peerCertVerifyType, UBSHcomTLSCertVerifyCallback &cb)
{
    caPath = certPath + "/CA/cacert.pem";
    cb = std::bind(&Verify, std::placeholders::_1, std::placeholders::_2);
    return true;
}

UBSHcomTLSCertVerifyCallback函数类型 ​

函数定义

using UBSHcomTLSCertVerifyCallback = std::function<int(void *, const char *)>;

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0表示证书验证成功。

UBSHcomNetDriver::RegisterTLSCertificationCallback ​

接口使用方法 ​

函数定义

注册建链双向认证的回调函数，用于获取公钥证书。

实现方法

void UBSHcomNetDriver::RegisterTLSCertificationCallback(const UBSHcomTLSCertificationCallback &cb);

参数说明

表 1 参数说明

返回值

无

代码样例

bool CertCallback(const std::string &name, std::string &value)
{
    value = certPath + "/client/cert.pem";
    return true;
}

driver->RegisterTLSCertificationCallback( std::bind(&CertCallback, std::placeholders::_1, std::placeholders::_2));

UBSHcomTLSCertificationCallback函数类型 ​

函数定义

using UBSHcomTLSCertificationCallback = std::function<bool(const std::string &name, std::string &path)>;

参数说明

表 1 参数说明

返回值

Bool类型，表示回调函数是否执行成功。

• 返回值为true：表示成功。
• 返回值为false：表示失败。

代码样例

bool CertCallback(const std::string &name, std::string &value)
{
    value = certPath + "/client/cert.pem";
    return true;
}

UBSHcomNetDriver::RegisterTLSPrivateKeyCallback ​

接口使用方法 ​

函数定义

注册建链双向认证的回调函数，用户获取私钥证书。

实现方法

void UBSHcomNetDriver::RegisterTLSPrivateKeyCallback(const UBSHcomTLSPrivateKeyCallback &cb);

参数说明

表 1 参数说明

返回值

无

代码样例

void Erase(void *pass, int len) {}

bool PrivateKeyCallback(const std::string &name, std::string &value, void *&keyPass, int &len, UBSHcomTLSEraseKeypass &erase)
{
    static char content[] = "xxxx";
    keyPass = reinterpret_cast<void *>(content);
    len = sizeof(content);
    value = certPath + "/client/key.pem";
    erase = std::bind(&Erase, std::placeholders::_1, std::placeholders::_2);
    return true;
}

driver->RegisterTLSPrivateKeyCallback(std::bind(&PrivateKeyCallback, std::placeholders::_1,  std::placeholders::_2, std::placeholders::_3, std::placeholders::_4, std::placeholders::_5));

UBSHcomTLSPrivateKeyCallback函数类型 ​

函数定义

using UBSHcomTLSPrivateKeyCallback = std::function<bool(const std::string &name, std::string &path, void *&password, int &length, UBSHcomTLSEraseKeypass &erase)>;

参数说明

表 1 参数说明

返回值

Bool类型，表示回调函数是否执行成功。

• 返回值为true表示成功。
• 返回值为false表示失败。

代码样例

void Erase(void *pass, int len) {}

bool PrivateKeyCallback(const std::string &name, std::string &value, void *&keyPass, int &len, UBSHcomTLSEraseKeypass &erase)
{
    static char content[] = "xxxx";
    keyPass = reinterpret_cast<void *>(content);
    len = sizeof(content);
    value = certPath + "/client/key.pem";
    erase = std::bind(&Erase, std::placeholders::_1, std::placeholders::_2);
    return true;
}

UBSHcomTLSEraseKeypass函数类型 ​

函数定义

using UBSHcomTLSEraseKeypass = std::function<void(void *, int)>;

参数说明

表 1 参数说明

返回值

无

UBSHcomNetDriver::RegisterPskUseSessionCb ​

接口使用方法 ​

函数定义

供Client端注册PSK回调函数。

实现方法

void UBSHcomNetDriver::RegisterPskUseSessionCb(const UBSHcomPskUseSessionCb &cb)

参数说明

表 1 参数说明

返回值

无。

UBSHcomPskUseSessionCb函数类型 ​

函数定义

using UBSHcomPskUseSessionCb = std::function<int(void *ssl, const void *md, const unsigned char **id, size_t *idlen, void **sess)>;

参数说明

表 1 参数说明

返回值

int类型。

• 1：表示回调函数执行成功。
• 0：表示回调函数执行失败。

UBSHcomNetDriver::RegisterPskFindSessionCb ​

接口使用方法 ​

函数定义

供Server端注册PSK回调函数。

实现方法

void UBSHcomNetDriver::RegisterPskFindSessionCb(const UBSHcomPskFindSessionCb &cb)

参数说明

表 1 参数说明

返回值

无。

UBSHcomPskFindSessionCb函数类型 ​

函数定义

using UBSHcomPskFindSessionCb = std::function<int(void *ssl, const unsigned char *identity, size_t identity_len, void **sess)>;

参数说明

表 1 参数说明

返回值

int类型，1表示回调函数执行成功，0表示执行失败。

UBSHcomNetDriver::RegisterEndpointSecInfoProvider ​

函数定义

给UBSHcomNetDriver对象设置EP安全信息提供函数。

实现方法

void UBSHcomNetDriver::RegisterEndpointSecInfoProvider(const UBSHcomNetDriverEndpointSecInfoProvider &provider)

参数说明

表 1 参数说明

返回值

无

UBSHcomNetDriver::RegisterEndpointSecInfoValidator ​

函数定义

给UBSHcomNetDriver对象设置EP安全信息校验函数。

实现方法

void UBSHcomNetDriver::RegisterEndpointSecInfoValidator(const UBSHcomNetDriverEndpointSecInfoValidator &validator)

参数说明

表 1 参数说明

返回值

无

UBSHcomNetEndpoint::PostSendRawSgl ​

函数定义

发送一个不带opcode和header的请求给对方，对方将触发新的请求回调，也不带opcode和header，当客户有自己定义的header时可以使用。

实现方法

NResult UBSHcomNetEndpoint::PostSendRawSgl(const UBSHcomNetTransSglRequest &request,uint32_t seqNo)

参数说明

表 1 参数说明

返回值

返回值为0则表示发送消息成功。

UBSHcomNetEndpoint::ReceiveRaw ​

函数定义

获得发送请求应答的响应，不包含header和opCode，默认超时生效。

实现方法

NResult UBSHcomNetEndpoint::ReceiveRaw(UBSHcomNetResponseContext &ctx)

参数说明

表 1 参数说明

返回值

返回值为0则表示发送消息成功。

UBSHcomNetEndpoint::EstimatedEncryptLen ​

函数定义

输入原始数据大小的估计加密长度。

实现方法

uint64_t UBSHcomNetEndpoint::EstimatedEncryptLen(uint64_t rawLen)

参数说明

表 1 参数说明

返回值

返回uint64_t类型，表示数据加密长度。

UBSHcomNetEndpoint::Encrypt ​

函数定义

加密数据。

实现方法

NResult UBSHcomNetEndpoint::Encrypt(const void *rawData, uint64_t rawLen, void *cipher, uint64_t &cipherLen)

参数说明

表 1 参数说明

返回值

返回值为0则表示加密成功。

UBSHcomNetEndpoint::EstimatedDecryptLen ​

函数定义

输出原始数据大小。

实现方法

uint64_t UBSHcomNetEndpoint::EstimatedDecryptLen(uint64_t cipherLen)

参数说明

表 1 参数说明

返回值

返回uint64_t类型，表示解密后的原始数据长度。

UBSHcomNetEndpoint::Decrypt ​

函数定义

解密数据。

实现方法

NResult UBSHcomNetEndpoint::Decrypt(const void * cipher, uint64_t cipherLen, void *rawData, uint64_t &rawLen)

参数说明

表 1 参数说明

返回值

返回值为0则表示解密成功。

UBSHcomNetEndpoint::SendFds ​

函数定义

发送共享文件的句柄，该接口只支持在SHM协议下使用。

实现方法

NResult UBSHcomNetEndpoint::SendFds(int fds[], uint32_t len)

参数说明

表 1 参数说明

返回值

返回值为0则表示句柄发送成功。

UBSHcomNetEndpoint::ReceiveFds ​

函数定义

接收共享文件的句柄，该接口只支持在SHM协议下使用。

实现方法

NResult UBSHcomNetEndpoint::ReceiveFds(int fds[], uint32_t len)

参数说明

表 1 参数说明

返回值

返回值为0则表示句柄发送成功。

UBSHcomNetOutLogger::Instance ​

函数定义

创建外部日志对象。

实现方法

static UBSHcomNetOutLogger *UBSHcomNetOutLogger::Instance()

参数说明

无

返回值

返回外部日志导入对象。

UBSHcomNetOutLogger::SetLogLevel ​

函数定义

• 设置外部日志对象日志等级，设置为环境变量HCOM_SET_LOG_LEVEL。

• 设置外部日志对象日志等级，大于等于此等级的日志将被打印。

  日志等级如下：

  • 0：debug
  • 1：info
  • 2：warn
  • 3：error

实现方法

• static void UBSHcomNetOutLogger::SetLogLevel()
• static void UBSHcomNetOutLogger::SetLogLevel(int level)

参数说明

表 1 参数说明

返回值

无

UBSHcomNetOutLogger::SetExternalLogFunction ​

函数定义

设置外部日志对象的外部日志函数。

实现方法

void UBSHcomNetOutLogger::SetExternalLogFunction(ExternalLog func)

参数说明

表 1 参数说明

返回值

无

[!NOTICE]说明

数据类型解释如下： typedef void (*ExternalLog)(int level, const char *msg).

UBSHcomNetOutLogger::Print ​

函数定义

打印日志。

实现方法

static inline void UBSHcomNetOutLogger::Print(int level, const char *msg)

参数说明

表 1 参数说明

返回值

无

UBSHcomNetOutLogger::Log ​

函数定义

打印日志，如果有外部日志函数，则使用外部日志函数。

实现方法

void UBSHcomNetOutLogger::Log(int level, const std::ostringstream &oss) const

参数说明

表 1 参数说明

返回值

无

UBSHcomNetOutLogger::GetLogLevel ​

函数定义

获取当日志打印等级。

实现方法

int UBSHcomNetOutLogger::GetLogLevel()

参数说明

无

返回值

返回日志等级。

UBSHcomNetAtomicState::Get ​

函数定义

获得原子状态。

实现方法

T Get() const

参数说明

无

返回值

获得原子状态。

UBSHcomNetAtomicState::Set ​

函数定义

设置原子状态。

实现方法

void Set(T newState)

参数说明

表 1 参数说明

返回值

无

UBSHcomNetAtomicState::CAS ​

函数定义

原子状态比较并交换。

实现方法

bool CAS(T oldState, T newState)

参数说明

表 1 参数说明

返回值

布尔值。检查mState是否等于oldState。如果是，则将其设置为newState，并返回true；否则不做任何修改，返回false。

UBSHcomNetAtomicState::Compare ​

函数定义

原子状态比较。

实现方法

bool Compare(T state)

参数说明

表 1 参数说明

返回值

布尔值。检查mState是否等于state，如果是返回true；否则返回false。

组播API ​

PublisherService::Create ​

函数定义

创建发布者服务。

实现方法

static PublisherService *Create(const std::string &name, const MulticastServiceOptions &opt = {})

参数说明

表 1 参数说明

返回值

成功时返回创建好的PublisherService实例，失败时返回空。

PublisherService::Detroy ​

函数定义

销毁发布者服务。

实现方法

static int32_t Destroy(const std::string &name)

参数说明

表 1 参数说明

返回值

in32_t。成功时返回0，失败时返回错误码。

PublisherService::Start ​

函数定义

启动发布者服务。

实现方法

int32_t Start()

参数说明

无。

返回值

in32_t。成功时返回0，失败时返回错误码。

PublisherService::Stop ​

函数定义

停止发布者服务。

实现方法

void Stop()

参数说明

无。

返回值

无。

PublisherService::CreatePublisher ​

函数定义

创建发布者publisher。

实现方法

int32_t CreatePublisher(NetRef<Publisher> &publisher)

参数说明

表 1 参数说明

返回值

in32_t。成功时返回0，失败时返回错误码。

PublisherService::DestroyPublisher ​

函数定义

销毁发布者publisher。

实现方法

void DestroyPublisher(NetRef<Publisher> &publisher)

参数说明

表 1 参数说明

返回值

无。

PublisherService::Bind ​

函数定义

绑定监听url，指定监听的类型及url。

实现方法

int32_t Bind(const std::string &listenerUrl, const NewSubscriptionHandler &handler, const int cpuId = -1)

参数说明

表 1 参数说明

返回值

in32_t。成功时返回0，失败时返回错误码。

PublisherService::GetConfig ​

函数定义

获取MulticastConfig，用于做高级配置。

实现方法

MulticastConfig &GetConfig()

参数说明

无。

返回值

MulticastConfig&。返回MulticastConfig组播配置对象。

PublisherService::RegisterSubscriptionExceptionHandler ​

函数定义

注册SubscriptionException回调函数。

实现方法

void RegisterSubscriptionExceptionHandler(const SubscriptionExceptionHandler &handler)

参数说明

表 1 参数说明

返回值

无。

PublisherService::RegisterBrokenHandler ​

函数定义

注册Broken断链回调函数。

实现方法

void RegisterBrokenHandler(const MulticastEpBrokenHandler &handler)

参数说明

表 1 参数说明

返回值

无。

PublisherService::RegisterSendHandler ​

函数定义

注册发送回调函数。

实现方法

void RegisterSendHandler(const MulticastReqPostedHandler &handler)

参数说明

表 1 参数说明

返回值

无。

PublisherService::RegisterPubRecvHandler ​

函数定义

注册发布者接收回调函数。

实现方法

void RegisterPubRecvHandler(const MulticastPubReqRecvHandler &handler)

参数说明

表 1 参数说明

返回值

无。

PublisherService::AddWorkerGroup ​

函数定义

添加WorkerGroup配置。

实现方法

void AddWorkerGroup(uint16_t workerGroupId, uint32_t threadCount, const std::pair<uint32_t, uint32_t> &cpuIdsRange, int8_t priority)

参数说明

表 1 参数说明

返回值

无。

PublisherService::RegisterMemoryRegion ​

函数定义

• 注册一个内存区域，内存将在组播内部分配。
• 将用户申请的内存，注册到组播内部。

实现方法

• SerResult RegisterMemoryRegion(uint64_t size, NetMemoryRegionPtr &mr)
• SerResult RegisterMemoryRegion(uintptr_t address, uint64_t size, NetMemoryRegionPtr &mr)

参数说明

表 1 参数说明

返回值

表示函数执行结果，返回值为0则表示注册成功。

PublisherService::DestroyMemoryRegion ​

函数定义

销毁内存区域。

实现方法

void DestroyMemoryRegion(NetMemoryRegionPtr &mr)

参数说明

表 1 参数说明

返回值

无。

Publisher::Call ​

函数定义

发布双边消息，需要订阅者回复。

实现方法

SerResult Call(const NetServiceOpInfo &opInfo, const MultiRequest &req, const MultiCastCallback *done)

参数说明

表 1 参数说明

返回值

SerResult。成功返回0，失败返回错误码。

Publisher::AddSubscription ​

函数定义

发布者添加订阅信息。

实现方法

bool AddSubscription(SubscriptionInfoPtr &info)

参数说明

表 1 参数说明

返回值

bool。成功返回true，失败返回false。

Publisher::DelSubscription ​

函数定义

发布者删除订阅信息。

实现方法

bool DelSubscription(SubscriptionInfoPtr &info)

参数说明

表 1 参数说明

返回值

bool。成功返回true，失败返回false。

Publisher::GetSubscriberNum ​

函数定义

发布者删除订阅者数量。

实现方法

uint32_t GetSubscriberNum()

参数说明

无。

返回值

uint32_t。返回订阅者数量。

Publisher::GetAllSubscriberInfo ​

函数定义

获取所有订阅者信息。

实现方法

std::vector<SubscriptionInfoPtr> GetAllSubscriberInfo()

参数说明

无。

返回值

vector。返回所有订阅者信息。

Publisher::GetSubscribeByEpId ​

函数定义

通过ep id获取订阅者信息。

实现方法

SubscriptionInfoPtr GetSubscribeByEpId(uint64_t id)

参数说明

表 1 参数说明

返回值

SubscriptionInfoPtr。返回获取到的订阅者信息。

Publisher::Initialize ​

函数定义

初始化发布者。

实现方法

SerResult Initialize(uintptr_t memPool, uintptr_t pubMemPool, uintptr_t periodicMgr, uint32_t ctxStoreCapacity, UBSHcomNetDriverProtocol protocol = UBSHcomNetDriverProtocol::RDMA)

参数说明

表 1 参数说明