README.md
1# Distributed DeviceProfile
2
3## Introduction
4
5DeviceProfile is used to manage device hardware capabilities and system software features. A typical device profile includes the device type, device name, OS type, and OS version. By allowing quick access to local and remote device profiles, DeviceProfile lays the foundation for initiating distributed services.
6
7DeviceProfile provides the following functions:
8
9- Inserting, deleting, and querying profiles of local devices.
10- Querying remote device profile information.
11- Subscribing to remote device profile changes.
12- Synchronizing profile information across devices.
13
14The following figure shows the architecture of the DeviceProfile module.
15
16## Architecture
17
18**Figure 1** DeviceProfile component architecture
19
20
21
22
23
24## Directory Structure
25
26The main code directory structure of DeviceProfile is as follows:
27
28```
29├── interfaces
30│ └── innerkits
31│ └── distributeddeviceprofile // innerkits APIs
32├── ohos.build
33├── sa_profile // SAID profile
34│ ├── 6001.xml
35│ └── BUILD.gn
36└── services
37 └── distributeddeviceprofile
38 ├── BUILD.gn
39 ├── include
40 │ ├── authority // Permission verification
41 │ ├── contentsensor // Header file for content sensor data collection
42 │ ├── dbstorage // Header file for database operations
43 │ ├── devicemanager // Header file for device management
44 │ └── subscribemanager // Header file for subscription management
45 ├── src
46 │ ├── authority // Permission verification
47 │ ├── contentsensor // Implementation of content sensor data collection
48 │ ├── dbstorage // Implementation of database operations
49 │ ├── devicemanager // Implementation of device management
50 │ └── subscribemanager // Implementation of subscription management
51 └── test // Test cases
52```
53
54## Constraints
55
56- The devices between which you want to set up a connection must be in the same LAN.
57- Before setting up a connection between two devices, you must bind the devices. For details about the binding process, see the Security subsystem readme file.
58
59## Usage
60
61### Querying Profile Information
62
63* Parameters of **GetDeviceProfile**
64
65| Name | Type | Mandatory| Description |
66| --------- | ---------------------------- | ---- | ----------------------------------- |
67| deviceId | std::string | Yes | ID of the device whose profile is to be queried. A null value indicates the local device.|
68| serviceId | std::string | Yes | Service ID. |
69| profile | ServiceCharacteristicProfile | Yes | Device profile information returned. |
70
71* Sample code
72
73```c++
74// Declare the return value.
75ServiceCharacteristicProfile profile;
76// Call GetDeviceProfile.
77DistributedDeviceProfileClient::GetInstance().GetDeviceProfile(deviceId, serviceId, profile);
78std::string jsonData = profile.GetCharacteristicProfileJson();
79result.append("jsonData:" + jsonData + "\n");
80```
81
82### Inserting Profile Information
83
84* Parameters of **PutDeviceProfile**
85
86| Name | Type | Mandatory| Description |
87| --------- | ---------------------------- | ---- | ----------------------------------- |
88| profile | ServiceCharacteristicProfile | Yes | Profile information to insert. |
89
90* Sample code
91
92```c++
93// Declare and fill in the data to insert.
94ServiceCharacteristicProfile profile;
95profile.SetServiceId(serviceId);
96profile.SetServiceType(serviceType);
97nlohmann::json j;
98j["testVersion"] = "3.0.0";
99j["testApiLevel"] = API_LEVEL;
100profile.SetCharacteristicProfileJson(j.dump());
101// Call PutDeviceProfile.
102DistributedDeviceProfileClient::GetInstance().PutDeviceProfile(profile);
103```
104
105### Deleting Profile Information
106
107* Parameters of **DeleteDeviceProfile**
108
109| Name | Type | Mandatory| Description |
110| --------- | ---------------------------- | ---- | ----------------------------------- |
111| serviceId | std::string | Yes | ID of the service record to delete. |
112
113* Sample code
114
115```c++
116// Declare and fill in the data to delete.
117std::string serviceId = "test";
118// DeleteDeviceProfile
119DistributedDeviceProfileClient::GetInstance().DeleteDeviceProfile(serviceId);
120```
121
122### Synchronizing Profile Information
123
124* Parameters of **SyncDeviceProfile**
125
126| Name | Type | Mandatory| Description |
127| --------- | ---------------------------- | ---- | ----------------------------------- |
128| syncOption| SyncOption | Yes | Synchronization range and mode. |
129| syncCb | IProfileEventCallback | Yes | Callback used to return the synchronization result. |
130
131* Sample code
132
133```c++
134// Define the synchronization mode and range.
135SyncOptions syncOption;
136syncOption.SetSyncMode((OHOS::DeviceProfile::SyncMode)atoi(mode.c_str()));
137for (const auto& deviceId : deviceIds) {
138 syncOption.AddDevice(deviceId);
139}
140// Call SyncDeviceProfile.
141DistributedDeviceProfileClient::GetInstance().SyncDeviceProfile(syncOption,
142 std::make_shared<ProfileEventCallback>());
143```
144
145### Subscribing to Profile Events (Synchronization and Change Events)
146
147* Parameters of **SubscribeProfileEvents**
148
149| Name | Type | Mandatory| Description |
150| -------------- | ---------------------------- | ---- | ----------------------------------- |
151| subscribeInfos | SubscribeInfo | Yes | Type of the event to subscribe to. |
152| eventCb | IProfileEventCallback | Yes | Callback used to return the subscription event. |
153| failedEvents | ProfileEvent | Yes | Failure event. |
154
155* Sample code
156
157```c++
158auto callback = std::make_shared<ProfileEventCallback>();
159std::list<SubscribeInfo> subscribeInfos;
160
161// Subscribe to the EVENT_PROFILE_CHANGED event.
162ExtraInfo extraInfo;
163extraInfo["deviceId"] = deviceId;
164extraInfo["serviceIds"] = serviceIds;
165SubscribeInfo changeEventInfo;
166changeEventInfo.profileEvent = ProfileEvent::EVENT_PROFILE_CHANGED;
167changeEventInfo.extraInfo = std::move(extraInfo);
168subscribeInfos.emplace_back(changeEventInfo);
169
170// Subscribe to the EVENT_SYNC_COMPLETED event.
171SubscribeInfo syncEventInfo;
172syncEventInfo.profileEvent = ProfileEvent::EVENT_SYNC_COMPLETED;
173subscribeInfos.emplace_back(syncEventInfo);
174
175// Call SubscribeProfileEvents.
176std::list<ProfileEvent> failedEvents;
177DistributedDeviceProfileClient::GetInstance().SubscribeProfileEvents(subscribeInfos,
178 callback, failedEvents);
179
180// Cancel the subscription.
181std::list<ProfileEvent> profileEvents;
182profileEvents.emplace_back(ProfileEvent::EVENT_PROFILE_CHANGED);
183DistributedDeviceProfileClient::GetInstance().UnsubscribeProfileEvents(profileEvents,
184 callback, failedEvents);
185```
186
187## Repositories Involved
188
189[**deviceprofile_device_info_manager**](https://gitee.com/openharmony/deviceprofile_device_info_manager)
190
README_zh.md
1# 分布式DeviceProfile部件<a name="ZH-CN_TOPIC_0000001128264105"></a>
2
3- [简介](#section11660541593)
4- [目录](#section1464106163817)
5- [约束](#section1718733212019)
6- [使用](#section10729231131110)
7- [相关仓](#section176111311166)
8
9## 简介<a name="section11660541593"></a>
10
11DeviceProfile是设备硬件能力和系统软件特征的管理器，典型的Profile有设备类型、设备名称、设备OS类型、OS版本号等。DeviceProfile提供快速访问本地和远端设备Profile的能力，是发起分布式业务的基础。主要功能如下：
12
13- 本地设备Profile的插入、删除、查询。
14- 远程设备Profile的查询。
15- 订阅远程Profile变化的通知。
16- 跨设备同步Profile。
17
18DeviceProfile模块组成如下图所示：
19
20## 系统架构<a name="section13587185873516"></a>
21
22**图 1** DeviceProfile组件架构图<a name="fig4460722185514"></a>
23
24
25
26
27
28## 目录<a name="section1464106163817"></a>
29
30DeviceProfile主要代码目录结构如下：
31
32```
33├── interfaces
34│ └── innerkits
35│ └── distributeddeviceprofile // innerkits接口
36├── ohos.build
37├── sa_profile // said声明文件
38│ ├── 6001.xml
39│ └── BUILD.gn
40└── services
41 └── distributeddeviceprofile
42 ├── BUILD.gn
43 ├── include
44 │ ├── authority // 权限校验
45 │ ├── contentsensor // CS数据采集头文件
46 │ ├── dbstorage // 数据库操作头文件
47 │ ├── devicemanager // 设备管理头文件
48 │ └── subscribemanager // 订阅管理头文件
49 ├── src
50 │ ├── authority // 权限校验
51 │ ├── contentsensor // CS数据采集实现
52 │ ├── dbstorage // 数据库操作实现
53 │ ├── devicemanager // 设备管理实现
54 │ └── subscribemanager // 订阅管理实现
55 └── test // 测试用例
56```
57
58## 约束<a name="section1718733212019"></a>
59
60- 组网设备需在同一局域网中。
61- 组网之前，需先完成设备绑定，绑定流程参见安全子系统中说明。
62
63## 使用<a name="section10729231131110"></a>
64
65### 查询Profile信息
66
67* GetDeviceProfile参数描述
68
69| 名称 | 类型 | 必填 | 描述 |
70| --------- | ---------------------------- | ---- | ----------------------------------- |
71| deviceId | std::string | 是 | 查询指定设备的profile,空值表示查询本地 |
72| serviceId | std::string | 是 | 查询的service id |
73| profile | ServiceCharacteristicProfile | 是 | 返回值 |
74
75* 代码示例
76
77```c++
78// 声明返回值
79ServiceCharacteristicProfile profile;
80// 执行查询接口GetDeviceProfile
81DistributedDeviceProfileClient::GetInstance().GetDeviceProfile(deviceId, serviceId, profile);
82std::string jsonData = profile.GetCharacteristicProfileJson();
83result.append("jsonData:" + jsonData + "\n");
84```
85
86### 插入Profile信息
87
88* PutDeviceProfile参数描述
89
90| 名称 | 类型 | 必填 | 描述 |
91| --------- | ---------------------------- | ---- | ----------------------------------- |
92| profile | ServiceCharacteristicProfile | 是 | 需要插入的profile信息 |
93
94* 代码示例
95
96```c++
97// 声明并填充插入数据
98ServiceCharacteristicProfile profile;
99profile.SetServiceId(serviceId);
100profile.SetServiceType(serviceType);
101nlohmann::json j;
102j["testVersion"] = "3.0.0";
103j["testApiLevel"] = API_LEVEL;
104profile.SetCharacteristicProfileJson(j.dump());
105// 执行插入接口PutDeviceProfile
106DistributedDeviceProfileClient::GetInstance().PutDeviceProfile(profile);
107```
108
109### 删除Profile信息
110
111* DeleteDeviceProfile参数描述
112
113| 名称 | 类型 | 必填 | 描述 |
114| --------- | ---------------------------- | ---- | ----------------------------------- |
115| serviceId | std::string | 是 | 删除特定serviceid的记录 |
116
117* 代码示例
118
119```c++
120// 声明并填充插入数据
121std::string serviceId = "test";
122// DeleteDeviceProfile
123DistributedDeviceProfileClient::GetInstance().DeleteDeviceProfile(serviceId);
124```
125
126### 同步Profile信息
127
128* SyncDeviceProfile参数描述
129
130| 名称 | 类型 | 必填 | 描述 |
131| --------- | ---------------------------- | ---- | ----------------------------------- |
132| syncOption| SyncOption | 是 | 指定同步范围和模式 |
133| syncCb | IProfileEventCallback | 是 | 同步结果回调 |
134
135* 代码示例
136
137```c++
138// 定义同步模式和范围
139SyncOptions syncOption;
140syncOption.SetSyncMode((OHOS::DeviceProfile::SyncMode)atoi(mode.c_str()));
141for (const auto& deviceId : deviceIds) {
142 syncOption.AddDevice(deviceId);
143}
144// 执行同步接口
145DistributedDeviceProfileClient::GetInstance().SyncDeviceProfile(syncOption,
146 std::make_shared<ProfileEventCallback>());
147```
148
149### 订阅Profile事件（同步、变更事件）
150
151* SubscribeProfileEvents参数描述
152
153| 名称 | 类型 | 必填 | 描述 |
154| -------------- | ---------------------------- | ---- | ----------------------------------- |
155| subscribeInfos | SubscribeInfo | 是 | 指定订阅的事件类型 |
156| eventCb | IProfileEventCallback | 是 | 订阅事件回调 |
157| failedEvents | ProfileEvent | 是 | 失败事件 |
158
159* 代码示例
160
161```c++
162auto callback = std::make_shared<ProfileEventCallback>();
163std::list<SubscribeInfo> subscribeInfos;
164
165// 订阅EVENT_PROFILE_CHANGED事件
166ExtraInfo extraInfo;
167extraInfo["deviceId"] = deviceId;
168extraInfo["serviceIds"] = serviceIds;
169SubscribeInfo changeEventInfo;
170changeEventInfo.profileEvent = ProfileEvent::EVENT_PROFILE_CHANGED;
171changeEventInfo.extraInfo = std::move(extraInfo);
172subscribeInfos.emplace_back(changeEventInfo);
173
174// 订阅EVENT_SYNC_COMPLETED事件
175SubscribeInfo syncEventInfo;
176syncEventInfo.profileEvent = ProfileEvent::EVENT_SYNC_COMPLETED;
177subscribeInfos.emplace_back(syncEventInfo);
178
179// 执行订阅接口
180std::list<ProfileEvent> failedEvents;
181DistributedDeviceProfileClient::GetInstance().SubscribeProfileEvents(subscribeInfos,
182 callback, failedEvents);
183
184// 解除订阅
185std::list<ProfileEvent> profileEvents;
186profileEvents.emplace_back(ProfileEvent::EVENT_PROFILE_CHANGED);
187DistributedDeviceProfileClient::GetInstance().UnsubscribeProfileEvents(profileEvents,
188 callback, failedEvents);
189```
190
191## 相关仓<a name="section176111311166"></a>
192
193[**deviceprofile_device_info_manager**](https://gitee.com/openharmony/deviceprofile_device_info_manager)
