@ohos.enterprise.deviceSettings (Device Settings) (System API)

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 of this module can be called only by a device administrator application that is enabled.

This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.enterprise.deviceSettings.

Modules to Import

import { deviceSettings } from '@kit.MDMKit';

deviceSettings.setScreenOffTime¹¹⁺

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

Sets the device screen-off time.

Required permissions: ohos.permission.ENTERPRISE_SET_SCREENOFF_TIME

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
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 and Universal Error Codes.

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
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. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_GET_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
callback	AsyncCallback<number>	Yes	Callback invoked to return the result. If the operation is successful, err is null and data is the screen-off time in ms. If the operation fails, err is an error object.

Error codes

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

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
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. This API uses an asynchronous promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_GET_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.

Return value

Type	Description
Promise<number>	Promise used to return the screen-off time, in ms.

Error codes

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

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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. This API uses a callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
certificate	CertBlob	Yes	Information about the certificate to install. The certificate file must be stored in a path that can be accessed by the application, such as the application sandbox path.
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 and Universal Error Codes.

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
9201001	Failed to manage the certificate.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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. This API uses a promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
certificate	CertBlob	Yes	Information about the certificate to install. The certificate file must be stored in a path that can be accessed by the application, such as the application sandbox path.

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 and Universal Error Codes.

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
9201001	Failed to manage the certificate.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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

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. This API uses a callback to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
certUri	string	Yes	Certificate URI, which is set and returned by the installUserCertificate API for installing a user certificate.
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 and Universal Error Codes.

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
9201001	Failed to manage the certificate.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
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. This API uses a promise to return the result.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
certUri	string	Yes	Certificate URI, which is set and returned by the installUserCertificate API for installing a user certificate.

Return value

Type	Description
Promise<void>	Promise that returns no value. An error object is thrown when a user certificate fails to be uninstalled.

Error codes

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

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
9201001	Failed to manage the certificate.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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 power policy.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
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 and Universal Error Codes.

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
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 (err) {
  console.error(`Failed to set power policy. Code: ${err.code}, message: ${err.message}`);
}

deviceSettings.getPowerPolicy¹¹⁺

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

Obtains the power policy.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_SETTINGS

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Parameters

Name	Type	Mandatory	Description
admin	Want	Yes	EnterpriseAdminExtensionAbility.
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.

Error codes

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

ID	Error Message
9200001	The application is not an administrator application of the device.
9200002	The administrator application does not have permission to manage the device.
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
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 (err) {
  console.error(`Failed to get power policy. Code: ${err.code}, message: ${err.message}`);
}

PowerPolicy¹¹⁺

Represents the power policy.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

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

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

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 鸿蒙MDM Kit

harmony 鸿蒙Enterprise Device Management Error Codes

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

harmony 鸿蒙@ohos.enterprise.accountManager (Account Management) (System API)

harmony 鸿蒙@ohos.enterprise.accountManager (Account Management)

harmony 鸿蒙@ohos.enterprise.adminManager (Enterprise Device Management) (System API)

harmony 鸿蒙@ohos.enterprise.adminManager (Enterprise Device Management)

harmony 鸿蒙@ohos.enterprise.applicationManager (Application Management (System API)

harmony 鸿蒙@ohos.enterprise.applicationManager (Application Management)

harmony 鸿蒙@ohos.enterprise.bluetoothManager (Bluetooth Management) (System API)