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

Data Structures

Macros

Typedefs

Enumerations

Functions

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

#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

#define GET_IUNKNOWN( T)   ([IUnknown](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

#define GET_OFFSIZE( T,  member )   (long)((char *)&(((T *)(0))->member))

Description:

Calculates the offset of the member in the T type.

Parameters:

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 interface.

When developing a subclass of the IUnknown class, you can use this macro to inherit the structures of the IUnknown 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 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

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

#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

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

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.

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.

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

TaskType

enum [TaskType](Samgr.md#ga026844c14ab62f42a2e19b54d622609b)

Description:

Enumerates task types.

These enumerations are used for configuring the task type.

Function Documentation

IUNKNOWN_AddRef()

int IUNKNOWN_AddRef ([IUnknown](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()

int IUNKNOWN_QueryInterface ([IUnknown](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:

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 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:

Returns:

**** Indicates the number of IUnknown 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.

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.

Parameters:

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:

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:

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 service to broadcast messages. The value of reference counting is incremented by one each time this function is called.

Parameters:

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 service to broadcast messages.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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