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

Posted 2021-11-24 心永向阳

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

• 本篇概述
• 代码框架
• iunknown.h
• • 宏定义部分
  • 结构体部分
  • 函数声明部分
• iunknown.c
• • IUNKNOWN_QueryInterface
  • IUNKNOWN_AddRef
  • IUNKNOWN_Release
• 本篇小结

本篇概述

基于IUnknown，我们可以开发服务或功能的对外接口，接口实现的本质是函数地址的传导与函数的调用，因此IUnknown在M核和A核系统服务开发框架基础代码中显得尤为重要。
组件对外公布的是接口，一个组件可以实现多个接口，也就是说可以对外公布多个接口，组件本身就提供对自己查询的一个接口，让客户去询问组件，问它是否支持某个接口，在经过多次的这种询问之后，客户对于组件的认识将越来越清晰。这是COM组件对象模型的核心内容，详情请参考com编程。
本篇将讲述iunknown.c和iunknown.h的核心内容，基于接口的底层代码探索接口实现的核心技术。

代码框架

iunknown
├── 宏定义
│ └── DEFAULT_VERSION
│ └── INHERIT_IUNKNOWN
│ └── INHERIT_IUNKNOWNENTRY
│ └── DEFAULT_IUNKNOWN_IMPL
│ └── IUNKNOWN_ENTRY_BEGIN
│ └── IUNKNOWN_ENTRY_END
│ └── GET_IUNKNOWN
├── 结构体
│ └── IUnknown
│ └── IUnknownEntry
├── 接口功能函数
│ └── IUNKNOWN_QueryInterface
│ └── IUNKNOWN_AddRef
│ └── IUNKNOWN_Release

iunknown.h

iunknown.h中包含了有关接口对象以及类的相关宏定义、接口与接口入口的结构体以及接口功能函数的部分声明。通过iunknown.h中的相关代码以及注释我们可以发现：接口的结构与调用思路采用COM编程的方案，详情请见：

宏定义部分

/**
 * @brief Defines the default IUnknown IUnknown. You can customize the version.
 * 概述：定义默认IUnknown型号，你可以自定义这个型号
 * The <b>IUnknown</b> interface of the default version can be called only in the current process.
 * Inter-process communication is not supported. \\n
 * IUnknown默认型号接口只能在当前进程被调用
 * 跨进程间通信不被支持
 * @since 1.0
 * @version 1.0
 */
#define DEFAULT_VERSION 0x20 //16进制数转10进制为32

/**
 * @brief Defines the macro for inheriting the <b>IUnknown</b> interface.
 * 概述：定义为了继承IUnknown接口的宏
 * When developing a subclass of the <b>IUnknown</b> class, you can use this macro to inherit the
 * structures of the <b>IUnknown</b> interface. \\n
 * 在开发一个IUnknown的子类时，你可以使用这个宏来继承IUnknown接口的框架
 */
#define INHERIT_IUNKNOWN                                                   \\
    int (*QueryInterface)(IUnknown *iUnknown, int version, void **target); \\
    int (*AddRef)(IUnknown *iUnknown);                                     \\
    int (*Release)(IUnknown *iUnknown)

/**
 * @brief Defines the macro for inheriting the classes that implement the <b>IUnknown</b>
 * interface.
 * 概述：定义macro（宏）用来继承实现IUnknown接口的类
 * When developing a subclass of a class that implements the <b>IUnknown</b> interface, you can use
 * this macro to inherit the structures of the <b>IUnknown</b> implementation class. \\n
 * 当开发一个实现IUnknown接口的子类时，你可以使用这个macro来继承IUnknown实现类的框架
 */
#define INHERIT_IUNKNOWNENTRY(T) \\
    uint16 ver;                   \\
    int16 ref;                   \\
    T iUnknown

