@ohos.data.dataShare (Data Sharing)

The DataShare module allows an application to manage its own data and share data with other applications on the same device.

NOTE

• 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.

• The APIs provided by this module are system APIs.

• The APIs of this module can be used only in the stage model.

Modules to Import

import dataShare from '@ohos.data.dataShare'

URI Naming Rule

The URIs are in the following format:

Scheme://authority/path

• Scheme: scheme name, which has a fixed value of datashare for the DataShare module.
• authority: [userinfo@]host[:port]
  • userinfo: login information, which can be left unspecified.
  • host: server address. It is the target device ID for cross-device access and empty for local device access.
  • port: port number of the server, which can be left unspecified.
• path: DataShare identifier and the resource path. The DataShare identifier is mandatory, and the resource path is optional.

Example:

• URI without the resource path:
  datashare:///com.samples.datasharetest.DataShare

• URI with the resource path:
  datashare:///com.samples.datasharetest.DataShare/DB00/TBL00

com.samples.datasharetest.DataShare is the data share identifier, and DB00/TBL00 is the resource path.

dataShare.createDataShareHelper

createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void

Creates a DataShareHelper instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Error codes

For details about the error codes, see DataShare Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
try {
    dataShare.createDataShareHelper(this.context, uri, (err, data) => {
        if (err != undefined) {
            console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    });
} catch (err) {
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
};

dataShare.createDataShareHelper

createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper>

Creates a DataShareHelper instance. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Error codes

For details about the error codes, see DataShare Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
try {
    dataShare.createDataShareHelper(this.context, uri).then((data) => {
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    }). catch((err) => {
        console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
};

DataShareHelper

Provides a DataShareHelper instance to access or manage data on the server. Before calling an API provided by DataShareHelper, you must create a DataShareHelper instance using createDataShareHelper.

on('dataChange')

on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void

Subscribes to changes of the specified data. After an observer is registered, the subscriber will receive a notification when the change notification is triggered (the notifyChange() method is called). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
function onCallback() {
    console.info("**** Observer on callback ****");
}
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.on("dataChange", uri, onCallback);

off('dataChange')

off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void

Unsubscribes from the changes of the specified data. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
function offCallback() {
    console.info("**** Observer off callback ****");
}
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.off("dataChange", uri, offCallback);

insert

insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void

Inserts a single data record into the database. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
const valueBucket = {
    "name": "rose",
    "age": 22,
    "salary": 200.5,
}
try {
    dataShareHelper.insert(uri, valueBucket, (err, data) => {
        if (err != undefined) {
            console.error(`insert error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("insert succeed, data : " + data);
    });
} catch (err) {
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
};

insert

insert(uri: string, value: ValuesBucket): Promise<number>

Inserts a single data record into the database. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
const valueBucket = {
    "name": "rose1",
    "age": 221,
    "salary": 20.5,
}
try {
    dataShareHelper.insert(uri, valueBucket).then((data) => {
        console.log("insert succeed, data : " + data);
    }). catch((err) => {
        console.error(`insert error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
};

delete

delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void

Deletes one or more data records from the database. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.delete(uri, da, (err, data) => {
        if (err != undefined) {
            console.error(`delete error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.info("delete succeed, data : " + data);
    });
} catch (err) {
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
};

delete

delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number>

Deletes one or more data records from the database. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.delete(uri, da).then((data) =>  {
        console.log("delete succeed, data : " + data);
    }). catch((err) => {
        console.error(`delete error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
};

query

query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void

Queries data in the database. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.query(uri, da, columns, (err, data) => {
        if (err != undefined) {
            console.error(`query error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.log("query succeed, rowCount : " + data.rowCount);
    });
} catch (err) {
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
};

query

query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet>

Queries data in the database. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
try {
    dataShareHelper.query(uri, da, columns).then((data) =>  {
        console.log("query succeed, rowCount : " + data.rowCount);
    }). catch((err) => {
        console.error(`query error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
};

update

update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void

Updates data in the database. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
try {
    dataShareHelper.update(uri, da, va, (err, data) => {
        if (err != undefined) {
            console.error(`update error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.log("update succeed, data : " + data);
    });
} catch (err) {
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
};

update

update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number>

Updates data in the database. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
import dataSharePredicates from '@ohos.data.dataSharePredicates'

let uri = ("datashare:///com.samples.datasharetest.DataShare");
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
try {
    dataShareHelper.update(uri, da, va).then((data) =>  {
        console.log("update succeed, data : " + data);
    }). catch((err) => {
        console.error(`update error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
};

batchInsert

batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void

Batch inserts data into the database. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
try {
    dataShareHelper.batchInsert(uri, vbs, (err, data) => {
        if (err != undefined) {
            console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
            return;
        }
        console.log("batchInsert succeed, data : " + data);
    });
} catch (err) {
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
};

batchInsert

batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number>

Batch inserts data into the database. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
try {
    dataShareHelper.batchInsert(uri, vbs).then((data) =>  {
        console.log("batchInsert succeed, data : " + data);
    }). catch((err) => {
        console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
    });
} catch (err) {
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
};

normalizeUri

normalizeUri(uri: string, callback: AsyncCallback<string>): void

Normalizes a DataShare URI. The DataShare URI can be used only by the local device, but the normalized URI can be used across devices. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.normalizeUri(uri, (err, data) => {
    if (err != undefined) {
        console.log("normalizeUri failed, error message : " + err);
    }else{
        console.log("normalizeUri = " + data);
    }
});

normalizeUri

normalizeUri(uri: string): Promise<string>

Normalizes a DataShare URI. The DataShare URI can be used only by the local device, but the normalized URI can be used across devices. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.normalizeUri(uri).then((data) => {
    console.log("normalizeUri = " + data);
}).catch((err) => {
    console.log("normalizeUri failed, error message : " + err);
});

denormalizeUri

denormalizeUri(uri: string, callback: AsyncCallback<string>): void

Denormalizes a URI. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.denormalizeUri(uri, (err, data) => {
    if (err != undefined) {
        console.log("denormalizeUri failed, error message : " + err);
    }else{
        console.log("denormalizeUri = " + data);
    }
});

denormalizeUri

denormalizeUri(uri: string): Promise<string>

Denormalizes a URI. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.denormalizeUri(uri).then((data) => {
    console.log("denormalizeUri = " + data);
}).catch((err) => {
    console.log("denormalizeUri failed, error message : " + err);
});

notifyChange

notifyChange(uri: string, callback: AsyncCallback<void>): void

Notifies the registered observer of data changes. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.notifyChange(uri, () => {
    console.log("***** notifyChange *****");
});

notifyChange

notifyChange(uri: string): Promise<void>

Notifies the registered observer of data changes. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataShare.Consumer

Parameters

Return value

Example

import UIAbility from '@ohos.app.ability.UIAbility'
let uri = ("datashare:///com.samples.datasharetest.DataShare");
dataShareHelper.notifyChange(uri);