分布式系统架构-samgr/source系统服务开发框架基础代码feature.c讲解

本篇概述

本篇主要讲解feature.h、feature_impl.h以及feature.c三个文件。这三个文件主要集中讲述了有关开发功能时，需要实现的功能的生命周期接口的一系列基础函数。总结来说：

• 它被用于开发服务功能
• 它提供了实现的功能的生命周期接口

代码框架

feature
├── 重要结构体与类
│ └── Feature
│ └── FeatureImpl
├── 静态内联函数
│ └── IsInvalidFeature
│ └── IsInvalidIUnknown
├── 功能接口类函数
│ └── SAMGR_AddInterface
│ └── SAMGR_DelInterface
│ └── SAMGR_GetInterface
│ └── SAMGR_IsNoInterface
│ └── FEATURE_CreateInstance
├── 功能函数（由开发人员提供）
│ └── GetName
│ └── OnInitialize
│ └── OnStop
│ └── OnMessage

feature.h

feature.h中主要定义了Feature基础功能类，同时对feature.c中定义的四个函数进行了函数声明。其中，基础功能类中的函数继承于marco的功能类当中，详细代码及标注如下：

/**
 * @brief Defines the base class of a feature.
 * 概述：定义了一个基础的功能类
 * You need to implement the pointer to the feature. \n
 * 你需要实现指向功能的指针
 * @since 1.0
 * @version 1.0
 */
struct Feature {
    /**
     * @brief Obtains a feature name.
     * 概述：获取功能名
     * This function is implemented by developers and called by Samgr during feature registration
     * and startup. 
     * 这个功能由开发人员实现，它在功能注册和打开时由Samgr调用
     *
     * @param feature Indicates the pointer to the feature.
     * 参数说明：feature表示它对应的指针
     * @return Returns a constant character string less than 16 bytes if the operation is
     * successful; returns <b>NULL</b> if the operation fails.
     * 返回值：如果操作成功，返回一个固定的小于16比特的字符，如果操作失败则返回空值
     * @since 1.0
     * @version 1.0
     */
    const char *(*GetName)(Feature *feature);

    /**
     * @brief Initializes a feature.
     * 概述：初始化功能
     * This function is implemented by developers. After Samgr dispatches tasks to a service, the
     * service calls this function in its own tasks. 
     * 这个功能由开发人员实现。Samgr将任务分派给服务后，服务在自己的任务中调用这个函数。
     *
     * @param feature Indicates the pointer to the feature.
     * @param parent Indicates the pointer to the {@link Service} to which the feature belongs.
     * @param identity Indicates the identity of a feature dispatched by the system.
     * 参数说明：parent代表功能对应的服务指针，identity代表由系统分派的功能ID
     * @since 1.0
     * @version 1.0
     */
    void (*OnInitialize)(Feature *feature, Service *parent, Identity identity);

    /**
     * @brief Stops a feature.
     * 概述：暂停一个功能
     * This function is implemented by developers and is called by Samgr when a feature is
     * deregistered to stop running services.
     * 这个函数是由开发人员实现的，Samgr在注销某个功能以停止运行服务时调用该函数。
     * 
     * @param feature Indicates the pointer to the feature.
     * @param identity Indicates the {@link Identity} of the feature to be stopped.
     * @since 1.0
     * @version 1.0
     */
    void (*OnStop)(Feature *feature, Identity identity);

    /**
     * @brief Processes a feature message.
     * 概述：处理一条功能信息
     * This function is implemented by developers to process requests sent by callers through
     * IUnknown.
     * 这个函数是由开发人员实现的，用于处理调用者通过IUnknown对外接口发送的请求。
     *
     * @param feature Indicates the pointer to the feature.
     * @param request Indicates the request message.
     * @return Returns <b>TRUE</b> if the processing is successful; returns <b>FALSE</b> if
     * the processing fails.
     * 参数说明：request代表请求消息
     * 如果处理成功返回TRUE，否则返回FLASE
     * 
     * @since 1.0
     * @version 1.0
     */
    BOOL (*OnMessage)(Feature *feature, Request *request);
};

/**
 * @brief Inherits from the macro of the feature class.
 * 概述：从macro继承的功能类
 * This macro provides the capability of inheriting the feature lifecycle. \n
 * 这个macro提供继承feature(功能)生命周期的能力
 */
