@ohos.enterprise.deviceSettings (Device Settings Management)

The deviceSettings module provides APIs for setting enterprise devices, including obtaining the screen-off time of a device.

NOTE

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

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

• The APIs provided by this module can be called only by a device administrator application that is enabled.

Modules to Import

import deviceSettings from '@ohos.enterprise.deviceSettings';

deviceSettings.setScreenOffTime¹¹⁺

setScreenOffTime(admin: Want, time: number): void

Sets the device screen-off time through the specified device administrator application. This API returns the result synchronously. If the operation is successful, null is returned. If the operation fails, an exception is thrown.

Required permissions: ohos.permission.ENTERPRISE_SET_SCREENOFF_TIME

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
time	number	Yes	Screen-off time to set, in milliseconds. You are advised to set this parameter to the device's optional screen-off time.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.

Example

import Want from '@ohos.app.ability.Want';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
try {
  deviceSettings.setScreenOffTime(wantTemp, 30000);
  console.info(`Succeeded in setting screen off time`);
} catch(err) {
  console.error(`Failed to set screen off time. Code: ${err.code}, message: ${err.message}`);
}

deviceSettings.getScreenOffTime

getScreenOffTime(admin: Want, callback: AsyncCallback<number>): void

Obtains the device screen-off time through the specified device administrator application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_GET_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
callback	AsyncCallback<number>	Yes	Callback invoked to return the result. If the operation is successful, err is null and data is the device screen-off time obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.

Example

import Want from '@ohos.app.ability.Want';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};

deviceSettings.getScreenOffTime(wantTemp, (err, result) => {
  if (err) {
    console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in getting screen off time, result : ${result}`);
});

deviceSettings.getScreenOffTime

getScreenOffTime(admin: Want): Promise<number>

Obtains the device screen-off time through the specified device administrator application. This API uses a promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_GET_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.

Return value

Type	Description
Promise<number>	Promise used to return the device screen-off time.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.

Example

import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};

deviceSettings.getScreenOffTime(wantTemp).then((result) => {
  console.info(`Succeeded in getting screen off time, result : ${result}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`);
});

deviceSettings.installUserCertificate

installUserCertificate(admin: Want, certificate: CertBlob, callback: AsyncCallback<string>): void

Installs a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
certificate	CertBlob	Yes	Information about the certificate to install.
callback	AsyncCallback<string>	Yes	Callback invoked to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.
9201001	manage certificate failed

Example

import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
let certFileArray: Uint8Array = new Uint8Array();
// The variable context needs to be initialized in MainAbility's onCreate callback function
// test.cer needs to be placed in the rawfile directory
getContext().resourceManager.getRawFileContent("test.cer").then((value) => {
  certFileArray = value;
  deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }, (err, result) => {
    if (err) {
      console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`);
    }
  });
}).catch((error: BusinessError) => {
  console.error(`Failed to get row file content. message: ${error.message}`);
  return
});

deviceSettings.installUserCertificate

installUserCertificate(admin: Want, certificate: CertBlob): Promise<string>

Installs a user certificate through the specified device administrator application. This API uses a promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
certificate	CertBlob	Yes	Information about the certificate to install.

Return value

Type	Description
Promise<string>	Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.
9201001	manage certificate failed

Example

import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
let certFileArray: Uint8Array = new Uint8Array();
// The variable context needs to be initialized in MainAbility's onCreate callback function
// test.cer needs to be placed in the rawfile directory
getContext().resourceManager.getRawFileContent("test.cer").then((value) => {
  certFileArray = value
  deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" })
    .then((result) => {
      console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`);
    }).catch((err: BusinessError) => {
    console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`);
  })
}).catch((error: BusinessError) => {
  console.error(`Failed to get row file content. message: ${error.message}`);
  return
});

CertBlob

Represents the certificate information.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Name	Type	Mandatory	Description
inData	Uint8Array	Yes	Binary content of the certificate.
alias	string	Yes	Certificate alias.

deviceSettings.uninstallUserCertificate

uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void

Uninstalls a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
certUri	string	Yes	Certificate URI, which is returned by installUserCertificate().
callback	AsyncCallback<void>	Yes	Callback invoked to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.
9201001	manage certificate failed

Example