/**
 * @brief Defines the default marco for initializing the <b>IUnknown</b> interface.
 * 概述：定义默认的marco（宏）用来初始化IUnknown接口
 * When creating a subclass object of the <b>IUnknown</b> interface, you can use this macro to
 * initialize members of the <b>IUnknown</b> interface to their default values. \\n
 * 当创建一个IUnknown接口的子类时，你可以使用这个macro（宏）来初始化IUnknown接口成员的默认值
 */
#define DEFAULT_IUNKNOWN_IMPL                  \\
    .QueryInterface = IUNKNOWN_QueryInterface, \\
    .AddRef = IUNKNOWN_AddRef,                 \\
    .Release = IUNKNOWN_Release

/**
 * @brief Defines the macro for initializing the classes that implement the <b>IUnknown</b>
 * interface.
 * 概述：定义一个宏用于初始化实现IUnknown接口的类
 * When creating a subclass object of a class that implements the <b>IUnknown</b> interface, you
 * can use this macro to initialize members of the <b>IUnknown</b> implementation class to their
 * default values. \\n
 * You need to add the initialization of the customized member variable. \\n
 * 当创建一个类的用于实现IUnknown接口的子类对象时，你可以使用这个macro（宏）来初始化IUnknown实现类成员的默认值
 */
