# Samgr ## **Overview** Manages system capabilities. This module provides the development framework base of the service-oriented architecture \(SOA\). You can develop your own abilities based on the Samgr development framework. This module provides basic models of services, features, and functions, and registration and discovery capabilities. **Since:** 1.0 **Version:** 1.0 ## **Summary** ## Files

File Name	Description
common.h	Provides common objects and functions for Samgr and external modules.
feature.h	Defines the base class of a feature.
iunknown.h	Provides the base class and default implementation for external functions of system capabilities.
message.h	Provides message communication APIs that help you to implement asynchronous functions of IUnknown.
samgr_lite.h	Manages system capabilities.
service.h	Provides basic types and constants of services.

## Data Structures

Data Structure Name	Description
SimpleVector	Defines the simplified vector class, which is extended by four elements.
Feature	Defines the base class of a feature.
IUnknown	Defines the IUnknown class.
IUnknownEntry	Defines the IUnknown implementation class.
Identity	Identifies a service and feature.
Request	Defines a request.
Response	Defines a response.
SamgrLite	Represents the system ability management class.
TaskConfig	Defines task configurations for a service.
Service	Indicates the basic type of a service.

## Macros

Macro Name and Value	Description
GET_OFFSIZE(T, member) (long)((char )&(((T )(0))->member))	Calculates the offset of the member in the T type.
INHERIT_FEATURE	Inherits from the macro of the feature class.
DEFAULT_VERSION 0x20	Defines the default IUnknown version. You can customize the version.
INHERIT_IUNKNOWN	Defines the macro for inheriting the IUnknown interface.
INHERIT_IUNKNOWNENTRY(T)	Defines the macro for inheriting the classes that implement the IUnknown interface.
DEFAULT_IUNKNOWN_IMPL	Defines the default marco for initializing the IUnknown interface.
IUNKNOWN_ENTRY_BEGIN(version)	Defines the macro for initializing the classes that implement the IUnknown interface.
IUNKNOWN_ENTRY_END }	IUnknown Defines the end macro for initializing the IUnknown implementation object.
GET_IUNKNOWN(T) (IUnknown *)(&((T).iUnknown))	Obtains the pointer of the IUnknown interface object from the subclass object T (generic macro) of the IUnknown implementation class.
BOOTSTRAP_SERVICE "Bootstrap"	Starts a bootstrap service, which is used by samgr and implemented by system service developers.
INHERIT_SERVICE	Indicates the macro used to inherit the members from the service class.

## Typedefs

