[C++知识库]模块二interfaces下头文件解析

distributedschedule_samgr_lite/interfaces/kits/samgr/common.h

该模块提供了管理系统功能，本模块提供了面向服务体系结构（SOA）的开发框架基础，同时此模块提供服务、功能和功能的基本模型，以及注册和发现功能。

该文件为Samgr和外部模块提供通用对象和函数，主要提供简化的向量容器和向下广播函数

该宏定义的功能是计算T类型中杆件的偏移量。

#define GET_OFFSIZE(T, member) (long)((char *)&(((T *)(0))->member))
//member表示T成员变量的名称。

该宏定义提供了向下转换指向T类型的指针。

#define GET_OBJECT(Ptr, T, member) (T *)(((char *)(Ptr)) - GET_OFFSIZE(T, member))
//Ptr表示当前指针，即T成员变量的地址。
//T表示向下广播的目标类型。
//member将{@code Ptr}的名称指示为T成员变量。

该宏指示无效的向量索引，该值为-1，表示向量操作失败。

#define INVALID_INDEX (-1)
typedef void *(*VECTOR_Key)(const void *);
typedef int (*VECTOR_Compare)(const void *, const void *);

如果{@link VECTOR Find}找不到元素或无法将元素添加到VECTOR Add中，则返回无效的索引。

该宏定义了向量类，该类由四个元素扩展，适用于数据量较小且需要动态扩展的C语言开发场景。

typedef struct SimpleVector {
	 int16 max;  //可存储的最大数据记录数。初始值为<b>0</b>。
	 int16 top;  //存储数据记录数的峰值。初始值为<b>0</b>。
	 int16 free; //已发布的数据记录数。初始值为<b>0</b>。
	 void **data;    //数据存储指针
	 VECTOR_Key key; //将数据元素转换为键以进行比较。密钥由用户提供，默认值为<b>NULL</b>
	 VECTOR_Compare compare;
	 //比较用户提供的键1和键2的大小。值<b>1</b>表示键1大于键2，值<b>0</b>表示键1等于键2，值<b>-1</b>表示键1小于键2。默认值为<b>NULL</b>。
} Vector;

该函数提供创建或初始化向量对象的功能，此函数用于创建或初始化向量对象，返回向量右值对象

Vector VECTOR_Make(VECTOR_Key key, VECTOR_Compare compare);
//key表示指向用户提供的用于将数据元素转换为键值的函数的指针。
//compare指示指向用于比较两个元素大小的函数的指针。

如果未提供此功能，请将其设置为NULL。

该函数的主要功能销毁向量对象，此函数用于在使用堆栈中的临时向量后清除向量应用的内存

void VECTOR_Clear(Vector *vector);
 //vector表示指向要清除的向量的指针。

该函数的功能是将元素添加到向量，此函数用于向向量添加元素，此函数用于完全遍历。

int16 VECTOR_Add(Vector *vector, void *element);
//vector表示指向该向量的指针。
//element指示要添加的元素。

如果操作成功，返回要添加的元素的位置；如果操作失败，则返回{@link INVALID_INDEX}。

该函数的功能是获取向量中的元素数，包括已设置为NULL的元素，//返回向量的最大值，该值指示元素数。
此函数用于完全遍历。

int16 VECTOR_Size(Vector *vector);
//vector表示指向该向量的指针

该函数提供获取向量中的有效元素数，不包括已设置为NULL的元素，返回向量的无顶值，该值指示非空元素的数量。
此功能用于检查元素数量是否达到上限。

int16 VECTOR_Num(Vector *vector);
//vector表示指向该向量的指针。

该函数提供了在指定位置获取元素的功能，返回元素（如果已获取）；否则返回空值。
此函数用于获取指定位置的元素。

void *VECTOR_At(Vector *vector, int16 index);
//vector表示指向该向量的<b>指针。
//index指示要获取的下标

该函数的功能是将向量中指定位置的元素与另一个元素交换，此函数用于清除、排序或更新向量中的元素。

void *VECTOR_Swap(Vector *vector, int16 index, void *element);
//vector表示指向该向量的指针。
//index指示要交换的元素的位置。
//element指示指向新元素的指针。

使用此函数之前，请确保索引有效。您可以使用VECTOR_Size获取索引的上限，如果交换成功，则返回原始元素；如果交换失败，则返回NULL。

该函数用于检查元素的位置，检查向量是否具有指定的元素。

int16 VECTOR_Find(Vector *vector, const void *element);
//vector表示指向该向量的指针。
//element表示要检查的元素。

如果检查成功，则返回不小于0的元素索引；如果检查失败，则返回{@link INVALID_INDEX}。

该函数的功能是使用指定的键检查元素的位置，此函数用于根据元素的键值检查元素。

int16 VECTOR_FindByKey(Vector *vector, const void *key);
//vector表示指向该向量的指针。
//key表示指向要检查的元素键值的指针。

如果检查成功，则返回不小于0的键元素索引；如果检查失败，则返回{@link INVALID_INDEX}。