1# @ohos.application.DataShareExtensionAbility (DataShare ExtensionAbility) (System API) 2 3The **DataShareExtensionAbility** module provides data share services based on the ExtensionAbility. 4 5>**NOTE** 6> 7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - The APIs provided by this module are system APIs. 10> 11> - The APIs of this module can be used only in the stage model. 12 13 14## Modules to Import 15 16```ts 17import { DataShareExtensionAbility } from '@kit.ArkData'; 18``` 19 20## Properties 21 22**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 23 24| Name| Type| Readable| Writable| Description| 25| -------- | -------- | -------- | -------- | -------- | 26| context<sup>10+</sup> | [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md) | Yes| No|Context of the DataShare ExtensionAbility.| 27 28## onCreate 29 30onCreate?(want: Want, callback: AsyncCallback<void>): void 31 32Called by the server to initialize service logic when the DataShare client connects to the DataShareExtensionAbility server. This API can be overridden as required. 33 34**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 35 36**Parameters** 37 38| Name| Type| Mandatory| Description| 39| ----- | ------ | ------ | ------ | 40| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md#want) | Yes | Want information, including the ability name and bundle name.| 41| callback | AsyncCallback<void> | Yes| Callback that returns no value.| 42 43**Example** 44 45```ts 46import { DataShareExtensionAbility, relationalStore } from '@kit.ArkData'; 47import { Want } from '@kit.AbilityKit'; 48 49let DB_NAME = 'DB00.db'; 50let TBL_NAME = 'TBL00'; 51let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS ' 52 + TBL_NAME 53 + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)'; 54let rdbStore: relationalStore.RdbStore; 55 56export default class DataShareExtAbility extends DataShareExtensionAbility { 57 onCreate(want: Want, callback: Function) { 58 relationalStore.getRdbStore(this.context, { 59 name: DB_NAME, 60 securityLevel: relationalStore.SecurityLevel.S3 61 }, (err, data) => { 62 console.info(`getRdbStore done, data : ${data}`); 63 rdbStore = data; 64 rdbStore.executeSql(DDL_TBL_CREATE, [], (err) => { 65 console.error(`executeSql done, error message : ${err}`); 66 }); 67 if (callback) { 68 callback(); 69 } 70 }); 71 } 72}; 73``` 74 75## UpdateOperation<sup>12+</sup> 76 77Represents the batch update operation information. 78 79**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 80 81| Name | Type | Mandatory| Description | 82| --------------- | ------------------------------------------------------------ | ---- | -------------- | 83| UpdateOperation | [dataShare.UpdateOperation](js-apis-data-dataShare-sys.md#updateoperation12) | Yes | Data to update.| 84 85## insert 86 87insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void 88 89Inserts data into the database. This API can be overridden as required. 90 91**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 92 93**Parameters** 94 95| Name| Type| Mandatory| Description| 96| ----- | ------ | ------ | ------ | 97| uri |string | Yes | URI of the data to insert.| 98| valueBucket |[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes| Data to insert.| 99| callback |AsyncCallback<number> | Yes| Callback used to return the index of the data inserted.| 100 101**Example** 102 103```ts 104import { DataShareExtensionAbility, relationalStore, ValuesBucket } from '@kit.ArkData'; 105 106let TBL_NAME = 'TBL00'; 107let rdbStore: relationalStore.RdbStore; 108 109export default class DataShareExtAbility extends DataShareExtensionAbility { 110 insert(uri: string, valueBucket: ValuesBucket, callback: Function) { 111 if (valueBucket === null) { 112 console.error('invalid valueBuckets'); 113 return; 114 } 115 rdbStore.insert(TBL_NAME, valueBucket, (err, ret) => { 116 console.info(`callback ret: ${ret}`); 117 if (callback !== undefined) { 118 callback(err, ret); 119 } 120 }); 121 } 122}; 123``` 124 125## update 126 127update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void 128 129Updates data in the database. This API can be overridden as required. 130 131**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 132 133**Parameters** 134 135| Name| Type| Mandatory| Description| 136| ----- | ------ | ------ | ------ | 137| uri | string | Yes | URI of the data to update.| 138| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for updating data.| 139| valueBucket | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes| New data.| 140| callback | AsyncCallback<number> | Yes| Callback used to return the number of updated data records.| 141 142**Example** 143 144```ts 145import { DataShareExtensionAbility, relationalStore, dataSharePredicates, ValuesBucket } from '@kit.ArkData'; 146 147let TBL_NAME = 'TBL00'; 148let rdbStore: relationalStore.RdbStore; 149 150export default class DataShareExtAbility extends DataShareExtensionAbility { 151 update(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: Function) { 152 if (predicates === null || predicates === undefined) { 153 return; 154 } 155 rdbStore.update(TBL_NAME, valueBucket, predicates, (err, ret) => { 156 if (callback !== undefined) { 157 callback(err, ret); 158 } 159 }); 160 } 161}; 162``` 163 164## batchUpdate<sup>12+</sup> 165 166batchUpdate?( operations: Record<string, Array<UpdateOperation>> , callback: AsyncCallback<Record<string, Array<number>>>): void 167 168Batch updates data into the database. This API is called by the server and can be overridden as required. 169 170**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 171 172**Parameters** 173 174| Name | Type | Mandatory| Description | 175| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------ | 176| operations | Record<string, Array<[UpdateOperation](#updateoperation12)>> | Yes | Collection of the path of the data to update, update conditions, and new data. | 177| callback | AsyncCallback<Record<string, Array<number>>> | Yes | Callback used to return an array of updated data records. The value **-1** means the update operation fails.| 178 179**Example** 180 181```ts 182import { DataShareExtensionAbility, relationalStore, dataShare } from '@kit.ArkData'; 183import { BusinessError } from '@kit.BasicServicesKit' 184 185let TBL_NAME = 'TBL00'; 186let rdbStore: relationalStore.RdbStore; 187 188export default class DataShareExtAbility extends DataShareExtensionAbility { 189 batchUpdate(operations:Record<string, Array<dataShare.UpdateOperation>>, callback:Function) { 190 let recordOps : Record<string, Array<dataShare.UpdateOperation>> = operations; 191 let results : Record<string, Array<number>> = {}; 192 let a = Object.entries(recordOps); 193 for (let i = 0; i < a.length; i++) { 194 let key = a[i][0]; 195 let values = a[i][1]; 196 let result : number[] = []; 197 for (const value of values) { 198 rdbStore.update(TBL_NAME, value.values, value.predicates).then(async (rows) => { 199 console.info('Update row count is ' + rows); 200 result.push(rows); 201 }).catch((err:BusinessError) => { 202 console.info('Update failed, err is ' + JSON.stringify(err)); 203 result.push(-1) 204 }) 205 } 206 results[key] = result; 207 } 208 callback(null, results); 209 } 210}; 211``` 212 213## delete 214 215delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 216 217Deletes data from the database. This API can be overridden as required. 218 219**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 220 221**Parameters** 222 223| Name | Type | Mandatory| Description | 224| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- | 225| uri | string | Yes | URI of the data to delete. | 226| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for deleting data. | 227| callback | AsyncCallback<number> | Yes | Callback used to return the number of data records deleted.| 228 229**Example** 230 231```ts 232import { DataShareExtensionAbility, relationalStore, dataSharePredicates } from '@kit.ArkData'; 233 234let TBL_NAME = 'TBL00'; 235let rdbStore: relationalStore.RdbStore; 236 237export default class DataShareExtAbility extends DataShareExtensionAbility { 238 delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: Function) { 239 if (predicates === null || predicates === undefined) { 240 return; 241 } 242 rdbStore.delete(TBL_NAME, predicates, (err, ret) => { 243 if (callback !== undefined) { 244 callback(err, ret); 245 } 246 }); 247 } 248}; 249``` 250 251## query 252 253query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void 254 255Queries data from the database. This API can be overridden as required. 256 257**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 258 259**Parameters** 260 261| Name| Type| Mandatory| Description| 262| ----- | ------ | ------ | ------ | 263| uri | string | Yes | URI of the data to query.| 264| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for querying data.| 265| columns | Array<string> | Yes| Columns to query. If this parameter is empty, all columns will be queried.| 266| callback | AsyncCallback<Object> | Yes| Callback used to return the result set obtained.| 267 268**Example** 269 270```ts 271import { DataShareExtensionAbility, relationalStore, dataSharePredicates } from '@kit.ArkData'; 272 273let TBL_NAME = 'TBL00'; 274let rdbStore: relationalStore.RdbStore; 275 276export default class DataShareExtAbility extends DataShareExtensionAbility { 277 query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: Function) { 278 if (predicates === null || predicates === undefined) { 279 return; 280 } 281 rdbStore.query(TBL_NAME, predicates, columns, (err, resultSet) => { 282 if (resultSet !== undefined) { 283 console.info(`resultSet.rowCount: ${resultSet.rowCount}`); 284 } 285 if (callback !== undefined) { 286 callback(err, resultSet); 287 } 288 }); 289 } 290}; 291``` 292 293## batchInsert 294 295batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void 296 297Batch inserts data into the database. This API is called by the server and can be overridden as required. 298 299**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 300 301**Parameters** 302 303| Name | Type | Mandatory| Description | 304| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- | 305| uri | string | Yes | URI of the data to insert. | 306| valueBuckets | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to insert. | 307| callback | AsyncCallback<number> | Yes | Callback used to return the number of inserted data records.| 308 309**Example** 310 311```ts 312import { DataShareExtensionAbility, relationalStore, ValuesBucket } from '@kit.ArkData'; 313 314let TBL_NAME = 'TBL00'; 315let rdbStore: relationalStore.RdbStore; 316 317export default class DataShareExtAbility extends DataShareExtensionAbility { 318 batchInsert(uri: string, valueBuckets: Array<ValuesBucket>, callback: Function) { 319 if (valueBuckets === null || valueBuckets.length === undefined) { 320 console.error('invalid valueBuckets'); 321 return; 322 } 323 rdbStore.batchInsert(TBL_NAME, valueBuckets, (err, ret) => { 324 if (callback !== undefined) { 325 callback(err, ret); 326 } 327 }); 328 }; 329}; 330``` 331 332## normalizeUri 333 334normalizeUri?(uri: string, callback: AsyncCallback<string>): void 335 336Normalizes a URI. This API can be overridden as required. 337 338**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 339 340**Parameters** 341 342| Name | Type | Mandatory| Description | 343| -------- | --------------------- | ---- | ----------------------- | 344| uri | string | Yes | [URI](../apis-arkts/js-apis-uri.md#uri) to normalize.| 345| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, the normalized URI is returned. Otherwise, **null** is returned.| 346 347**Example** 348 349```ts 350import { DataShareExtensionAbility } from '@kit.ArkData'; 351import { BusinessError } from '@kit.BasicServicesKit' 352 353export default class DataShareExtAbility extends DataShareExtensionAbility { 354 normalizeUri(uri: string, callback: Function) { 355 let key = 'code'; 356 let value = 0; 357 let err: BusinessError = { 358 code: value, 359 name: key, 360 message: key 361 }; 362 let ret: string = `normalize: ${uri}`; 363 callback(err, ret); 364 } 365}; 366``` 367 368## denormalizeUri 369 370denormalizeUri?(uri: string, callback: AsyncCallback<string>): void 371 372Denormalizes a URI. This API can be overridden as required. 373 374**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider 375 376**Parameters** 377 378| Name | Type | Mandatory| Description | 379| -------- | --------------------- | ---- | ----------------------- | 380| uri | string | Yes | [URI](../apis-arkts/js-apis-uri.md#uri) to denormalize.| 381| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, the denormalized URI is returned. If the URI passed in is returned, denormalization is not required. If denormalization is not supported, **null** is returned.| 382 383**Example** 384 385```ts 386import { DataShareExtensionAbility } from '@kit.ArkData'; 387import { BusinessError } from '@kit.BasicServicesKit' 388 389export default class DataShareExtAbility extends DataShareExtensionAbility { 390 denormalizeUri(uri: string, callback: Function) { 391 let key = 'code'; 392 let value = 0; 393 let err: BusinessError = { 394 code: value, 395 name: key, 396 message: key 397 }; 398 let ret = `denormalize ${uri}`; 399 callback(err, ret); 400 } 401}; 402``` 403