Typedef Name	Description
Vector	typedef struct SimpleVector Defines the simplified vector class, which is extended by four elements.
IUnknownEntry	typedef struct IUnknownEntry Defines the IUnknown implementation class.
Handler) (const Request request, const Response response)	typedef void(* Handles asynchronous responses.
BootMessage	typedef enum BootMessage Enumerates the IDs of the message to be processed for starting the bootstrap service.
SamgrLite	typedef struct SamgrLite Represents the system ability management class.
TaskType	typedef enum TaskType Enumerates task types.
SpecifyTag	typedef enum SpecifyTag Specifies the tag for the task shared by multiple services.
TaskPriority	typedef enum TaskPriority Enumerates task priority.

## Enumerations

Enumeration Name	Description
BootMessage { BOOT_SYS_COMPLETED, BOOT_APP_COMPLETED, BOOT_REG_SERVICE, BOOTSTRAP_BUTT }	Enumerates the IDs of the message to be processed for starting the bootstrap service.
TaskType { SHARED_TASK = 0, SINGLE_TASK = 1, SPECIFIED_TASK = 2, NO_TASK = 0xFF }	Enumerates task types.
SpecifyTag { LEVEL_HIGH = 0, LEVEL_MIDDLE = 1, LEVEL_LOW = 2, LEVEL_CUSTOM_BEGIN }	Specifies the tag for the task shared by multiple services.
TaskPriority { PRI_LOW = 9, PRI_BELOW_NORMAL = 16, PRI_NORMAL = 24, PRI_ABOVE_NORMAL = 32, PRI_BUTT = 39 }	Enumerates task priority.

## Functions

Function Name	Description
VECTOR_Make (VECTOR_Key key, VECTOR_Compare compare)	Vector Creates or initializes a vector object.
VECTOR_Clear (Vector *vector)	void Destruct a vector object.
VECTOR_Add (Vector vector, void element)	int16 Adds an element to the vector.
VECTOR_Size (Vector *vector)	int16 Obtains the number of elements in the vector, including elements that have been set to NULL.
VECTOR_Num (Vector *vector)	int16 Obtains the number of valid elements in the vector, excluding elements that have been set to NULL.
VECTOR_At (Vector *vector, int16 index)	void * Obtains the element at a specified position.
VECTOR_Swap (Vector vector, int16 index, void element)	void * Swaps the element at a specified position in a vector with another element.
VECTOR_Find (Vector vector, const void element)	int16 Checks the position of an element.
VECTOR_FindByKey (Vector vector, const void key)	int16 Checks the position of the element with a specified key.
IUNKNOWN_AddRef (IUnknown *iUnknown)	int Increments the reference count in this IUnknown interface.
IUNKNOWN_QueryInterface (IUnknown iUnknown, int ver, void *target)	int Queries the IUnknown interfaces of a specified version (downcasting).
IUNKNOWN_Release (IUnknown *iUnknown)	int Releases a reference to an IUnknown interface that is no longer used.
SAMGR_SendRequest (const Identity identity, const Request request, Handler handler)	int32 Sends a request to a service or feature of a specified identity.
SAMGR_SendSharedRequest (const Identity identity, const Request request, uint32 *token, Handler handler)	uint32 * Sends a request to multiple services or features to save memory.
SAMGR_SendSharedDirectRequest (const Identity id, const Request req, const Response resp, uint32 *ref, Handler handler)	int32 Sends a request and response of a caller to the feature thread. The handler is directly called to process the request and response without using the message processing functions. (Customized function for the broadcast service)
SAMGR_SendResponse (const Request request, const Response response)	int32 Sends a response after processing a request.
SAMGR_SendResponseByIdentity (const Identity id, const Request request, const Response *response)	int32 Sends a response to a specified service or feature after processing the original request. (Customized function for bootstrap)
SAMGR_GetInstance (void)	SamgrLite * Obtains the singleton Samgr instance.
SAMGR_Bootstrap (void)	void Starts system services and features.

## **Details** ## **Macro Definition Documentation** ## DEFAULT\_IUNKNOWN\_IMPL ``` #define DEFAULT_IUNKNOWN_IMPL ``` ``` Values: .QueryInterface = [IUNKNOWN_QueryInterface](Samgr.md#gac857d12648500c7dab1cb43e85ae2ed4), \ .AddRef = [IUNKNOWN_AddRef](Samgr.md#ga9abef49ec89bf913c3bed03faf478c1e), \ .Release = [IUNKNOWN_Release](Samgr.md#gabd462f8a5e6460a68760cd0719982296) ``` **Description:** Defines the default marco for initializing the **[IUnknown](IUnknown.md)** interface. When creating a subclass object of the **[IUnknown](IUnknown.md)** interface, you can use this macro to initialize members of the **[IUnknown](IUnknown.md)** interface to their default values. ## DEFAULT\_VERSION ``` #define DEFAULT_VERSION 0x20 ``` **Description:** Defines the default [IUnknown](IUnknown.md) version. You can customize the version. The **[IUnknown](IUnknown.md)** interface of the default version can be called only in the current process. Inter-process communication is not supported. ## GET\_IUNKNOWN ``` #define GET_IUNKNOWN( T) ([IUnknown](IUnknown.md) *)(&((T).iUnknown)) ``` **Description:** Obtains the pointer of the **[IUnknown](IUnknown.md)** interface object from the subclass object T \(generic macro\) of the **[IUnknown](IUnknown.md)** implementation class. Use this macro when registering **[IUnknown](IUnknown.md)** interfaces with Samgr so that you can obtain the interfaces from the subclass objects of different **[IUnknown](IUnknown.md)** implementation classes. ## GET\_OFFSIZE ``` #define GET_OFFSIZE( T, member ) (long)((char *)&(((T *)(0))->member)) ``` **Description:** Calculates the offset of the member in the T type. **Parameters:**

Name	Description
Indicates	the T type.
member	Indicates the name of the T member variable.

## INHERIT\_FEATURE ``` #define INHERIT_FEATURE ``` ``` Values: const char *(*GetName)([Feature](Feature.md) *feature); \ void (*OnInitialize)([Feature](Feature.md) *feature, [Service](Service.md) *parent, [Identity](Identity.md) identity); \ void (*OnStop)([Feature](Feature.md) *feature, [Identity](Identity.md) identity); \ BOOL (*OnMessage)([Feature](Feature.md) *feature, [Request](Request.md) *request) ``` **Description:** Inherits from the macro of the feature class. This macro provides the capability of inheriting the feature lifecycle. ## INHERIT\_IUNKNOWN ``` #define INHERIT_IUNKNOWN ``` ``` Values: int (*QueryInterface)([IUnknown](IUnknown.md) *iUnknown, int version, void **target); \ int (*AddRef)([IUnknown](IUnknown.md) *iUnknown); \ int (*Release)([IUnknown](IUnknown.md) *iUnknown) ``` **Description:** Defines the macro for inheriting the **[IUnknown](IUnknown.md)** interface. When developing a subclass of the **[IUnknown](IUnknown.md)** class, you can use this macro to inherit the structures of the **[IUnknown](IUnknown.md)** interface. ## INHERIT\_IUNKNOWNENTRY ``` #define INHERIT_IUNKNOWNENTRY( T) ``` ``` Values: uint16 ver; \ int16 ref; \ T iUnknown ``` **Description:** Defines the macro for inheriting the classes that implement the **[IUnknown](IUnknown.md)** interface. When developing a subclass of a class that implements the **[IUnknown](IUnknown.md)** interface, you can use this macro to inherit the structures of the **[IUnknown](IUnknown.md)** implementation class. ## INHERIT\_SERVICE ``` #define INHERIT_SERVICE ``` ``` Values: const char *(*GetName)([Service](Service.md) * service); \ BOOL (*Initialize)([Service](Service.md) * service, [Identity](Identity.md) identity); \ BOOL (*MessageHandle)([Service](Service.md) * service, [Request](Request.md) * request); \ TaskConfig (*GetTaskConfig)([Service](Service.md) * service) ``` **Description:** Indicates the macro used to inherit the members from the **service** class. This macro provides the capability of inheriting the lifecycle functions of the **service** class. You can use this macro to customize the service structure. ## IUNKNOWN\_ENTRY\_BEGIN ``` #define IUNKNOWN_ENTRY_BEGIN( version) ``` ``` Values: .ver = (version), \ .ref = 1, \ .iUnknown = { \ DEFAULT_IUNKNOWN_IMPL ``` **Description:** Defines the macro for initializing the classes that implement the **[IUnknown](IUnknown.md)** interface. When creating a subclass object of a class that implements the **[IUnknown](IUnknown.md)** interface, you can use this macro to initialize members of the **[IUnknown](IUnknown.md)** implementation class to their default values. You need to add the initialization of the customized member variable. ## IUNKNOWN\_ENTRY\_END ``` #define IUNKNOWN_ENTRY_END } ``` **Description:** [IUnknown](IUnknown.md) Defines the end macro for initializing the **[IUnknown](IUnknown.md)** implementation object. This macro is used when a subclass object of the **[IUnknown](IUnknown.md)** implementation class is initialized. ## **Typedef Documentation** ## BootMessage ``` typedef enum [BootMessage](Samgr.md#gaf39e482610dca95f0dba85613755eb40) [BootMessage](Samgr.md#gaf39e482610dca95f0dba85613755eb40) ``` **Description:** Enumerates the IDs of the message to be processed for starting the bootstrap service. This function is implemented by developers of the system service. Messages sent to the bootstrap service when Samgr is started. ## Handler ``` typedef void(* Handler) (const [Request](Request.md) *request, const [Response](Response.md) *response) ``` **Description:** Handles asynchronous responses. This function will be used when a service or feature uses [IUnknown](IUnknown.md) to send a request. If the caller is a feature, this function is used to handle the response that is sent after the feature processes a request. If the caller is a service, **Handler** will run in the service thread. ## IUnknownEntry ``` typedef struct [IUnknownEntry](IUnknownEntry.md) [IUnknownEntry](IUnknownEntry.md) ``` **Description:** Defines the **[IUnknown](IUnknown.md)** implementation class. You need to inherit this structure when developing a subclass of the **[IUnknown](IUnknown.md)** implementation class. Each **[IUnknown](IUnknown.md)** interface must correspond to one or more **[IUnknown](IUnknown.md)** implementation classes. ## SamgrLite ``` typedef struct [SamgrLite](SamgrLite.md) [SamgrLite](SamgrLite.md) ``` **Description:** Represents the system ability management class. This class is used for registering and discovering services, features, and functions. ## SpecifyTag ``` typedef enum [SpecifyTag](Samgr.md#ga704a59a45a705ef7a15d16e3cab8c1b0) [SpecifyTag](Samgr.md#ga704a59a45a705ef7a15d16e3cab8c1b0) ``` **Description:** Specifies the tag for the task shared by multiple services. These enumerations are used for specifying a multi-service sharing task. ## TaskPriority ``` typedef enum [TaskPriority](Samgr.md#gaee057e5f06a7b2533e6f58bde34d15fa) [TaskPriority](Samgr.md#gaee057e5f06a7b2533e6f58bde34d15fa) ``` **Description:** Enumerates task priority. These enumerations are used for configuring the task priority. The valid range of the priority is \(9, 39\). ## TaskType ``` typedef enum [TaskType](Samgr.md#ga026844c14ab62f42a2e19b54d622609b) [TaskType](Samgr.md#ga026844c14ab62f42a2e19b54d622609b) ``` **Description:** Enumerates task types. These enumerations are used for configuring the task type. ## Vector ``` typedef struct [SimpleVector](SimpleVector.md) [Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) ``` **Description:** Defines the simplified vector class, which is extended by four elements. This class is applicable to the C language development scenario where the data volume is small and dynamic expansion is required. ## **Enumeration Type Documentation** ## BootMessage ``` enum [BootMessage](Samgr.md#gaf39e482610dca95f0dba85613755eb40) ``` **Description:** Enumerates the IDs of the message to be processed for starting the bootstrap service. This function is implemented by developers of the system service. Messages sent to the bootstrap service when Samgr is started.

Enumerator	Description
BOOT_SYS_COMPLETED	Message indicating that the core system service is initialized
BOOT_APP_COMPLETED	Message indicating that the system and application-layer services are initialized
BOOT_REG_SERVICE	Message indicating service registration during running
BOOTSTRAP_BUTT	Maximum number of message IDs

## SpecifyTag ``` enum [SpecifyTag](Samgr.md#ga704a59a45a705ef7a15d16e3cab8c1b0) ``` **Description:** Specifies the tag for the task shared by multiple services. These enumerations are used for specifying a multi-service sharing task.

Enumerator	Description
LEVEL_HIGH	Preset tag
LEVEL_MIDDLE	Preset tag
LEVEL_LOW	Preset tag
LEVEL_CUSTOM_BEGIN	Customized tag

## TaskPriority ``` enum [TaskPriority](Samgr.md#gaee057e5f06a7b2533e6f58bde34d15fa) ``` **Description:** Enumerates task priority. These enumerations are used for configuring the task priority. The valid range of the priority is \(9, 39\).

Enumerator	Description
PRI_LOW	Low-priority: (9, 15)
PRI_BELOW_NORMAL	Lower than the normal priority: [16, 23)
PRI_NORMAL	Normal priority: [24, 31). The log service is available.
PRI_ABOVE_NORMAL	Higher than the normal priority: [32, 39). The communication service is available.
PRI_BUTT	Upper limit of the priority

## TaskType ``` enum [TaskType](Samgr.md#ga026844c14ab62f42a2e19b54d622609b) ``` **Description:** Enumerates task types. These enumerations are used for configuring the task type.

Enumerator	Description
SHARED_TASK	Tasks shared based on their priority by services
SINGLE_TASK	Task exclusively occupied by a service
SPECIFIED_TASK	A specified task shared by multiple services
NO_TASK	No task for the service. Generally, this situation does not occur.

## **Function Documentation** ## IUNKNOWN\_AddRef\(\) ``` int IUNKNOWN_AddRef ([IUnknown](IUnknown.md) * iUnknown) ``` **Description:** Increments the reference count in this **[IUnknown](IUnknown.md)** interface. This function is called in **QueryInterface**. Do not call this function in the **[IUnknown](IUnknown.md)** interface. When the **QueryInterface** function is re-implemented, you need to call this function in the new **QueryInterface**.**** ****The system does not provide a lock to protect functions. Therefore, you need to re-implement functions if multiple developers are using them. **** **Parameters:** ## IUNKNOWN\_QueryInterface\(\) ``` int IUNKNOWN_QueryInterface ([IUnknown](IUnknown.md) * iUnknown, int ver, void ** target ) ``` **Description:** Queries the **[IUnknown](IUnknown.md)** interfaces of a specified version \(downcasting\). After obtaining the **[IUnknown](IUnknown.md)** interface object, the function caller uses **QueryInterface** to convert the object to the required subclass type. The system converts [DEFAULT\_VERSION](Samgr.md#ga13dae059206df8d2d9b9b42e694b3f9c) into the subclass type required by the caller. If the type conversion requirements cannot be met, you need to re-implement this function. **Parameters:**

Name	Description
iUnknown	Indicates the pointer to the IUnknown interface.
version	Indicates the version of the IUnknown interface object to be converted.
target	Indicates the IUnknown subclass type required by the caller. This is an output parameter.

**Returns:** Returns **EC\_SUCCESS** if the conversion is successful; returns other error codes if the conversion fails. ## IUNKNOWN\_Release\(\) ``` int IUNKNOWN_Release ([IUnknown](IUnknown.md) * iUnknown) ``` **Description:** Releases a reference to an **[IUnknown](IUnknown.md)** interface that is no longer used. In the default implementation provided by the system, if the reference count is **0**, the memory of the **[IUnknown](IUnknown.md)** interface object and implementation object is not released. If the memory of the **[IUnknown](IUnknown.md)** interface object and implementation object is dynamically allocated, this function needs to be re-implemented. If the reference count is **0**, the memory of the **[IUnknown](IUnknown.md)** interface object and implementation object is released. **Parameters:**

Name	Description
iUnknown	Indicates the pointer to the IUnknown interface object.

**Returns:** **** Indicates the number of **[IUnknown](IUnknown.md)** interface objects that are referenced after the current reference is released.******** ## SAMGR\_Bootstrap\(\) ``` void SAMGR_Bootstrap (void ) ``` **Description:** Starts system services and features. This function is called in the **main** function to start all services when an independent process is developed. This function is called after the dynamic library \(containing system services and features\) is loaded during system running. **Attention:** This function cannot be called frequently. Otherwise, problems such as repeated service startup may occur. It is recommended that this function be called once in the **main** function or after the dynamic library is loaded. ## SAMGR\_GetInstance\(\) ``` [SamgrLite](SamgrLite.md)* SAMGR_GetInstance (void ) ``` **Description:** Obtains the singleton Samgr instance. You need to call this function before using the Samgr capabilities. **Returns:** Returns the pointer to the singleton instance [SamgrLite](SamgrLite.md). ## SAMGR\_SendRequest\(\) ``` int32 SAMGR_SendRequest (const [Identity](Identity.md) * identity, const [Request](Request.md) * request, [Handler](Samgr.md#ga5e13d943cc6a87a5c99fe604f3bc01e4) handler ) ``` **Description:** Sends a request to a service or feature of a specified identity. This function is called by a service to send messages to its own features through the asynchronous function of [IUnknown](IUnknown.md). **Parameters:**

Name	Description
identity	Indicates the pointer to the ID of the feature or service that processes the message.
request	Indicates the pointer to the request.
handler	Indicates the function handling the response. If the value is NULL, no response is required.

**Returns:** Returns **EC\_SUCCESS** if the request is sent successfully; returns other error codes if the request fails to be sent. The caller needs to release the memory applied in the request. ## SAMGR\_SendResponse\(\) ``` int32 SAMGR_SendResponse (const [Request](Request.md) * request, const [Response](Response.md) * response ) ``` **Description:** Sends a response after processing a request. This function is called to send a response after processing a request by **MessageHandle** of a service or **OnMessage** of a feature. **Parameters:**

Name	Description
request	Indicates the pointer to the original request.
response	Indicates the pointer to the response content.

**Returns:** Returns **EC\_SUCCESS** if the response is sent successfully; returns other error codes if the response fails to be sent. **Attention:** - This function can be called only in **MessageHandle** or **OnMessage**. - The request must be the original one passed from **MessageHandle** or **OnMessage**. Otherwise, a memory exception occurs. - When the caller sends a request, the **handler** callback function must be carried. - The response is sent to the message queue of the service to which the requester belongs for processing. Therefore, the requester should wait for the response in non-blocking mode. ## SAMGR\_SendResponseByIdentity\(\) ``` int32 SAMGR_SendResponseByIdentity (const [Identity](Identity.md) * id, const [Request](Request.md) * request, const [Response](Response.md) * response ) ``` **Description:** Sends a response to a specified service or feature after processing the original request. \(Customized function for **bootstrap**\) This function is called to send a response after processing a request by **MessageHandle** of a service or **OnMessage** of a feature. This function can be customized to implement phased startup of different types of services. **Parameters:**

Name	Description
id	Indicates the pointer to the ID of a service or feature. The response is sent to the thread of the service or feature for processing.
request	Indicates the pointer to the original request.
response	Indicates the pointer to the response content.

**Returns:** Returns **EC\_SUCCESS** if the response is sent successfully; returns other error codes if the response fails to be sent. **Attention:** - This function can be called only in **MessageHandle** or **OnMessage**. - The request must be the original one passed from **MessageHandle** or **OnMessage**. Otherwise, a memory exception occurs. - When the caller sends a request, the **handler** callback function must be carried. - The response is sent to the message queue of a specified ID for processing. Therefore, wait for the response in non-blocking mode. ## SAMGR\_SendSharedDirectRequest\(\) ``` int32 SAMGR_SendSharedDirectRequest (const [Identity](Identity.md) * id, const [Request](Request.md) * req, const [Response](Response.md) * resp, uint32 ** ref, [Handler](Samgr.md#ga5e13d943cc6a87a5c99fe604f3bc01e4) handler ) ``` **Description:** Sends a request and response of a caller to the feature thread. The handler is directly called to process the request and response without using the message processing functions. \(Customized function for the broadcast service\) This function is used to publish topics for the [Broadcast](Broadcast.md) service to broadcast messages. The value of reference counting is incremented by one each time this function is called. **Parameters:**

Name	Description
id	Indicates the pointer to the IDs of services or features, to which the request and response are sent.
request	Indicates the pointer to the request.
resp	Indicates the pointer to the response.
ref	Indicates the reference counting.
handler	Indicates the function for handling the request and response. This parameter cannot be NULL.

**Returns:** Returns **EC\_SUCCESS** if the request and response are sent successfully; returns other error codes if the request and response fail to be sent. **Attention:** - Ensure that the thread specified by **identity** processes the message after all messages are sent. Common practice: Add a lock before sending a request and add the same lock during processing. - If **NULL** is returned, the caller needs to release the memory of the request and response. - If the response changes each time when a request is sent, ensure that the response will not be released. \(Set **len** to **0**, the **data** of response will be the resident memory.\) ## SAMGR\_SendSharedRequest\(\) ``` uint32* SAMGR_SendSharedRequest (const [Identity](Identity.md) * identity, const [Request](Request.md) * request, uint32 * token, [Handler](Samgr.md#ga5e13d943cc6a87a5c99fe604f3bc01e4) handler ) ``` **Description:** Sends a request to multiple services or features to save memory. This function is used to publish topics for the [Broadcast](Broadcast.md) service to broadcast messages. **Parameters:**

Name	Description
identity	Indicates the pointer to the IDs of services or features, to which requests are sent.
request	Indicates the pointer to the request.
token	Indicates the pointer to reference counting.
handler	Indicates the function handling the response. If the value is NULL, no response is required.

**Attention:** - Ensure that the thread specified by **identity** processes the message after all messages are sent. Common practice: Add a lock before sending a request and add the same lock during processing. - If **NULL** is returned, the caller needs to release the memory of the request. ## VECTOR\_Add\(\) ``` int16 VECTOR_Add ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector, void * element ) ``` **Description:** Adds an element to the vector. This function is used to add an element to the vector. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.
element	Indicates the element to add.

**Returns:** Returns the location of the element to be added if the operation is successful; returns **INVALID\_INDEX** if the operation fails. ## VECTOR\_At\(\) ``` void* VECTOR_At ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector, int16 index ) ``` **Description:** Obtains the element at a specified position. This function is used to obtain the element at a specified position. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.
index	Indicates the subscript to be obtained.

**Returns:** Returns the element if obtained; returns **NULL** otherwise. ## VECTOR\_Clear\(\) ``` void VECTOR_Clear ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector) ``` **Description:** Destruct a vector object. This function is used to clear the memory applied by the vector after the temporary vector in the stack is used. **Parameters:**

Name	Description
vector	Indicates the pointer to the vector to clear.

## VECTOR\_Find\(\) ``` int16 VECTOR_Find ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector, const void * element ) ``` **Description:** Checks the position of an element. This function is used to check whether a vector has a specified element. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.
element	Indicates the element to be checked.

**Returns:** Returns the index of the element that is not less than 0 if the check is successful; returns **INVALID\_INDEX** if the check fails. ## VECTOR\_FindByKey\(\) ``` int16 VECTOR_FindByKey ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector, const void * key ) ``` **Description:** Checks the position of the element with a specified key. This function is used to check an element based on its key value. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.
key	Indicates the pointer to the key value of the element to check.

**Returns:** Returns the index of the key element that is not less than 0 if the check is successful; returns **INVALID\_INDEX** if the check fails. ## VECTOR\_Make\(\) ``` [Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) VECTOR_Make (VECTOR_Key key, VECTOR_Compare compare ) ``` **Description:** Creates or initializes a vector object. This function is used to create or initialize a vector object. **Parameters:**

Name	Description
key	Indicates the pointer to the function provided by users for converting data elements into key values. If this function is not provided, set it to NULL.
compare	Indicates the pointer to the function for comparing the sizes of two elements. If this function is not provided, set it to NULL.

**Returns:** Returns the vector right value object. ## VECTOR\_Num\(\) ``` int16 VECTOR_Num ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector) ``` **Description:** Obtains the number of valid elements in the vector, excluding elements that have been set to **NULL**. This function is used to check whether the number of elements reaches the upper limit. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.

**Returns:** Returns the top - free value of the vector, which indicates the number of non-null elements. ## VECTOR\_Size\(\) ``` int16 VECTOR_Size ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector) ``` **Description:** Obtains the number of elements in the vector, including elements that have been set to **NULL**. This function is used for full traversal. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.

**Returns:** Returns the top value of the vector, which indicates the number of elements. ## VECTOR\_Swap\(\) ``` void* VECTOR_Swap ([Vector](Samgr.md#ga255ca81c214b8a94a90f786ceef94514) * vector, int16 index, void * element ) ``` **Description:** Swaps the element at a specified position in a vector with another element. This function is used to clear, sort, or update elements in the vector. **Parameters:**

Name	Description
vector	Indicates the this pointer to the vector.
index	Indicates the position of the element to be swapped.
element	Indicates the pointer to the new element.

**Attention:** Before using this function, ensure that the index is valid. You can use **VECTOR\_Size** to obtain the upper limit of the index. **Returns:** Returns the original element if the swapping is successful; returns **NULL** if the swapping fails. **See also:** [VECTOR\_Size](Samgr.md#ga1432f30c136d14bc00414d883d8be3bd)