@ohos.data.distributedDataObject (Distributed Data Object)

The distributedDataObject module provides basic data object management, including creating, querying, deleting, modifying, and subscribing to data objects, and distributed data object collaboration for the same application among multiple devices.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import distributedObject from '@ohos.data.distributedDataObject';

distributedObject.create⁹⁺

create(context: Context, source: object): DataObject

Creates a distributed data object.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Return value

Example

FA model:

// Import the module.
import distributedObject from '@ohos.data.distributedDataObject';
import featureAbility from '@ohos.ability.featureAbility';
import { BusinessError } from '@ohos.base';
// Obtain the context.
let context = featureAbility.getContext();
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DataObject = distributedObject.create(context, source);

Stage model:

// Import the module.
import distributedObject from '@ohos.data.distributedDataObject';
import UIAbility from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let g_object: distributedObject.DataObject|null = null;
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        let source: SourceObject = new SourceObject("amy", 18, false);
        let g_object: distributedObject.DataObject = distributedObject.create(this.context, source);
    }
}

distributedObject.genSessionId

genSessionId(): string

Creates a random session ID.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Return value

Example

import distributedObject from '@ohos.data.distributedDataObject';
let sessionId: string = distributedObject.genSessionId();

SaveSuccessResponse⁹⁺

Called when the Save() API is successfully called.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

RevokeSaveSuccessResponse⁹⁺

Called when the revokeSave() API is successfully called.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

DataObject

Provides APIs for managing a distributed data object. Before using any API of this class, use create() to create a DataObject object.

setSessionId⁹⁺

setSessionId(sessionId: string, callback: AsyncCallback<void>): void

Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Error codes

For details about the error codes, see Distributed Data Object Error Codes.

Example

// Add g_object to the distributed network.
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
    console.info("join session");
});

setSessionId⁹⁺

setSessionId(callback: AsyncCallback<void>): void

Exits all joined sessions.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Error codes

For details about the error codes, see Distributed Data Object Error Codes.

Example

// Add g_object to the distributed network.
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
    console.info("join session");
});
// Exit the distributed network.
g_object.setSessionId(() => {
    console.info("leave all session.");
});

setSessionId⁹⁺

setSessionId(sessionId?: string): Promise<void>

Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Return value

Error codes

For details about the error codes, see Distributed Data Object Error Codes.

Example

// Add g_object to the distributed network.
g_object.setSessionId(distributedObject.genSessionId()).then (()=>{
    console.info("join session.");
    }).catch((error: BusinessError)=>{
        console.info("error:" + error.code + error.message);
});
// Exit the distributed network.
g_object.setSessionId().then (()=>{
    console.info("leave all session.");
    }).catch((error: BusinessError)=>{
        console.info("error:" + error.code + error.message);
});

on(‘change’)⁹⁺

on(type: ‘change’, callback: (sessionId: string, fields: Array<string>) => void ): void

Subscribes to data changes of this distributed data object.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

