1# safwk 2## Introduction 3 4The System Ability Framework (safwk) component defines how to implement system abilities in OpenHarmony and provides APIs to start and register system abilities. 5 6## System Architecture 7 8**Figure 1** Architecture of safwk 9 10 11 12 13## Directory Structure 14 15``` 16/foundation/systemabilitymgr 17│── safwk # Directory of safwk 18│ ├── bundle.json # Description and build file of safwk 19│ ├── etc # Configuration files 20│ ├── interfaces # APIs exposed externally 21│ ├── services # Service implementation 22│ ├── test # Test cases 23``` 24 25## Usage 26 27### Available APIs 28 29| API | Description | 30| ------------------------------------------------------------ | -------------------------------------- | 31| sptr\<IRemoteObject> GetSystemAbility(int32_t systemAbilityId); | Obtains the remote procedure call (RPC) object of a system ability. | 32| bool Publish(sptr\<IRemoteObject> systemAbility); | Publishes a system ability. | 33| virtual void DoStartSAProcess(const std::string& profilePath) = 0; | Enables a system ability based on its profile.| 34 35### How to Use 36 37A system ability is implemented by using a XXX.cfg, a profile.xml, and a libXXX.z.so. The init process starts the SystemAbility process by executing the corresponding XXX.cfg file. 38 39**Implementing a System Ability in C++** 40 41The sample code is as follows: 42 43**1. Define the *IXXX* class for IPC.** 44 45The *IXXX* class is used to define the functions for the system ability to provide specific capabilities. To define this class, inherit from the **IRemoteBroker** class provided by OpenHarmony for Inter-Process Communication (IPC) and implement the **DECLARE\_INTERFACE\_DESCRIPTOR\(*XXX*)** that uniquely identifies this class. The identifier is used for IPC verification. 46 47``` 48namespace OHOS { 49class IListenAbility : public IRemoteBroker { 50public: 51 virtual int AddVolume(int volume) = 0; 52 53public: 54 enum { 55 ADD_VOLUME = 1, 56 }; 57public: 58 DECLARE_INTERFACE_DESCRIPTOR(u"OHOS.test.IListenAbility"); 59}; 60} 61``` 62 63**2. Define the *XXX*Proxy class for client communication.** 64 65``` 66namespace OHOS { 67class ListenAbilityProxy : public IRemoteProxy<IListenAbility> { 68public: 69 int AddVolume(int volume); 70 71 explicit ListenAbilityProxy(const sptr<IRemoteObject>& impl) 72 : IRemoteProxy<IListenAbility>(impl) 73 { 74 } 75 76private: 77 static inline BrokerDelegator<ListenAbilityProxy> delegator_; 78}; 79} // namespace OHOS 80``` 81 82**3. Define the *XXX*Stub class for server communication.** 83 84``` 85namespace OHOS { 86int32_t ListenAbilityStub::OnRemoteRequest(uint32_t code, 87 MessageParcel& data, MessageParcel &reply, MessageOption &option) 88{ 89 switch (code) { 90 case ADD_VOLUME: { 91 return reply.WriteInt32(AddVolume(data.ReadInt32())); 92 } 93 94 default: 95 return IPCObjectStub::OnRemoteRequest(code, data, reply, option); 96 } 97} 98} 99``` 100 101**4. Implement a system ability.** 102 103``` 104namespace { 105constexpr OHOS::HiviewDFX::HiLogLabel LABEL = {LOG_CORE, 0xD001800, "SA_TST"}; 106} 107 108REGISTER_SYSTEM_ABILITY_BY_ID(ListenAbility, DISTRIBUTED_SCHED_TEST_LISTEN_ID, true); 109 110ListenAbility::ListenAbility(int32_t saId, bool runOnCreate) : SystemAbility(saId, runOnCreate) 111{ 112 HiLog::Info(LABEL, ":%s called", __func__); 113 HiLog::Info(LABEL, "ListenAbility()"); 114} 115 116ListenAbility::~ListenAbility() 117{ 118 HiLog::Info(LABEL, "~ListenAbility()"); 119} 120 121int ListenAbility::AddVolume(int volume) 122{ 123 pid_t current = getpid(); 124 HiLog::Info(LABEL, "ListenAbility::AddVolume volume = %d, pid = %d.", volume, current); 125 return (volume + 1); 126} 127 128void ListenAbility::OnDump() 129{ 130} 131 132void ListenAbility::OnStart() 133{ 134 HiLog::Info(LABEL, "ListenAbility::OnStart()"); 135 HiLog::Info(LABEL, "ListenAbility:%s called:-----Publish------", __func__); 136 bool res = Publish(this); 137 if (res) { 138 HiLog::Error(LABEL, "ListenAbility: res == false"); 139 } 140 HiLog::Info(LABEL, "ListenAbility:%s called:AddAbilityListener_OS_TST----beg-----", __func__); 141 AddSystemAbilityListener(DISTRIBUTED_SCHED_TEST_OS_ID); 142 HiLog::Info(LABEL, "ListenAbility:%s called:AddAbilityListener_OS_TST----end-----", __func__); 143 144 HiLog::Info(LABEL, "ListenAbility:%s called:StopAbility_OS_TST----beg-----", __func__); 145 StopAbility(DISTRIBUTED_SCHED_TEST_OS_ID); 146 HiLog::Info(LABEL, "ListenAbility:%s called:StopAbility_OS_TST----end-----", __func__); 147 return; 148} 149 150void ListenAbility::OnStop() 151{ 152} 153``` 154 155**5. Configure the system ability.** 156 157Configure the profile of the system ability so that the system ability can be loaded and registered. The configuration procedure is as follows: 158 159Create a folder named **sa_profile** in the root directory of the subsystem. Then, create two files in this folder, including an XML file prefixed with the service ID of the system ability and a **BUILD.gn** file. 160 161Sample *serviceid*.xml file: 162 163``` 164<?xml version="1.0" encoding="UTF-8"?> 165<info> 166 <process>listen_test</process> 167 <systemability> 168 <name>serviceid</name> 169 <libpath>/system/lib64/liblistentest.z.so</libpath> 170 <run-on-create>true</run-on-create> 171 <distributed>false</distributed> 172 <dump-level>1</dump-level> 173</systemability> 174</info> 175``` 176 177Sample **BUILD.gn** file: 178 179``` 180import("//build/ohos/sa_profile/sa_profile.gni") 181ohos_sa_profile("xxx_sa_profile") { 182 sources = [ 183 "serviceid.xml" 184 ] 185 subsystem_name = "systemabilitymgr" 186} 187``` 188 189>**NOTE** 190>1. Set **process** to the name of the process where the system ability will run. This parameter is mandatory. 191>2. The *serviceid*.xml file can contain only one **systemability** node. Multiple **systemability** nodes will cause a build failure. 192>3. Set **name** to the service ID registered in the code for the system ability. This parameter is mandatory. 193>4. Set **libpath** to the path for loading the system ability. This parameter is mandatory. 194>5. Set **run-on-create** to **true** if you want to register this system ability with the Samgr component immediately after the process is started. Set it to **false** if you want the system ability to start only when it is accessed. This parameter is mandatory. 195>6. Set **distributed** to **true** if this system ability allows cross-device access. Set it to **false** if it allows IPC only on the local device. 196>7. **bootphase** specifies the startup priority of the system ability. The value can be **BootStartPhase** (highest), **CoreStartPhase**, or **OtherStartPhase** (lowest). In the same process, system abilities of a lower priority can be started and registered only after those of a higher priority have all been started and registered. This parameter is optional. The default value is **OtherStartPhase**. 197>8. **dump-level** specifies the level supported by the system dumper. The default value is **1**. 198>9. In the **BUILD.gn** file, set **subsystem_name** to the subsystem name, and add the list of system abilities to be configured for the subsystem in **sources**. Multiple system abilities can be configured. 199 200After the preceding steps are complete, an XML file named by the process will be generated in the **out**, for example, **out\...\system\profile\listen_test.xml**. 201 202**6. Configure the .cfg file.** 203 204The .cfg file contains the native process startup policy provided by Linux. During the system startup process, the init process parses the .cfg file to start the native process. 205 206``` 207{ 208 "jobs" : [{ 209 "name" : "post-fs-data", 210 "cmds" : [ 211 "start listen_test" 212 ] 213 } 214 ], 215 "services" : [{ 216 "name" : "listen_test", 217 "path" : ["/system/bin/sa_main", "/system/profile/listen_test.xml"], 218 "uid" : "system", 219 "gid" : ["system", "shell"] 220 } 221 ] 222} 223``` 224 225>**NOTE** 226> 227>For details about the implementation of listen_ability, see **test/services/safwk/unittest/common/listen_ability**. 228 229## Repositories Involved 230 231Samgr 232 233[**systemabilitymgr\_safwk**](https://gitee.com/openharmony/systemabilitymgr_safwk) 234 235[systemabilitymgr\_samgr](https://gitee.com/openharmony/systemabilitymgr_samgr) 236 237[systemabilitymgr\_safwk\_lite](https://gitee.com/openharmony/systemabilitymgr_safwk_lite) 238 239[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite) 240