import Want from '@ohos.app.ability.Want';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
let aliasStr = "certName"
deviceSettings.uninstallUserCertificate(wantTemp, aliasStr, (err) => {
  if (err) {
    console.error(`Failed to uninstall user certificate. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in uninstalling user certificate`);
});

deviceSettings.uninstallUserCertificate

uninstallUserCertificate(admin: Want, certUri: string): Promise<void>

Uninstalls a user certificate through the specified device administrator application. This API uses a promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
certUri	string	Yes	Certificate URI, which is returned by installUserCertificate().

Return value

Type	Description
Promise<void>	Promise that returns no value. An error object will be thrown if the operation fails.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.
9201001	manage certificate failed

Example

import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
let aliasStr = "certName"
deviceSettings.uninstallUserCertificate(wantTemp, aliasStr).then(() => {
  console.info(`Succeeded in uninstalling user certificate`);
}).catch((err: BusinessError) => {
  console.error(`Failed to uninstall user certificate. Code is ${err.code}, message is ${err.message}`);
});

deviceSettings.setPowerPolicy¹¹⁺

setPowerPolicy(admin: Want, powerScene: PowerScene, powerPolicy: PowerPolicy): void

Sets the device power policy through the specified device administrator application. This API returns the result synchronously. If the operation is successful, null is returned. If the operation fails, an exception is thrown.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
powerScene	PowerScene	Yes	Scenario to which the power policy applies. Currently, only the timeout scenario is supported.
powerPolicy	PowerPolicy	Yes	Power policy to set.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.

Example

import Want from '@ohos.app.ability.Want';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
try {
  let delayTime = 0;
  let powerScene: deviceSettings.PowerScene = deviceSettings.PowerScene.TIME_OUT;
  let powerPolicyAction: deviceSettings.PowerPolicyAction = deviceSettings.PowerPolicyAction.AUTO_SUSPEND;
  let powerPolicy: deviceSettings.PowerPolicy = {powerPolicyAction, delayTime};
  deviceSettings.setPowerPolicy(wantTemp, powerScene, powerPolicy);
  console.info(`Succeeded in setting power polilcy`);
} catch (error) {
  console.error(`Failed to set power policy. Code: ${err.code}, message: ${err.message}`);
}

deviceSettings.getPowerPolicy¹¹⁺

getPowerPolicy(admin: Want, powerScene: PowerScene): PowerPolicy

Obtains the device power policy through the specified device administrator application. This API returns the result synchronously. If the operation is successful, the power policy obtained is returned. If the operation fails, an exception is thrown.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	Device administrator application.
powerScene	PowerScene	Yes	Scenario to which the power policy applies. Currently, only the timeout scenario is supported.

Return value

Type	Description	Description
PowerPolicy	PowerPolicy	Power policy obtained.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes.

ID	Error Message
9200001	the application is not an administrator of the device.
9200002	the administrator application does not have permission to manage the device.

Example

import Want from '@ohos.app.ability.Want';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
try {
  let powerScene: deviceSettings.PowerScene = deviceSettings.PowerScene.TIME_OUT;
  let powerPolicy: deviceSettings.PowerPolicy = deviceSettings.getPowerPolicy(wantTemp, powerScene);
  console.info(`Succeeded in getting power polilcy ${JSON.stringify(powerPolicy)}`);
} catch (error) {
  console.error(`Failed to get power policy. Code: ${err.code}, message: ${err.message}`);
}

PowerPolicy¹¹⁺

Represents the power policy.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Name	Type	Mandatory	Description
powerPolicyAction	PowerPolicyAction	Yes	Action to apply the power policy.
delayTime	number	Yes	Delay time allowed.

PowerScene¹¹⁺

Defines the scenario to which the power policy applies.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Name	Value	Description
TIME_OUT	0	Timeout scenario.

PowerPolicyAction¹¹⁺

Enumerates the actions that can be performed to apply the power policy.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

System API: This is a system API.

Name	Value	Description
NONE	0	No action is performed.
AUTO_SUSPEND	1	Automatically enter the sleep mode.
FORCE_SUSPEND	2	Forcibly enter the sleep mode.
HIBERNATE	3	Enter the hibernation state. Currently, the power subsystem does not support this action.
SHUTDOWN	4	Shut down the system.

你可能感兴趣的鸿蒙文章

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)