#define INHERIT_FEATURE                                                         \
    const char *(*GetName)(Feature *feature);                                   \
    void (*OnInitialize)(Feature *feature, Service *parent, Identity identity); \
    void (*OnStop)(Feature *feature, Identity identity);                        \
    BOOL (*OnMessage)(Feature *feature, Request *request)

feature_impl.h

feature_impl.h中包含了在功能实现过程中对功能声明周期的控制接口相关函数的定义及声明，同时还定义了关键的一个结构体：FeatureImpl，它在功能的实现与调用中起到了至关重要的作用。详细代码及标注如下：

// 定义功能应用结构体
struct FeatureImpl {
    Feature *feature; //Feature：开发功能时，需要实现的功能的生命周期接口
    IUnknown *iUnknown; //基于IUnknown开发服务或功能的对外接口
};

// 内联静态函数，返回feature是否无效
inline static BOOL IsInvalidFeature(Feature *feature)
{
    //如果feature中任何一个相关量为空则返回1（无效）否则返回0（有效）
    return (feature == NULL || feature->GetName == NULL || feature->OnInitialize == NULL ||
            feature->OnMessage == NULL || feature->OnStop == NULL);
}

// 判断IUnknown是否无效
inline static BOOL IsInvalidIUnknown(IUnknown *iUnknown)
{
    return (iUnknown == NULL || iUnknown->QueryInterface == NULL || iUnknown->AddRef == NULL ||
            iUnknown->Release == NULL);
}

//函数声明：
//Samgr增加接口、删除接口、获取接口、判断是否存在接口、创建实例、创建功能性实例
BOOL SAMGR_AddInterface(FeatureImpl *featureImpl, IUnknown *iUnknown);
IUnknown *SAMGR_DelInterface(FeatureImpl *featureImpl);
IUnknown *SAMGR_GetInterface(FeatureImpl *featureImpl);
BOOL SAMGR_IsNoInterface(FeatureImpl *featureImpl);
FeatureImpl *FEATURE_CreateInstance(Feature *feature);

feature.c

feature.c中主要定义了增加、删除、获取、判断、创建feature功能性接口函数，可以发现，功能的地址以及接口的地址即接口的位置是整个功能体系运作的关键。详细代码及标注如下：

// 定义增加接口的SAMGR功能性函数
BOOL SAMGR_AddInterface(FeatureImpl *featureImpl, IUnknown *iUnknown)
{
    if (featureImpl == NULL || iUnknown == NULL || featureImpl->iUnknown != NULL) {
        return FALSE;
    }

    //将iUnKnown变量赋值到结构体featureImpl中
    featureImpl->iUnknown = iUnknown;
    return TRUE;
}

// 定义SAMGR删除接口函数
IUnknown *SAMGR_DelInterface(FeatureImpl *featureImpl)
{
    if (featureImpl == NULL) {
        return NULL;
    }
    //先定义一个iUnknown变量用于存储删除量
    IUnknown *iUnknown = featureImpl->iUnknown;
    featureImpl->iUnknown = NULL;
    return iUnknown;
}

//定义获取接口函数
IUnknown *SAMGR_GetInterface(FeatureImpl *featureImpl)
{
    if (featureImpl == NULL) {
        return NULL;
    }
    return featureImpl->iUnknown;
}

//定义判断接口是否存在函数
BOOL SAMGR_IsNoInterface(FeatureImpl *featureImpl)
{
    return (BOOL)(featureImpl == NULL || featureImpl->iUnknown == NULL);
}

//定义创建实例功能函数
FeatureImpl *FEATURE_CreateInstance(Feature *feature)
{
    if (feature == NULL) {
        return NULL;
    }
    FeatureImpl *featureImpl = (FeatureImpl *)SAMGR_Malloc(sizeof(FeatureImpl));
    if (featureImpl == NULL) {
        return NULL;
    }
    //对功能赋功能地址，对iUnknown赋空值
    featureImpl->feature = feature;
    featureImpl->iUnknown = NULL;
    return featureImpl;
}

本篇小结

feature功能的实现，是在给定服务调用请求后在底层对功能地址与对应接口地址进行传导的过程，理解这一点对服务调用功能的基础运作会有一个更深刻的认识，在代码调用与接口实现上有助于我们理解底层工作原理。