README.md
1# samgr<a name="EN-US_TOPIC_0000001162068341"></a>
2## Introduction<a name="section11660541593"></a>
3
4The **samgr** module is a core module of OpenHarmony. It provides functions, such as start, registration, and query, of system abilities (also called system services).
5
6
7
8## Directory Structure<a name="section161941989596"></a>
9
10```
11/foundation/systemabilitymgr
12├── samgr
13│ ├── bundle.json # Description and build file of samgr
14│ ├── frameworks # Framework implementation
15│ ├── interfaces # APIs
16│ ├── services # Directory for samgr services
17│ ├── test # Test code
18│ ├── utils # Utils
19```
20
21## Usage<a name="section1312121216216"></a>
22
231. Upon receiving a registration message from the system ability (SA) framework, the samgr service saves the system ability information in the local cache.
24
25 ```
26 int32_t SystemAbilityManager::AddSystemAbility(int32_t systemAbilityId, const sptr<IRemoteObject>& ability,
27 const SAExtraProp& extraProp)
28 {
29 if (!CheckInputSysAbilityId(systemAbilityId) || ability == nullptr) {
30 HILOGE("AddSystemAbilityExtra input params is invalid.");
31 return ERR_INVALID_VALUE;
32 }
33 {
34 unique_lock<shared_mutex> writeLock(abilityMapLock_);
35 auto saSize = abilityMap_.size();
36 if (saSize >= MAX_SERVICES) {
37 HILOGE("map size error, (Has been greater than %zu)", saSize);
38 return ERR_INVALID_VALUE;
39 }
40 SAInfo saInfo;
41 saInfo.remoteObj = ability;
42 saInfo.isDistributed = extraProp.isDistributed;
43 saInfo.capability = extraProp.capability;
44 saInfo.permission = Str16ToStr8(extraProp.permission);
45 abilityMap_[systemAbilityId] = std::move(saInfo);
46 HILOGI("insert %{public}d. size : %{public}zu", systemAbilityId, abilityMap_.size());
47 }
48 RemoveCheckLoadedMsg(systemAbilityId);
49 if (abilityDeath_ != nullptr) {
50 ability->AddDeathRecipient(abilityDeath_);
51 }
52
53 u16string strName = Str8ToStr16(to_string(systemAbilityId));
54 if (extraProp.isDistributed && dBinderService_ != nullptr) {
55 dBinderService_->RegisterRemoteProxy(strName, systemAbilityId);
56 HILOGD("AddSystemAbility RegisterRemoteProxy, serviceId is %{public}d", systemAbilityId);
57 }
58 if (systemAbilityId == SOFTBUS_SERVER_SA_ID && !isDbinderStart_) {
59 if (dBinderService_ != nullptr && rpcCallbackImp_ != nullptr) {
60 bool ret = dBinderService_->StartDBinderService(rpcCallbackImp_);
61 HILOGI("start result is %{public}s", ret ? "succeed" : "fail");
62 isDbinderStart_ = true;
63 }
64 }
65 SendSystemAbilityAddedMsg(systemAbilityId, ability);
66 return ERR_OK;
67 }
68 ```
69
702. If the system service requested by the SA framework is a local service, the samgr service locates the proxy object of the system service based on the service ID and then returns the proxy object to the SA framework.
71
72 ```
73 sptr<IRemoteObject> SystemAbilityManager::CheckSystemAbility(int32_t systemAbilityId)
74 {
75 if (!CheckInputSysAbilityId(systemAbilityId)) {
76 HILOGW("CheckSystemAbility CheckSystemAbility invalid!");
77 return nullptr;
78 }
79
80 shared_lock<shared_mutex> readLock(abilityMapLock_);
81 auto iter = abilityMap_.find(systemAbilityId);
82 if (iter != abilityMap_.end()) {
83 HILOGI("found service : %{public}d.", systemAbilityId);
84 return iter->second.remoteObj;
85 }
86 HILOGI("NOT found service : %{public}d", systemAbilityId);
87 return nullptr;
88 }
89 ```
90
913. The samgr service dynamically loads the system service process and system ability. Instead of starting upon system startup, the process starts when the system ability is accessed and loads the specified system ability.
92
93
94 3.1 Inherit from the **SystemAbilityLoadCallbackStub** class and overwrite the **OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject)** and **OnLoadSystemAbilityFail(int32_t systemAbilityId)** methods.
95
96 ```
97 class OnDemandLoadCallback : public SystemAbilityLoadCallbackStub {
98 public:
99 void OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject) override;
100 void OnLoadSystemAbilityFail(int32_t systemAbilityId) override;
101 };
102
103 void OnDemandLoadCallback::OnLoadSystemAbilitySuccess(int32_t systemAbilityId,
104 const sptr<IRemoteObject>& remoteObject) // systemAbilityId is the ID of the system ability to be loaded, and remoteObject indicates the proxy object of the system ability.
105 {
106 cout << "OnLoadSystemAbilitySuccess systemAbilityId:" << systemAbilityId << " IRemoteObject result:" <<
107 ((remoteObject != nullptr) ? "succeed" : "failed") << endl;
108 }
109
110 void OnDemandLoadCallback::OnLoadSystemAbilityFail(int32_t systemAbilityId) // systemAbilityId is the ID of the system ability to be loaded.
111 {
112 cout << "OnLoadSystemAbilityFail systemAbilityId:" << systemAbilityId << endl;
113 }
114 ```
115
116 3.2 Call **LoadSystemAbility(int32_t systemAbilityId, const sptr<ISystemAbilityLoadCallback>& callback)** provided by samgr.
117 ```
118 // Construct a SystemAbilityLoadCallbackStub instance (mentioned in step 3.1).
119 sptr<OnDemandLoadCallback> loadCallback_ = new OnDemandLoadCallback();
120 // Call the LoadSystemAbility method.
121 sptr<ISystemAbilityManager> sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
122 if (sm == nullptr) {
123 cout << "GetSystemAbilityManager samgr object null!" << endl;
124 return;
125 }
126 int32_t result = sm->LoadSystemAbility(systemAbilityId, loadCallback_);
127 if (result != ERR_OK) {
128 cout << "systemAbilityId:" << systemAbilityId << " load failed, result code:" << result << endl;
129 return;
130 }
131 ```
132>**NOTE**:
133>
134>- After the **LoadSystemAbility** method is called, the **OnLoadSystemAbilitySuccess** callback will be invoked if the specified system ability is successfully loaded and the **OnLoadSystemAbilityFail** callback will be invoked if the system ability fails to be loaded.
135>- The dynamically loaded process cannot start upon system startup. You must set **"ondemand": true** in the .cfg file. The following is an example:
136>
137>```
138>{
139>"services" : [{
140> "name" : "listen_test",
141> "path" : ["/system/bin/sa_main", "/system/profile/listen_test.xml"],
142> "ondemand" : true,
143> "uid" : "system",
144> "gid" : ["system", "shell"]
145> }
146>]
147>}
148>```
149>- The **LoadSystemAbility** method applies to dynamic loading of system abilities. In other scenarios, use the **CheckSystemAbility** method to obtain a system ability.
150>- The process name in the .cfg file must be the same as that in the .xml configuration file of the system ability.
151
152## Repositories Involved<a name="section1371113476307"></a>
153
154**System Ability Management Subsystem**
155
156[systemabilitymgr\_safwk](https://gitee.com/openharmony/systemabilitymgr_safwk)
157
158[**systemabilitymgr\_samgr**](https://gitee.com/openharmony/systemabilitymgr_samgr)
159
160[systemabilitymgr\_safwk\_lite](https://gitee.com/openharmony/systemabilitymgr_safwk_lite)
161
162[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite)
163
README_zh.md
1# 系统服务管理部件<a name="ZH-CN_TOPIC_0000001162068341"></a>
2## 简介<a name="section11660541593"></a>
3
4samgr组件是OpenHarmony的核心组件，提供OpenHarmony系统服务启动、注册、查询等功能。
5
6## 系统架构<a name="section342962219551"></a>
7
8**图 1** 系统服务管理系统架构图
9
10
11
12
13## 目录<a name="section161941989596"></a>
14
15```
16/foundation/systemabilitymgr
17├── samgr
18│ ├── bundle.json # 部件描述及编译文件
19│ ├── frameworks # 框架实现存在目录
20│ ├── interfaces # 接口目录
21│ ├── services # 组件服务端目录
22│ ├── test # 测试代码存放目录
23│ ├── utils # 工具类目录
24```
25
26## 说明<a name="section1312121216216"></a>
27
281. samgr服务接收到sa框架层发送的注册消息，会在本地缓存中存入系统服务相关信息。
29
30 ```
31 int32_t SystemAbilityManager::AddSystemAbility(int32_t systemAbilityId, const sptr<IRemoteObject>& ability,
32 const SAExtraProp& extraProp)
33 {
34 if (!CheckInputSysAbilityId(systemAbilityId) || ability == nullptr) {
35 HILOGE("AddSystemAbilityExtra input params is invalid.");
36 return ERR_INVALID_VALUE;
37 }
38 {
39 unique_lock<shared_mutex> writeLock(abilityMapLock_);
40 auto saSize = abilityMap_.size();
41 if (saSize >= MAX_SERVICES) {
42 HILOGE("map size error, (Has been greater than %zu)", saSize);
43 return ERR_INVALID_VALUE;
44 }
45 SAInfo saInfo;
46 saInfo.remoteObj = ability;
47 saInfo.isDistributed = extraProp.isDistributed;
48 saInfo.capability = extraProp.capability;
49 saInfo.permission = Str16ToStr8(extraProp.permission);
50 abilityMap_[systemAbilityId] = std::move(saInfo);
51 HILOGI("insert %{public}d. size : %{public}zu", systemAbilityId, abilityMap_.size());
52 }
53 RemoveCheckLoadedMsg(systemAbilityId);
54 if (abilityDeath_ != nullptr) {
55 ability->AddDeathRecipient(abilityDeath_);
56 }
57
58 u16string strName = Str8ToStr16(to_string(systemAbilityId));
59 if (extraProp.isDistributed && dBinderService_ != nullptr) {
60 dBinderService_->RegisterRemoteProxy(strName, systemAbilityId);
61 HILOGD("AddSystemAbility RegisterRemoteProxy, serviceId is %{public}d", systemAbilityId);
62 }
63 if (systemAbilityId == SOFTBUS_SERVER_SA_ID && !isDbinderStart_) {
64 if (dBinderService_ != nullptr && rpcCallbackImp_ != nullptr) {
65 bool ret = dBinderService_->StartDBinderService(rpcCallbackImp_);
66 HILOGI("start result is %{public}s", ret ? "succeed" : "fail");
67 isDbinderStart_ = true;
68 }
69 }
70 SendSystemAbilityAddedMsg(systemAbilityId, ability);
71 return ERR_OK;
72 }
73 ```
74
752. 对于本地服务而言，samgr服务接收到sa框架层发送的获取消息，会通过服务id，查找到对应服务的代理对象，然后返回给sa框架。
76
77 ```
78 sptr<IRemoteObject> SystemAbilityManager::CheckSystemAbility(int32_t systemAbilityId)
79 {
80 if (!CheckInputSysAbilityId(systemAbilityId)) {
81 HILOGW("CheckSystemAbility CheckSystemAbility invalid!");
82 return nullptr;
83 }
84
85 shared_lock<shared_mutex> readLock(abilityMapLock_);
86 auto iter = abilityMap_.find(systemAbilityId);
87 if (iter != abilityMap_.end()) {
88 HILOGI("found service : %{public}d.", systemAbilityId);
89 return iter->second.remoteObj;
90 }
91 HILOGI("NOT found service : %{public}d", systemAbilityId);
92 return nullptr;
93 }
94 ```
95
963. 动态加载系统服务进程及SystemAbility, 系统进程无需开机启动，而是在SystemAbility被访问的时候按需拉起，并加载指定SystemAbility。
97 3.1 继承SystemAbilityLoadCallbackStub类，并覆写OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject)、OnLoadSystemAbilityFail(int32_t systemAbilityId)方法。
98
99 ```
100 class OnDemandLoadCallback : public SystemAbilityLoadCallbackStub {
101 public:
102 void OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject) override;
103 void OnLoadSystemAbilityFail(int32_t systemAbilityId) override;
104 };
105
106 void OnDemandLoadCallback::OnLoadSystemAbilitySuccess(int32_t systemAbilityId,
107 const sptr<IRemoteObject>& remoteObject) // systemAbilityId为指定加载的SAID，remoteObject为指定systemAbility的代理对象
108 {
109 cout << "OnLoadSystemAbilitySuccess systemAbilityId:" << systemAbilityId << " IRemoteObject result:" <<
110 ((remoteObject != nullptr) ? "succeed" : "failed") << endl;
111 }
112
113 void OnDemandLoadCallback::OnLoadSystemAbilityFail(int32_t systemAbilityId) // systemAbilityId为指定加载的SAID
114 {
115 cout << "OnLoadSystemAbilityFail systemAbilityId:" << systemAbilityId << endl;
116 }
117 ```
118
119 3.2 调用samgr提供的动态加载接口LoadSystemAbility(int32_t systemAbilityId, const sptr<ISystemAbilityLoadCallback>& callback)。
120 ```
121 // 构造步骤1的SystemAbilityLoadCallbackStub子类的实例
122 sptr<OnDemandLoadCallback> loadCallback_ = new OnDemandLoadCallback();
123 // 调用LoadSystemAbility方法
124 sptr<ISystemAbilityManager> sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
125 if (sm == nullptr) {
126 cout << "GetSystemAbilityManager samgr object null!" << endl;
127 return;
128 }
129 int32_t result = sm->LoadSystemAbility(systemAbilityId, loadCallback_);
130 if (result != ERR_OK) {
131 cout << "systemAbilityId:" << systemAbilityId << " load failed, result code:" << result << endl;
132 return;
133 }
134 ```
135>说明：
136>1.LoadSystemAbility方法调用成功后，指定SystemAbility加载成功后会触发回调OnLoadSystemAbilitySuccess，加载失败触发回调OnLoadSystemAbilityFail。
137>2.动态加载的进程cfg文件不能配置为开机启动，需指定"ondemand" : true, 示例如下:
138>```
139>{
140> "services" : [{
141> "name" : "listen_test",
142> "path" : ["/system/bin/sa_main", "/system/profile/listen_test.xml"],
143> "ondemand" : true,
144> "uid" : "system",
145> "gid" : ["system", "shell"]
146> }
147> ]
148>}
149>```
150>3.LoadSystemAbility方法适用于动态加载场景，其他获取SystemAbility场景建议使用CheckSystemAbility方法。
151>4.cfg里进程名称需要与SA的配置xml文件里进程名保持一致
152
153## 相关仓<a name="section1371113476307"></a>
154
155系统服务管理子系统
156
157[systemabilitymgr\_safwk](https://gitee.com/openharmony/systemabilitymgr_safwk)
158
159[**systemabilitymgr\_samgr**](https://gitee.com/openharmony/systemabilitymgr_samgr)
160
161[systemabilitymgr\_safwk\_lite](https://gitee.com/openharmony/systemabilitymgr_safwk_lite)
162
163[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite)
164
165
