1# SystemCapability 2 3## Overview 4 5### System Capabilities and APIs 6 7SystemCapability (SysCap) refers to a standalone feature in the operating system, for example, Bluetooth, Wi-Fi, NFC, or camera. Each SysCap corresponds to a set of APIs, whose availability depends on the support of the target device. Such a set of APIs can be provided in DevEco Studio for association. 8 9 10 11<!--Del-->For details about the SysCap sets in OpenHarmony, see [SysCap List](syscap-list.md).<!--DelEnd--> 12 13### Supported SysCap Set, Associated SysCap Set, and Required SysCap Set 14 15The supported SysCap set, associated SysCap set, and required SysCap set are collections of SysCaps. 16 17The supported SysCap set covers the device capabilities, and the required SysCap set covers the application capabilities. If the SysCap set required by application A is a subset of the SysCap set supported by device N, application A can be distributed to device N for installation and running. Otherwise, application A cannot be distributed. 18 19The associated SysCap set covers the system capabilities of associated APIs that DevEco Studio offers during application development. 20 21 22 23### Devices and Supported SysCap Sets 24 25Each device provides a SysCap set that matches its hardware capability. 26 27The SDK classifies devices into general devices and custom devices. The general devices' supported SysCap set is defined by OpenHarmony, and the custom devices' is defined by device vendors. 28 29 30 31### Mapping Between Devices and SDK Capabilities 32 33The SDK provides a full set of APIs for DevEco Studio. DevEco Studio identifies the supported SysCap set based on the devices selected for the project, filters the APIs contained in the SysCap set, and provides the supported APIs for association (to autocomplete input). 34 35 36 37## How to Develop 38 39<!--Del--> 40### Obtaining the PCID 41 42The Product Compatibility ID (PCID) contains the SysCap information supported by the current device. For the moment, you can obtain the PCID of a device from the device vendor. In the future, you'll be able to obtain the PCIDs of all devices from the authentication center, which is in development. 43 44### Importing the PCID 45 46DevEco Studio allows Product Compatibility ID (PCID) imports for projects. After the imported PCID file is decoded, the SysCap is output and written into the **syscap.json** file. 47 48Right-click the project directory and choose **Import Product Compatibility ID** from the shortcut menu to upload the PCID file and import it to the **syscap.json** file. 49 50 51 52### Configuring the Associated SysCap Set and Required SysCap Set 53 54DevEco Studio automatically configures the associated SysCap set and required SysCap set based on the settings supported by the created project. You can modify these SysCap sets when necessary. 55You can add APIs to the associated SysCap set in DevEco Studio by adding system capabilities. However, note that these APIs may not be supported on the device. Therefore, check whether these APIs are supported before using them. 56Exercise caution when modifying the required SysCap set. Incorrect modifications may result in the application being unable to be distributed to the target device. 57 58```json 59// syscap.json 60{ 61 "devices": { 62 "general": [ // General devices. Each general device supports a SysCap set. Multiple general devices can be configured. 63 "default", 64 "car" 65 ], 66 "custom": [ // Custom devices. 67 { 68 "Custom device": [ 69 "SystemCapability.Communication.SoftBus.Core" 70 ] 71 } 72 ] 73 }, 74 "development": { // The SysCap set in addedSysCaps and the SysCap set supported by each device configured in devices form the associated SysCap set. 75 "addedSysCaps": [ 76 "SystemCapability.Location.Location.Lite" 77 ] 78 }, 79 "production": { // Used to generate the RPCID. Exercise caution when adding this parameter. Under incorrect settings, applications may fail to be distributed to target devices. 80 "addedSysCaps": [], // Intersection of SysCap sets supported by devices configured in devices. It is the required SysCap set with addedSysCaps set and removedSysCaps set. 81 "removedSysCaps": [] // When the required SysCap set is a capability subset of a device, the application can be distributed to the device. 82 } 83} 84``` 85<!--DelEnd--> 86 87<!--RP1--><!--RP1End--> 88 89### Single-Device Application Development 90 91By default, the associated SysCap set and required SysCap set of the application are the same as the supported SysCap set of the device. Exercise caution when modifying the required SysCap set. 92 93 94 95### Cross-Device Application Development 96 97By default, the associated SysCap set of an application is the union of multiple devices' supported SysCap sets, while the required SysCap set is the intersection of the devices' supported SysCap sets. 98 99 100 101### Checking Whether an API Is Available 102 103You can use either the ArkTS or native API to determine whether an API is available. 104 105- ArkTS API 106 107 - Method 1: Use the **canIUse()** API to check whether a SysCap is supported. 108 109 ```ts 110 if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { 111 console.log("This device supports SystemCapability.ArkUI.ArkUI.Full."); 112 } else { 113 console.log("This device does not support SystemCapability.ArkUI.ArkUI.Full."); 114 } 115 ``` 116 117 - Method 2: Import a module using the **import** API. If the current device does not support the module, the import result is **undefined**. Before using an API, you must make sure the API is available. 118 119 ```ts 120 import geolocationManager from '@ohos.geoLocationManager'; 121 122 try { 123 geolocationManager.getCurrentLocation((location) => { 124 console.log('current location: ' + JSON.stringify(location)); 125 }); 126 } catch(err) { 127 console.error('This device does not support location information.' + err); 128 } 129 ``` 130- Native API 131 132 ```c 133 #include <stdio.h> 134 #include <stdlib.h> 135 #include "syscap_ndk.h" 136 137 char syscap[] = "SystemCapability.ArkUI.ArkUI.Full"; 138 bool result = canIUse(syscap); 139 if (result) { 140 printf("SysCap: %s is supported!\n", syscap); 141 } else { 142 printf("SysCap: %s is not supported!\n", syscap); 143 } 144 ``` 145 146You can also find out the SysCap to which an API belongs by referring to the API reference document. 147 148### Checking the Differences Between Devices with a Specific SysCap 149 150The performance of a SysCap may vary by device type. For example, a tablet is superior to a smart wearable device in terms of the camera capability. 151 152```ts 153import userAuth from '@ohos.userIAM.userAuth'; 154 155const authParam : userAuth.AuthParam = { 156 challenge: new Uint8Array(), 157 authType: [userAuth.UserAuthType.PIN], 158 authTrustLevel: userAuth.AuthTrustLevel.ATL1, 159}; 160const widgetParam :userAuth.WidgetParam = { 161 title: 'Enter password', 162}; 163try { 164 let userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); 165 userAuthInstance.start(); 166 console.log('Device authentication succeeded.'); 167} catch (error) { 168 console.error('auth catch error: ' + JSON.stringify(error)); 169} 170``` 171 172### How Do SysCap Differences Arise Between Devices 173 174The device SysCaps in product solutions vary according to the component combination defined by the product solution vendor. The following figure shows the overall process. 175 176 177 1781. A set of operating system source code consists of optional and mandatory components. Different components represent different SysCaps. 179 1802. In a normalized released SDK, APIs are mapped to SysCap sets. 181 1823. Product solution vendors can assemble components based on hardware capabilities and product requirements. 183 1844. The components configured for a product can be system components or proprietary components developed by a third party. Since there is mapping between components and SysCap, the SysCap set of the product can be obtained after all components are assembled. 185 1865. The SysCap set is encoded to generate the PCID. You can import the PCID to DevEco Studio and decode it into SysCaps. During development, compatibility processing is performed to mitigate the SysCap differences of devices. 187 1886. System parameters deployed on devices contain the SysCap set. The system provides native interfaces and application interfaces for components and applications to check whether a specific SysCap is available. 189 1907. During application development, the SysCap set required by the application is encoded into the Required Product Compatibility ID (RPCID) and written into the application installation package. During application installation, the package manager decodes the RPCID to obtain the SysCap set required by the application and compares it with the SysCap set supported by the device. If the SysCap set required by the application is met, the application can be installed on the device. 191 1928. When an application is running on a device, the **canIUse** API can be used to query whether the device is compatible with a specific SysCap. 193
