• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Samgr
2## Introduction
3
4The System Ability Manager (Samgr) component is a core component of OpenHarmony. It provides functions related to system abilities (also called system services), including the startup, registration, and query.
5
6## System Architecture
7
8Figure 1 Architecture of Samgr
9
10
11![](figures/en-us_image_0000001115820566.png)
12
13## Directory Structure
14
15```
16/foundation/systemabilitymgr
17├── samgr
18│   ├── bundle.json  # Description and build file of Samgr
19│   ├── frameworks   # Framework implementation
20│   ├── interfaces   # APIs
21│   ├── services     # Directory for the Samgr service
22│   ├── test         # Test code
23│   ├── utils        # Utils
24```
25
26## Description
27
281.  Upon receiving a registration message from the system ability framework, the Samgr service saves the system ability information 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) {
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.  If the system service requested by the system ability framework is a local service, the Samgr service locates the proxy object of the system service based on the service ID and returns the proxy object to the system ability framework.
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. 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.
97
98    3.1 Inherit from the **SystemAbilityLoadCallbackStub** class and override the **OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject)** and **OnLoadSystemAbilityFail(int32_t systemAbilityId)** methods.
99
100    ```
101    class OnDemandLoadCallback : public SystemAbilityLoadCallbackStub {
102    public:
103        void OnLoadSystemAbilitySuccess(int32_t systemAbilityId, const sptr<IRemoteObject>& remoteObject) override;
104        void OnLoadSystemAbilityFail(int32_t systemAbilityId) override;
105    };
106
107    void OnDemandLoadCallback::OnLoadSystemAbilitySuccess(int32_t systemAbilityId,
108        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.
109    {
110        cout << "OnLoadSystemAbilitySuccess systemAbilityId:" << systemAbilityId << " IRemoteObject result:" <<
111            ((remoteObject != nullptr) ? "succeed" : "failed") << endl;
112    }
113
114    void OnDemandLoadCallback::OnLoadSystemAbilityFail(int32_t systemAbilityId) // systemAbilityId is the ID of the system ability to be loaded.
115    {
116        cout << "OnLoadSystemAbilityFail systemAbilityId:" << systemAbilityId << endl;
117    }
118    ```
119
120    3.2 Call **LoadSystemAbility(int32_t systemAbilityId, const sptr<ISystemAbilityLoadCallback>& callback)** provided by Samgr.
121
122    ```
123    // Construct a SystemAbilityLoadCallbackStub instance (mentioned in step 3.1).
124    sptr<OnDemandLoadCallback> loadCallback_ = new OnDemandLoadCallback();
125    // Call the LoadSystemAbility method.
126    sptr<ISystemAbilityManager> sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
127    if (sm == nullptr) {
128        cout << "GetSystemAbilityManager samgr object null!" << endl;
129        return;
130    }
131    int32_t result = sm->LoadSystemAbility(systemAbilityId, loadCallback_);
132    if (result != ERR_OK) {
133        cout << "systemAbilityId:" << systemAbilityId << " load failed, result code:" << result << endl;
134        return;
135    }
136    ```
137>NOTE
138>
139>1. After **LoadSystemAbility** 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.
140>
141>2. The dynamically loaded process cannot start upon system startup. You must set **"ondemand": true** in the .cfg file. The following is an example:
142>
143>```
144>{
145>"services" : [{
146>    "name" : "listen_test",
147>    "path" : ["/system/bin/sa_main", "/system/profile/listen_test.json"],
148>    "ondemand" : true,
149>    "uid" : "system",
150>    "gid" : ["system", "shell"]
151>    }
152>]
153>}
154>```
155>3. The **LoadSystemAbility** method applies to dynamic loading of system abilities. In other scenarios, use the **CheckSystemAbility** method to obtain a system ability.
156>4. The process name in the .cfg file must be the same as that in the .xml configuration file of the system ability.
157
158## Repositories Involved
159
160Samgr
161
162[systemabilitymgr\_safwk](https://gitee.com/openharmony/systemabilitymgr_safwk)
163
164[**systemabilitymgr\_samgr**](https://gitee.com/openharmony/systemabilitymgr_samgr)
165
166[systemabilitymgr\_safwk\_lite](https://gitee.com/openharmony/systemabilitymgr_safwk_lite)
167
168[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite)
169