【编程艺术】用 handle 形式设计 C 语言接口

  欢迎关注我的公众号 [极智视界]，获取我的更多笔记分享

  O_o   >_<   o_O   O_o   ~_~   o_O

  本文介绍一下怎么用 handle 形式设计 C 语言接口。

  接口的设计在协同开发工程落地中是必不可少的，对于 C++ 来说，用类成员函数做接口的比较多，对于 C 来说，我觉得用 handle 来设计接口很优雅，且网络上相关介绍资源并不多，故分享一下。

1、handle 是什么

  handle 也叫句柄，源于 Handle-C。要理解 handle，首先得理解指针，指针就像人的身份证，我们可以通过它来找到对应的真实对象。在 C 语言里有句话，叫做 一切皆为地址，当然指针也是地址，它指向对应对象的头位置。而句柄 handle 是一种指向指针的指针，通过句柄可以操作对象的所有方法，这么说可能比较抽象。举个例子，句柄就像一个手提包，当你拎起这个手提包的时候，包里的电脑、手机、笔、书本…这些结构体都被你一起拎起来了，你可以随时通过手提包里的手机去访问你手机里的照片、访问你电脑里的 vscode，甚至能通过手提包里手机的向日葵去远程访问你的电脑，没错，句柄就是这个作用。

2、用 handle 设计接口

  用句柄设计接口十分优雅，下面展示一下用句柄怎么设计接口。

/*====================== D E F I N E S ================*/ 
/* Channel Create Param */ 
typedef struct ImgChannelParam 
{
      
    int32_t width;          ///< 原始图像宽度
    int32_t height;         ///< 原始图像高度
    int32_t reserved[32];   ///< 保留字段
}ImgChannelParam; 

/* Config Param */ 
typedef struct ConfigParam 
{
      
    int32_t minThresh;       ///< 结果判断低阈值
    int32_t maxThresh;       ///< 结果判断高阈值
}ConfigParam; 

/* Process Input Param */ 
typedef struct ProcessParam 
{
      
    cv::Mat img;            ///< 原始输入图像
    cv::Rect roi;           ///< roi 
    int32_t reserved[32]; 
}ProcessParam; 

/* Process Output Param */ 
typedef struct ProcessResult 
{
      
    uint8_t *threshImg;    ///< 二值图
    uint8_t isOk;          ///< 是否合格
    int32_t reserved[32]; 
}ProcessResult; 

/*************************************************************** 
* @brief Init Memory 
* 
* @param [in] handle 
* @param [in] param 
* @return API_EXPORT int32_t  
* @note 模块内存分配及初始化
****************************************************************/ 
API_EXPORT int32_t CALL_METHOD Create(void **handle, ChannelParam *param); 

/*************************************************************** 
* @brief Get Config Param 
* 
* @param [in] handle 
* @param [in] param 
* @return API_EXPORT int32_t 
* @note 模块当前配置参数获取
****************************************************************/ 
API_EXPORT int32_t CALL_METHOD GetConfig(void *handle, ConfigParam *param); 

/*************************************************************** 
* @brief Set Config Param 
* 
* @param [in] handle 
* @param [in] param  
* @return API_EXPORT int32_t 
* @note 模块配置参数设置
****************************************************************/ 
API_EXPORT int32_t CALL_METHOD SetConfig(void *handle, ConfigParam *param); 

/*************************************************************** 
* @brief Process Algorithm 
*
* @param [in] handle 
* @param [in] param 
* @return API_EXPORT int32_t 
* @note 模块主函数
****************************************************************/ 
API_EXPORT int32_t CALL_METHOD Process(void *handle, ProcessParam *param, ProcessResult *result); 

/*************************************************************** 
* @brief Exit Algorithm 
* 
* @param [in] handle 
* @param [in] param 
* @return API_EXPORT int32_t 
* @note 模块退出
****************************************************************/ 
API_EXPORT int32_t CALL_METHOD Release(void *handle); 

  说明一下，Process 是主算法处理接口，Create 为内存开辟接口，内存相关的开辟只在 Create 中做，在 Process 中不存在内存的开辟动作，只对 Create 中申请好的内存进行操作，完了在 Release 释放内存。而 GetConfig 和 SetConfig 则用于算法参数的获取与配置。这套代码很清晰，且通用性较强，我个人很喜欢。

  关于 handle 的分享就到这了，其实也没说很多，主要侧重于展示了一套 handle 接口设计，希望能帮助到有需要的同学。

 【公众号传送】

《【编程艺术】用 handle 形式设计 C 语言接口》

扫描下方二维码即可关注我的微信公众号【极智视界】，获取更多AI经验分享，让我们用极致+极客的心态来迎接AI ！