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

  1. #define DEFAULT_IUNKNOWN_IMPL
  1. Values: .QueryInterface = [IUNKNOWN_QueryInterface]($api-api-LinkIoT-Samgr.md#gac857d12648500c7dab1cb43e85ae2ed4), \
  3.  .AddRef = [IUNKNOWN_AddRef]($api-api-LinkIoT-Samgr.md#ga9abef49ec89bf913c3bed03faf478c1e), \
  5.  .Release = [IUNKNOWN_Release]($api-api-LinkIoT-Samgr.md#gabd462f8a5e6460a68760cd0719982296)

Description:

Defines the default marco for initializing the IUnknown interface.

When creating a subclass object of the IUnknown interface, you can use this macro to initialize members of the IUnknown interface to their default values.

DEFAULT_VERSION

  1. #define DEFAULT_VERSION   0x20

Description:

Defines the default IUnknown version. You can customize the version.

The IUnknown interface of the default version can be called only in the current process. Inter-process communication is not supported.

GET_IUNKNOWN

  1. #define GET_IUNKNOWN( T)   ([IUnknown]($api-api-LinkIoT-IUnknown.md) *)(&((T).iUnknown))

Description:

Obtains the pointer of the IUnknown interface object from the subclass object T (generic macro) of the IUnknown implementation class.

Use this macro when registering IUnknown interfaces with Samgr so that you can obtain the interfaces from the subclass objects of different IUnknown implementation classes.

GET_OFFSIZE

  1. #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

  1. #define INHERIT_FEATURE
  1. Values: const char *(*GetName)([Feature]($api-api-LinkIoT-Feature.md) *feature); \
  3.  void (*OnInitialize)([Feature]($api-api-LinkIoT-Feature.md) *feature, [Service]($api-api-LinkIoT-Service.md) *parent, [Identity]($api-api-LinkIoT-Identity.md) identity); \
  5.  void (*OnStop)([Feature]($api-api-LinkIoT-Feature.md) *feature, [Identity]($api-api-LinkIoT-Identity.md) identity); \
  7.  BOOL (*OnMessage)([Feature]($api-api-LinkIoT-Feature.md) *feature, [Request]($api-api-LinkIoT-Request.md) *request)

Description:

Inherits from the macro of the feature class.

This macro provides the capability of inheriting the feature lifecycle.

INHERIT_IUNKNOWN

  1. #define INHERIT_IUNKNOWN
  1. Values: int (*QueryInterface)([IUnknown]($api-api-LinkIoT-IUnknown.md) *iUnknown, int version, void **target); \
  3.  int (*AddRef)([IUnknown]($api-api-LinkIoT-IUnknown.md) *iUnknown); \
  5.  int (*Release)([IUnknown]($api-api-LinkIoT-IUnknown.md) *iUnknown)

Description:

Defines the macro for inheriting the IUnknown interface.

When developing a subclass of the IUnknown class, you can use this macro to inherit the structures of the IUnknown interface.

INHERIT_IUNKNOWNENTRY

  1. #define INHERIT_IUNKNOWNENTRY( T)
  1. Values: uint16 ver; \
  3.  int16 ref; \
  5.  T iUnknown

Description:

Defines the macro for inheriting the classes that implement the IUnknown interface.

When developing a subclass of a class that implements the IUnknown interface, you can use this macro to inherit the structures of the IUnknown implementation class.

INHERIT_SERVICE

  1. #define INHERIT_SERVICE
  1. Values: const char *(*GetName)([Service]($api-api-LinkIoT-Service.md) * service); \
  3.  BOOL (*Initialize)([Service]($api-api-LinkIoT-Service.md) * service, [Identity]($api-api-LinkIoT-Identity.md) identity); \
  5.  BOOL (*MessageHandle)([Service]($api-api-LinkIoT-Service.md) * service, [Request]($api-api-LinkIoT-Request.md) * request); \
  7.  TaskConfig (*GetTaskConfig)([Service]($api-api-LinkIoT-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

  1. #define IUNKNOWN_ENTRY_BEGIN( version)
  1. Values: .ver = (version), \
  3.  .ref = 1, \
  5.  .iUnknown = { \
  7.  DEFAULT_IUNKNOWN_IMPL

Description:

Defines the macro for initializing the classes that implement the IUnknown interface.

When creating a subclass object of a class that implements the IUnknown interface, you can use this macro to initialize members of the IUnknown implementation class to their default values. You need to add the initialization of the customized member variable.

IUNKNOWN_ENTRY_END

  1. #define IUNKNOWN_ENTRY_END   }

Description:

IUnknown Defines the end macro for initializing the IUnknown implementation object.

This macro is used when a subclass object of the IUnknown implementation class is initialized.

Typedef Documentation

BootMessage

  1. typedef enum [BootMessage]($api-api-LinkIoT-Samgr.md#gaf39e482610dca95f0dba85613755eb40) [BootMessage]($api-api-LinkIoT-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

  1. typedef void(* Handler) (const [Request]($api-api-LinkIoT-Request.md) *request, const [Response]($api-api-LinkIoT-Response.md) *response)

Description:

Handles asynchronous responses.

This function will be used when a service or feature uses IUnknown 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

  1. typedef struct [IUnknownEntry]($api-api-LinkIoT-IUnknownEntry.md) [IUnknownEntry]($api-api-LinkIoT-IUnknownEntry.md)

Description:

Defines the IUnknown implementation class.

You need to inherit this structure when developing a subclass of the IUnknown implementation class. Each IUnknown interface must correspond to one or more IUnknown implementation classes.

SamgrLite

  1. typedef struct [SamgrLite]($api-api-LinkIoT-SamgrLite.md) [SamgrLite]($api-api-LinkIoT-SamgrLite.md)

Description:

Represents the system ability management class.

This class is used for registering and discovering services, features, and functions.

SpecifyTag

  1. typedef enum [SpecifyTag]($api-api-LinkIoT-Samgr.md#ga704a59a45a705ef7a15d16e3cab8c1b0) [SpecifyTag]($api-api-LinkIoT-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

  1. typedef enum [TaskPriority]($api-api-LinkIoT-Samgr.md#gaee057e5f06a7b2533e6f58bde34d15fa) [TaskPriority]($api-api-LinkIoT-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

  1. typedef enum [TaskType]($api-api-LinkIoT-Samgr.md#ga026844c14ab62f42a2e19b54d622609b) [TaskType]($api-api-LinkIoT-Samgr.md#ga026844c14ab62f42a2e19b54d622609b)

Description:

Enumerates task types.

These enumerations are used for configuring the task type.

Vector

  1. typedef struct [SimpleVector]($api-api-LinkIoT-SimpleVector.md) [Vector]($api-api-LinkIoT-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

  1. enum [BootMessage]($api-api-LinkIoT-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

  1. enum [SpecifyTag]($api-api-LinkIoT-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

  1. enum [TaskPriority]($api-api-LinkIoT-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

  1. enum [TaskType]($api-api-LinkIoT-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()

  1. int IUNKNOWN_AddRef ([IUnknown]($api-api-LinkIoT-IUnknown.md) * iUnknown)

Description:

Increments the reference count in this IUnknown interface.

This function is called in QueryInterface. Do not call this function in the IUnknown 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()

  1. int IUNKNOWN_QueryInterface ([IUnknown]($api-api-LinkIoT-IUnknown.md) * iUnknown, int ver, void ** target )

Description:

Queries the IUnknown interfaces of a specified version (downcasting).

After obtaining the IUnknown interface object, the function caller uses QueryInterface to convert the object to the required subclass type. The system converts DEFAULT_VERSION 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()

  1. int IUNKNOWN_Release ([IUnknown]($api-api-LinkIoT-IUnknown.md) * iUnknown)

Description:

Releases a reference to an IUnknown 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 interface object and implementation object is not released. If the memory of the IUnknown 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 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 interface objects that are referenced after the current reference is released.**

SAMGR_Bootstrap()

  1. 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()

  1. [SamgrLite]($api-api-LinkIoT-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.

SAMGR_SendRequest()

  1. int32 SAMGR_SendRequest (const [Identity]($api-api-LinkIoT-Identity.md) * identity, const [Request]($api-api-LinkIoT-Request.md) * request, [Handler]($api-api-LinkIoT-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.

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()

  1. int32 SAMGR_SendResponse (const [Request]($api-api-LinkIoT-Request.md) * request, const [Response]($api-api-LinkIoT-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()

  1. int32 SAMGR_SendResponseByIdentity (const [Identity]($api-api-LinkIoT-Identity.md) * id, const [Request]($api-api-LinkIoT-Request.md) * request, const [Response]($api-api-LinkIoT-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()

  1. int32 SAMGR_SendSharedDirectRequest (const [Identity]($api-api-LinkIoT-Identity.md) * id, const [Request]($api-api-LinkIoT-Request.md) * req, const [Response]($api-api-LinkIoT-Response.md) * resp, uint32 ** ref, [Handler]($api-api-LinkIoT-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 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()

  1. uint32* SAMGR_SendSharedRequest (const [Identity]($api-api-LinkIoT-Identity.md) * identity, const [Request]($api-api-LinkIoT-Request.md) * request, uint32 * token, [Handler]($api-api-LinkIoT-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 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()

  1. int16 VECTOR_Add ([Vector]($api-api-LinkIoT-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()

  1. void* VECTOR_At ([Vector]($api-api-LinkIoT-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()

  1. void VECTOR_Clear ([Vector]($api-api-LinkIoT-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()

  1. int16 VECTOR_Find ([Vector]($api-api-LinkIoT-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()

  1. int16 VECTOR_FindByKey ([Vector]($api-api-LinkIoT-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()

  1. [Vector]($api-api-LinkIoT-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()

  1. int16 VECTOR_Num ([Vector]($api-api-LinkIoT-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()

  1. int16 VECTOR_Size ([Vector]($api-api-LinkIoT-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()

  1. void* VECTOR_Swap ([Vector]($api-api-LinkIoT-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