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