#define IUNKNOWN_ENTRY_BEGIN(version)   \\
    .ver = (version),                   \\
    .ref = 1,                           \\
    .iUnknown = {                       \\
        DEFAULT_IUNKNOWN_IMPL

/**
 * @brief IUnknown Defines the end macro for initializing the <b>IUnknown</b> implementation
 * object.
 * 概述：IUnknown定义一个结尾标记宏用于初始化IUnknown实现对象
 * This macro is used when a subclass object of the <b>IUnknown</b> implementation class is
 * initialized. \\n
 * 这个宏在子类对象的IUnknown实现类被初始化时调用
 */
#define IUNKNOWN_ENTRY_END }

#define DEFAULT_IUNKNOWN_ENTRY_BEGIN IUNKNOWN_ENTRY_BEGIN(DEFAULT_VERSION)

#define DEFAULT_IUNKNOWN_ENTRY_END IUNKNOWN_ENTRY_END

/**
 * @brief Obtains the pointer of the <b>IUnknown</b> interface object from the subclass object T
 *  (generic macro) of the <b>IUnknown</b> implementation class.
 * 概述：从子类对象T中获取IUnknown接口对象的指针
 * Use this macro when registering <b>IUnknown</b> interfaces with Samgr so that you can obtain
 * the interfaces from the subclass objects of different <b>IUnknown</b> implementation classes. \\n
 * 当使用Samgr注册IUnknown接口时使用这个宏，这样你就能从子类对象的不同IUnknown实现类中获取接口
 * @since 1.0
 * @version 1.0
 */
#define GET_IUNKNOWN(T) (IUnknown *)(&((T).iUnknown))

结构体部分

通过宏定义和结构体我们可以发现：IUnknownEntry 是对IUnknown的一个继承，IUnknown接口是一个框架，在实现IUnknown接口类时需要在这个框架的基础上展开，详细代码如下：

/**
 * @brief Defines the <b>IUnknown</b> class.
 * 概述：定义IUnknown类
 * You need to inherit this structure when developing a subclass of the <b>IUnknown</b> interface. \\n
 * 当开发一个IUnknown子类接口时，你需要继承这个框架
 */
struct IUnknown {
    /**
     * Queries the subclass object of the <b>IUnknown</b> interface of a specified version
     * (downcasting).
     * 查询指定版本IUnknown接口的子类对象
     */
    int (*QueryInterface)(IUnknown *iUnknown, int version, void **target);
    /** Adds the reference count. 增加一个引用计数*/
    int (*AddRef)(IUnknown *iUnknown);
    /** Release the reference to an <b>IUnknown</b> interface. 释放一个IUnknown接口引用*/
    int (*Release)(IUnknown *iUnknown);
};

/**
 * @brief Defines the <b>IUnknown</b> implementation .
 * 概述：定义一个IUnknown实现类入口
 * You need to inherit this structure when developing a subclass of the <b>IUnknown</b>
 * implementation class. \\n
 * 你需要继承这个类当开发一个IUnknown实现类的子类时
 * Each <b>IUnknown</b> interface must correspond to one or more <b>IUnknown</b> implementation
 * classes. \\n
 * 每一个IUnknown接口必须对应一个或者更多的IUnknown实现类
 */
typedef struct IUnknownEntry {
    /** Version information of <b>IUnknown</b> interface. IUnknown接口的版本信息 */
    uint16 ver;
    /** Reference count of <b>IUnknown</b> interface. IUnknown接口的引用计数 */
    int16 ref;
    /**
     * Implementation of <b>IUnknown</b> interface, which is related to the specific definition
     * implementation.
     * IUnknown接口的实现，与特定的实现定义相关
     */
    IUnknown iUnknown;
} IUnknownEntry;

函数声明部分

函数声明部分结合函数的定义一起讲解，故此处先做省略。

iunknown.c

iunknown接口实现框架基于COM编程中的：QueryInterface、AddRefRelease，在此我们详细分析这三处功能函数的代码：

IUNKNOWN_QueryInterface

函数声明部分及注释：

/**
 * @brief Queries the <b>IUnknown</b> interfaces of a specified version (downcasting).
 * 概述：查询指定版本的IUnknown接口
 * 
 * After obtaining the <b>IUnknown</b> interface object, the function caller uses
 * <b>QueryInterface</b> to convert the object to the required subclass type. \\n
 * 在获取了IUnknown接口对象之后，函数调用QueryInterface来转变对象为需要的子类型
 * The system converts {@link DEFAULT_VERSION} into the subclass type required by the caller.
 * 系统将{@link DEFAULT_VERSION}转换为调用者需要的子类类型
 * If the type conversion requirements cannot be met, you need to re-implement this function. \\n
 * 如果不能满足类型转换要求，则需要重新实现该函数。
 * 
 * @param iUnknown Indicates the pointer to the <b>IUnknown</b> interface.
 * @param version Indicates the version of the <b>IUnknown</b> interface object to be converted.
 * @param target Indicates the <b>IUnknown</b> subclass type required by the caller. This is an
 * output parameter.
 * target代表调用者需要的IUnknown子类类型。这是一个输出参数
 * 
 * @return Returns <b>EC_SUCCESS</b> if the conversion is successful; returns other error codes
 * if the conversion fails.
 *
 * @since 1.0
 * @version 1.0
 */
int IUNKNOWN_QueryInterface(IUnknown *iUnknown, int ver, void **target);

函数体部分及注释：

//查询指定版本的IUnknown接口
int IUNKNOWN_QueryInterface(IUnknown *iUnknown, int ver, void **target)
{
    if (iUnknown == NULL || target == NULL) {
        return EC_INVALID;
    }
    //先获取一个对象，然后判断IUnknown入口的类型是否正确
    IUnknownEntry *entry = GET_OBJECT(iUnknown, IUnknownEntry, iUnknown);
    if ((entry->ver & (uint16)ver) != ver) {
        return EC_INVALID;
    }

    //接着检查类型信息
    if (ver == OLD_VERSION &&
        entry->ver != OLD_VERSION &&
        (entry->ver & (uint16)DEFAULT_VERSION) != DEFAULT_VERSION) {
        return EC_INVALID;
    }

    //赋值调用者需要的IUnknown子类类型接口值
    *target = iUnknown;
    //将该IUnknown接口结构体中增加一个引用
    iUnknown->AddRef(iUnknown);
    return EC_SUCCESS;
}

IUNKNOWN_AddRef

函数声明部分及注释:

/**
 * @brief Increments the reference count in this <b>IUnknown</b> interface.
 * 概述：在IUnknown接口中增加引用计数
 * 
 * This function is called in <b>QueryInterface</b>. Do not call this function in the
 * <b>IUnknown<b> interface. \\n
 * 这个函数在QueryInterface中调用。不要在IUnknown接口中调用这个函数
 * 
 * When the <b>QueryInterface</b> function is re-implemented, you need to call this function
 * in the new <b>QueryInterface</b>.
 * 当QueryInterface函数被重新实现时，你需要在新的QueryInterface中调用这个函数
 * 
 * The system does not provide a lock to protect functions. Therefore, you need to re-implement
 * functions if multiple developers are using them. \\n
 * 系统不提供锁保护功能。因此，如果多个开发人员正在使用这些函数，则需要重新实现它们
 * 
 * @param iUnknown Indicates the pointer to the <b>IUnknown<b> interface object.
 * 参数iUnknown：代表接口对象的iUnknown 的指针。
 * @return Indicates the number of objects that reference the <b>IUnknown<b> interface.
 * 返回值：引用IUnknown接口的节点数
 * @since 1.0
 * @version 1.0
 */
int IUNKNOWN_AddRef(IUnknown *iUnknown);

函数体部分代码及注释：

int IUNKNOWN_AddRef(IUnknown *iUnknown)
{
    //检查传入接口地址是否为空
    if (iUnknown == NULL) {
        return EC_INVALID;
    }

    //定义一个IUnknown入口，将iUnknown指针向下转为T成员变量地址
    IUnknownEntry *entry = GET_OBJECT(iUnknown, IUnknownEntry, iUnknown);
    //给iUnknown入口中的引用计数+1
    entry->ref++;
    //返回实现后的iUnknown引用数
    return entry->ref;
}

IUNKNOWN_Release

函数声明部分及注释:

/**
 * @brief Releases a reference to an <b>IUnknown</b> interface that is no longer used.
 * 概述：释放一个对不再使用的IUnknown接口的引用。
 * In the default implementation provided by the system, if the reference count is <b>0</b>,
 * the memory of the <b>IUnknown</b> interface object and implementation object is not released. \\n
 * 在系统默认实现中，如果引用数为0，内存中IUnknown接口对象和实现对象不被释放
 * 
 * If the memory of the <b>IUnknown</b> interface object and implementation object is dynamically
 * allocated, this function needs to be re-implemented. \\n
 * 如果内存IUnknown接口对象和应用对象被动态分配，这个函数需要被重新实现
 * If the reference count is <b>0</b>, the memory of the <b>IUnknown</b> interface object and
 * implementation object is released. \\n
 * 如果引用数为0，内存中的IUnknown接口对象与应用对象需要被释放
 *
 * @param iUnknown Indicates the pointer to the <b>IUnknown<b> interface object.
 * @return Indicates the number of <b>IUnknown<b> interface objects that are referenced after the
 * current reference is released.
 *
 * @since 1.0
 * @version 1.0
 */
int IUNKNOWN_Release(IUnknown *iUnknown);

函数体部分代码及注释：

//释放一个对不再使用的IUnknown接口的引用
int IUNKNOWN_Release(IUnknown *iUnknown)
{
    //判断传入iUnknown是否为空
    if (iUnknown == NULL) {
        return EC_INVALID;
    }

    //获取对象后，再对IUnknown入口接口进行引用数的操作
    IUnknownEntry *entry = GET_OBJECT(iUnknown, IUnknownEntry, iUnknown);
    int ref = entry->ref - 1;
    if (ref < 0) {
        // The iUnknown is already freed, there is some exception.iUnknown已经被释放，有一些异常;
    } else {
        if (ref == 0) {
            // Nobody reference to the iUnknown, should delete it.没有人引用iUnknown，应该删除它。
            // But iUnknown may be global variable, so the default version don`t delete it.
            // 但是iUnknown可能是全局变量，所以默认版本不会删除它。
        } else {
            entry->ref = ref;
        }
    }
    return ref;
}

本篇小结

在细致地解读了接口部分代码之后，相信对开发服务或功能的对外接口的实质有了更清晰的认识，以及接口在服务于功能中所处的地位有了更深刻的理解，这有助于我们去进一步解读系统服务开发框架。