g_object.on("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});

off(‘change’)⁹⁺

off(type: ‘change’, callback?: (sessionId: string, fields: Array<string>) => void ): void

Unsubscribes from the data changes of this distributed data object.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

// Unregister the specified data change callback.
g_object.off("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});
// Unregister all data change callbacks.
g_object.off("change");

on(‘status’)⁹⁺

on(type: ‘status’, callback: (sessionId: string, networkId: string, status: ‘online’ |‘offline’ ) => void): void

Subscribes to status changes of this distributed data object.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

g_object.on("status", (sessionId: string, networkId: string, status: 'online'|'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});

off(‘status’)⁹⁺

off(type: ‘status’, callback?:(sessionId: string, networkId: string, status: ‘online’ |‘offline’) => void): void

Unsubscribes from the status change of this distributed data object.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

// Unregister the specified status change callback.
g_object.off("status", (sessionId: string, networkId: string, status: 'online'|'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});
// Unregister all status change callbacks.
g_object.off("status");

save⁹⁺

save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void

Saves a distributed data object. This API uses an asynchronous callback to return the result.

If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored.

The saved data will be released in the following cases:

• The data is stored for more than 24 hours.
• The application has been uninstalled.
• Data is successfully restored.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

g_object.setSessionId("123456");
g_object.save("local", (err: BusinessError, result:distributedObject.SaveSuccessResponse) => {
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
    console.info("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});

save⁹⁺

save(deviceId: string): Promise<SaveSuccessResponse>

Saves a distributed data object. This API uses a promise to return the result.

If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored.

The saved data will be released in the following cases:

• The data is stored for more than 24 hours.
• The application has been uninstalled.
• Data is successfully restored.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Return value

Example

g_object.setSessionId("123456");
g_object.save("local").then((result: distributedObject.SaveSuccessResponse) => {
    console.info("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}).catch((err: BusinessError) => {
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
});

revokeSave⁹⁺

revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void

Revokes the data of this distributed data object saved. This API uses an asynchronous callback to return the result.

If the object is saved on the local device, the data saved on all trusted devices will be deleted. If the object is stored on another device, the data on the local device will be deleted.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

g_object.setSessionId("123456");
// Save data for persistence. 
g_object.save("local", (err: BusinessError, result: distributedObject.SaveSuccessResponse) => {
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
    console.info("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});
// Delete the persistence data.
g_object.revokeSave((err: BusinessError, result: distributedObject.RevokeSaveSuccessResponse) => {
    if (err) {
      console.info("revokeSave failed, error code = " + err.code);
      console.info("revokeSave failed, error message: " + err.message);
      return;
    }
    console.info("revokeSave callback");
    console.info("revokeSave sessionId " + result.sessionId);
});

revokeSave⁹⁺

revokeSave(): Promise<RevokeSaveSuccessResponse>

Revokes the data of this distributed data object saved. This API uses a promise to return the result.

If the object is saved on the local device, the data saved on all trusted devices will be deleted. If the object is stored on another device, the data on the local device will be deleted.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Return value

Example

g_object.setSessionId("123456");
// Save data for persistence. 
g_object.save("local").then((result: distributedObject.SaveSuccessResponse) => {
    console.info("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}).catch((err: BusinessError) => {
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
});
// Delete the persistence data.
g_object.revokeSave().then((result: distributedObject.RevokeSaveSuccessResponse) => {
    console.info("revokeSave callback");
    console.info("sessionId" + result.sessionId);
}).catch((err: BusinessError)=> {
    console.info("revokeSave failed, error code = " + err.code);
    console.info("revokeSave failed, error message = " + err.message);
});

distributedObject.createDistributedObject^(deprecated)

createDistributedObject(source: object): DistributedObject

Creates a distributed data object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use distributedObject.create.

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Return value

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);

DistributedObject^(deprecated)

Provides APIs for managing a distributed data object. Before using any API of this class, use createDistributedObject() to create a DistributedObject object.

setSessionId^(deprecated)

setSessionId(sessionId?: string): boolean

Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use setSessionId.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Return value

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// Add g_object to the distributed network.
g_object.setSessionId(distributedObject.genSessionId());
// Remove g_object from the distributed network.
g_object.setSessionId("");

on(‘change’)^(deprecated)

on(type: ‘change’, callback: (sessionId: string, fields: Array<string>) => void): void

Subscribes to data changes of this distributed data object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use on(‘change’).

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
g_object.on("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});

off(‘change’)^(deprecated)

off(type: ‘change’, callback?: (sessionId: string, fields: Array<string>) => void): void

Unsubscribes from the data changes of this distributed data object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use off(‘change’).

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// Unregister the specified data change callback.
g_object.off("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});
// Unregister all data change callbacks.
g_object.off("change");

on(‘status’)^(deprecated)

on(type: ‘status’, callback: (sessionId: string, networkId: string, status: ‘online’|‘offline’ ) => void): void

Subscribes to status changes of this distributed data object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use on(‘status’).

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);

g_object.on("status", (sessionId: string, networkId: string, status: 'online'|'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});

off(‘status’)^(deprecated)

off(type: ‘status’, callback?: (sessionId: string, networkId: string, status: ‘online’|‘offline’ ) => void): void

Unsubscribes from the status change of this distributed data object.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use off(‘status’).

System capability: SystemCapability.DistributedDataManager.DataObject.DistributedObject

Parameters

Example

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("amy", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// Unregister the specified status change callback.
g_object.off("status", (sessionId: string, networkId: string, status: 'online'|'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});
// Unregister all status change callbacks.
g_object.off("status");

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)