README.md
1# samgr<a name="EN-US_TOPIC_0000001162068341"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Usage](#section1312121216216)
6- [Repositories Involved](#section1371113476307)
7
8## Introduction<a name="section11660541593"></a>
9
10The **samgr** module is a core module of OpenHarmony. It provides functions related to system abilities \(also called system services\), including system ability \(SA\) startup, registration, and query.
11
12
13
14## Directory Structure<a name="section161941989596"></a>
15
16```
17/foundation/distributedschedule/samgr/services/samgr/
18├── native
19│ ├── BUILD.gn # Compilation script
20│ ├── include # Header files
21│ ├── samgr.rc # RC file for starting samgr
22│ ├── source # Source code
23│ ├── test # Test code
24```
25
26## Usage<a name="section1312121216216"></a>
27
281. After receiving the registration message from the SA framework, the samgr service saves information about the particular SA in the local cache.
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 || (!CheckCapability(extraProp.capability))) {
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 : %zu,", systemAbilityId, abilityMap_.size());
52 }
53 if (abilityDeath_ != nullptr) {
54 ability->AddDeathRecipient(abilityDeath_);
55 }
56 FindSystemAbilityManagerNotify(systemAbilityId, ADD_SYSTEM_ABILITY_TRANSACTION);
57 u16string strName = Str8ToStr16(to_string(systemAbilityId));
58 if (extraProp.isDistributed && dBinderService_ != nullptr) {
59 dBinderService_->RegisterRemoteProxy(strName, ability);
60 HILOGD("AddSystemAbility RegisterRemoteProxy, serviceId is %{public}d", systemAbilityId);
61 }
62 if (systemAbilityDataStorage_ == nullptr) {
63 HILOGE("AddSystemAbility systemAbilityDataStorage not init!");
64 return ERR_NO_INIT;
65 }
66 if (extraProp.isDistributed) {
67 systemAbilityDataStorage_->ClearSyncRecords();
68 DoInsertSaData(strName, ability, extraProp);
69 }
70 }
71 ```
72
732. If the SA requested by the SA framework is a local SA, the samgr service searches for the proxy object of the SA based on the SA ID and then returns the proxy object to the SA framework.
74
75 ```
76 sptr<IRemoteObject> SystemAbilityManager::CheckSystemAbility(int32_t systemAbilityId)
77 {
78 if (!CheckInputSysAbilityId(systemAbilityId)) {
79 return nullptr;
80 }
81
82 std::string selectedDeviceId;
83 if (CheckRemoteSa(to_string(systemAbilityId), selectedDeviceId)) {
84 return CheckSystemAbility(systemAbilityId, selectedDeviceId);
85 }
86
87 shared_lock<shared_mutex> readLock(abilityMapLock_);
88 auto iter = abilityMap_.find(systemAbilityId);
89 if (iter != abilityMap_.end()) {
90 auto callingUid = IPCSkeleton::GetCallingUid();
91 if (IsSystemApp(callingUid) || CheckPermission(iter->second.permission)) {
92 return iter->second.remoteObj;
93 }
94 return nullptr;
95 }
96 return nullptr;
97 }
98 ```
99
100
101## Repositories Involved<a name="section1371113476307"></a>
102
103Distributed Scheduler subsystem
104
105distributedschedule\_dms\_fwk
106
107distributedschedule\_safwk
108
109**distributedschedule\_samgr**
110
111distributedschedule\_safwk\_lite
112
113hdistributedschedule\_samgr\_lite
114
115distributedschedule\_dms\_fwk\_lite
116
117
README_zh.md
1# samgr组件<a name="ZH-CN_TOPIC_0000001162068341"></a>
2## 简介<a name="section11660541593"></a>
3
4samgr组件是OpenHarmony的核心组件，提供OpenHarmony系统服务启动、注册、查询等功能。
5
6
7
8## 目录<a name="section161941989596"></a>
9
10```
11/foundation/distributedschedule
12├── samgr
13│ ├── bundle.json # 部件描述及编译文件
14│ ├── frameworks # 框架实现存在目录
15│ ├── interfaces # 接口目录
16│ ├── services # 组件服务端目录
17│ ├── test # 测试代码存放目录
18│ ├── utils # 工具类目录
19```
20
21## 说明<a name="section1312121216216"></a>
22
231. samgr服务接收到sa框架层发送的注册消息，会在本地缓存中存入系统服务相关信息。
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. 对于本地服务而言，samgr服务接收到sa框架层发送的获取消息，会通过服务id，查找到对应服务的代理对象，然后返回给sa框架。
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. 动态加载系统服务进程及SystemAbility, 系统进程无需开机启动，而是在SystemAbility被访问的时候按需拉起，并加载指定SystemAbility。
92 3.1 继承SystemAbilityLoadCallbackStub类，并覆写OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject)、OnLoadSystemAbilityFail(int32_t systemAbilityId)方法。
93
94 ```
95 class OnDemandLoadCallback : public SystemAbilityLoadCallbackStub {
96 public:
97 void OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject) override;
98 void OnLoadSystemAbilityFail(int32_t systemAbilityId) override;
99 };
100
101 void OnDemandLoadCallback::OnLoadSystemAbilitySuccess(int32_t systemAbilityId,
102 const sptr<IRemoteObject>& remoteObject) // systemAbilityId为指定加载的SAID，remoteObject为指定systemAbility的代理对象
103 {
104 cout << "OnLoadSystemAbilitySuccess systemAbilityId:" << systemAbilityId << " IRemoteObject result:" <<
105 ((remoteObject != nullptr) ? "succeed" : "failed") << endl;
106 }
107
108 void OnDemandLoadCallback::OnLoadSystemAbilityFail(int32_t systemAbilityId) // systemAbilityId为指定加载的SAID
109 {
110 cout << "OnLoadSystemAbilityFail systemAbilityId:" << systemAbilityId << endl;
111 }
112 ```
113
114 3.2 调用samgr提供的动态加载接口LoadSystemAbility(int32_t systemAbilityId, const sptr<ISystemAbilityLoadCallback>& callback)。
115 ```
116 // 构造步骤1的SystemAbilityLoadCallbackStub子类的实例
117 sptr<OnDemandLoadCallback> loadCallback_ = new OnDemandLoadCallback();
118 // 调用LoadSystemAbility方法
119 sptr<ISystemAbilityManager> sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
120 if (sm == nullptr) {
121 cout << "GetSystemAbilityManager samgr object null!" << endl;
122 return;
123 }
124 int32_t result = sm->LoadSystemAbility(systemAbilityId, loadCallback_);
125 if (result != ERR_OK) {
126 cout << "systemAbilityId:" << systemAbilityId << " load failed, result code:" << result << endl;
127 return;
128 }
129 ```
130>说明：
131>1.LoadSystemAbility方法调用成功后，指定SystemAbility加载成功后会触发回调OnLoadSystemAbilitySuccess，加载失败触发回调OnLoadSystemAbilityFail。
132>2.动态加载的进程cfg文件不能配置为开机启动，需指定"dynamic" : true, 示例如下:
133>```
134>{
135> "services" : [{
136> "name" : "listen_test",
137> "path" : ["/system/bin/sa_main", "/system/profile/listen_test.xml"],
138> "dynamic" : true,
139> "uid" : "system",
140> "gid" : ["system", "shell"]
141> }
142> ]
143>}
144>```
145>3.LoadSystemAbility方法适用于动态加载场景，其他获取SystemAbility场景建议使用CheckSystemAbility方法。
146
147## 相关仓<a name="section1371113476307"></a>
148
149系统服务管理子系统
150
151[distributedschedule\_safwk](https://gitee.com/openharmony/distributedschedule_safwk)
152
153[**distributedschedule\_samgr**](https://gitee.com/openharmony/distributedschedule_samgr)
154
155[distributedschedule\_safwk\_lite](https://gitee.com/openharmony/distributedschedule_safwk_lite)
156
157[distributedschedule\_samgr\_lite](https://gitee.com/openharmony/distributedschedule_samgr_lite)
158
159
