Summary: Constants | Methods | Inherited Methods | [Expand All]
Since: API level 2
public class

DateTimePolicy

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.datetime.DateTimePolicy

Class Overview

This class provides APIs to control the device date and time settings. API functions include disabling and enabling settings, making configurations, and querying the current date and time settings.

Since
API level 2
MDM 2.0

Summary

Constants
String ACTION_EVENT_NTP_SERVER_UNREACHABLE Intent event to warn administrator when maximum attempts to connect to NTP server have been performed and is still unreachable.
Public Methods
boolean getAutomaticTime()
Deprecated in API level 35
String getDateFormat()
Deprecated in API level 35
Date getDateTime()
Deprecated in API level 35
boolean getDaylightSavingTime()
Deprecated in API level 35
NtpInfo getNtpInfo()
Deprecated in API level 35
String getTimeFormat()
Deprecated in API level 35
String getTimeZone()
Deprecated in API level 35
boolean isDateTimeChangeEnabled()
Deprecated in API level 35
boolean setAutomaticTime(boolean enabled)
Deprecated in API level 35
boolean setDateTime(int day, int month, int year, int hour, int minute, int second)
Deprecated in API level 35
boolean setDateTimeChangeEnabled(boolean enable)
Deprecated in API level 35
boolean setNtpInfo(NtpInfo ntpInfo)
Deprecated in API level 35
boolean setTimeFormat(String format)
Deprecated in API level 35
boolean setTimeZone(String timeZoneID)
Deprecated in API level 35
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_EVENT_NTP_SERVER_UNREACHABLE

Since: API level 17

Intent event to warn administrator when maximum attempts to connect to NTP server have been performed and is still unreachable.

Since
API level 17
MDM 5.5
Constant Value: "com.samsung.android.knox.intent.action.EVENT_NTP_SERVER_UNREACHABLE"

Public Methods

public boolean getAutomaticTime ()

Since: API level 2

Deprecated in API level 35

API to get the automatic time state of the device.

Returns
  • true if NITZ time is enabled, false if NITZ time is not used.
Usage
An administrator can use this API to determine whether the device obtains its time automatically via NITZ or by user-defined time. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 boolean automaticTime = mDateTimePolicy.getAutomaticTime();
 if (automaticTime == true) {
     Log.d(TAG, "Automatic time enabled");
 } else {
     Log.d(TAG, "Automatic time disabled");
 }

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope
See Also

public String getDateFormat ()

Since: API level 2

Deprecated in API level 35

API to get the device date format.

Returns
  • The device current date format when successful, else null.
Usage
An administrator can use this API to get the current device date format as DD/MM/YYYY, MM/DD/YYYY, or YYYY/MM/DD. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();
 String dateFormat = mDateTimePolicy.getDateFormat();
 // Sample Output
 // DD/MM/YYYY
For Container:
 // When you create container successfully, containerID will be returned via intent.
 // Use this containerID in below API.
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
 DateTimePolicy mDateTimePolicy = kcm.getDateTimePolicy();
 String dateFormat = mDateTimePolicy.getDateFormat();
 // Sample Output
 // DD/MM/YYYY

Since
API level 2
MDM 2.0
Multiuser Environment
User Scope

public Date getDateTime ()

Since: API level 2

Deprecated in API level 35

API to get the device date and time.

Returns
  • The device current date and time on success, else null.
Usage
An administrator can use this API to get the current date and time set on the device. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 Date date = mDateTimePolicy.getDateTime();
 if (date != null) {
     // Get device time has succeeded!
 } else {
     // Get device time has failed.
 }
 // Sample Output
 // Wed Dec 07 17:42:40 CST 2011

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope
See Also

public boolean getDaylightSavingTime ()

Since: API level 2

Deprecated in API level 35

API to get the state of daylight saving time.

Returns
  • true if in daylight saving time, false if not in daylight saving time.
Usage
An administrator can use this API to get the current daylight saving time state of the device, if it is currently in a time zone with daylight saving time. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 boolean daylightSavingTime = mDateTimePolicy.getDaylightSavingTime();

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope

public NtpInfo getNtpInfo ()

Since: API level 17

Deprecated in API level 35

API to get NTP (Network Time Protocol) server info set in the device.

Returns
  • NTP server info object or null if operation failed.
Usage
An administrator can use this API to get latest NTP server set. If no NTP info has been provided an empty object (server null and other parameters set to NOT_SET_INT or NOT_SET_LONG) will be returned. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 NtpInfo ntpInfo = mDateTimePolicy.getNtpInfo();
 String server = ntpInfo.getServer();
 // print server
 long timeout = ntpInfo.getTimeout();
 // print timeout
 long polInterval = ntpInfo.getPollingInterval();
 // print polInterval
 long polIntervalShorter = ntpInfo.getPollingIntervalShorter();
 // print polIntervalShorter
 int maxAttempts = ntpInfo.getMaxAttempts();
 // print maxAttempts
 int timeErrorThreshold = ntpInfo.getTimeErrorThreshold(); // deprecated in API level 33
 // print timeErrorThreshold

Since
API level 17
MDM 5.5
Multiuser Environment
Global Scope
See Also

public String getTimeFormat ()

Since: API level 2

Deprecated in API level 35

API to get the device time format as 12h or 24h.

Returns
  • The device current time format as "12" or "24" when successful, else null.
Usage
An administrator can use this API to get the current device time format (12h or 24h). 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();
 String timeFormat = mDateTimePolicy.getTimeFormat();
 // Sample Output
 // 24
For Container:
 // When you create container successfully, containerID will be returned via intent.
 // Use this containerID in below API.
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
 DateTimePolicy mDateTimePolicy = kcm.getDateTimePolicy();
 String timeFormat = mDateTimePolicy.getTimeFormat();
 // Sample Output
 // 24

Since
API level 2
MDM 2.0
Multiuser Environment
User Scope
See Also

public String getTimeZone ()

Since: API level 2

Deprecated in API level 35

API to get the device time zone as a valid Id.

Returns
  • The device current timeZone on success, else null.
Usage
An administrator can use this API to get the current time zone set on the device (e.g., America/Denver). The list of possible values can be seen on device in DateTimeSettings in the Settings application. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 String timeZone = mDateTimePolicy.getTimeZone();
 // Sample Output
 // America/Denver

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope
See Also

public boolean isDateTimeChangeEnabled ()

Since: API level 5

Deprecated in API level 35

API to check whether date and time change is enabled.

Returns
  • true if date and time change is enabled, else false
Usage
An administrator can use this API to check whether the date and time change is enabled. The default value will be true.
Since
API level 5
MDM 3.0
Multiuser Environment
Global Scope
See Also

public boolean setAutomaticTime (boolean enabled)

Since: API level 2

Deprecated in API level 35

API to set the time automatically by enabling the Network Identity and Time Zone (NITZ) option.

Parameters
enabled true to enable NITZ time, false to use user-defined time.
Returns
  • true if automatic time setting was set successfully, else false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to have the device obtain the time automatically by enabling NITZ. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 boolean automaticTime = true;
 try {
     mDateTimePolicy.setAutomaticTime(automaticTime);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope
See Also

public boolean setDateTime (int day, int month, int year, int hour, int minute, int second)

Since: API level 2

Deprecated in API level 35

API to set the device date and time.

Parameters
day Day of the month to set
month Month to set
year Year to set
hour Hour of the day to set
minute Minute to set
second Second to set
Returns
  • true if date and time are set successfully, else false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to provide date parameters that set the device date/time. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 try {
     mDateTimePolicy.setDateTime(Calendar.getInstance().get(Calendar.DAY_OF_MONTH),
             Calendar.getInstance().get(Calendar.MONTH),
             Calendar.getInstance().get(Calendar.YEAR),
             Calendar.getInstance().get(Calendar.HOUR),
             Calendar.getInstance().get(Calendar.MINUTE), 0);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Dependency
setAutomaticTime must be disabled
Multiuser Environment
Global Scope
See Also

public boolean setDateTimeChangeEnabled (boolean enable)

Since: API level 5

Deprecated in API level 35

API to enable or disable date and time change.

Parameters
enable true to enable, false to disable
Returns
  • true if successful, false if failed
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to prevent the user from changing the date and time setting. 
 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy dateTimePolicy = edm.getDateTimePolicy();
 try {
     boolean dateTimeChangeAllowed = true;
     // disable visible pattern
     dateTimePolicy.setDateTimeChangeEnabled(dateTimeChangeAllowed);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
Permission
The use of this API requires the caller to add the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission with a protection level of signature.
Since
API level 5
MDM 3.0
Multiuser Environment
Global Scope
See Also

public boolean setNtpInfo (NtpInfo ntpInfo)

Since: API level 17

Deprecated in API level 35

API to set NTP server info.

Parameters
ntpInfo Object containing the parameters to setup NTP server and other related settings.
Returns
  • true if successful, false if failed
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to set NTP (Network Time Protocol) server info to update device's time. When NTP server is set it will be preferred over NITZ (Network Identity and Time Zone) time and manual time. To prevent user from changing the device time and overriding the NTP time, administrator shall also use the API setDateTimeChangeEnabled(boolean). To reset NTP info just pass a NtpInfo object with server set to null, after that system will use its default defined values. The last value set is used and the previous will be discarded, so if the administrator who set the parameters for the last time is removed, the configuration will be reverted to system's default. The NtpInfo object should not be null. Since the NtpInfo object is initialized with the system's default parameters, if there is not intention to modify a specific field, administrator can either leave it as it is or explicitly set NOT_SET_INT or NOT_SET_LONG to that field. 
 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy dateTimePolicy = edm.getDateTimePolicy();
 try {
     boolean ntpInfoSet = true;
     NtpInfo ntpInfo = new NtpInfo(this.getApplicationContext());
     ntpInfo.setServer("us.pool.ntp.org");
     ntpInfo.setTimeout(10000); // 10 seconds
     ntpInfo.setMaxAttempts(5);
     ntpInfo.setPollingInterval(43200000); // 12 hours
     ntpInfo.setPollingIntervalShorter(30000); // 30 seconds
     ntpInfo.setTimeErrorThreshold(1000); // 1 second (deprecated in API level 33)
     ntpInfoSet = dateTimePolicy.setNtpInfo(ntpInfo);
     if (ntpInfoSet) {
         // operation was successfull
     } else {
         // operation failed
     }
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }

NOTE: NTP has security limitations that are not overcome by this API. So, if a secure environment is needed, please consider connecting your device through a secure tunnel.
Permission
The use of this API requires the caller to add the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission with a protection level of signature.
Since
API level 17
MDM 5.5
Multiuser Environment
Global Scope
See Also

public boolean setTimeFormat (String format)

Since: API level 2

Deprecated in API level 35

API to set the device time format as 12h or 24h.

Parameters
format The time format as "12" or "24".
Returns
  • true if time format was set successfully, else false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to set the device time format to 12 hours (12h) or 24 hours (24h). 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();
 String timeFormat = "12";
 try {
     mDateTimePolicy.setTimeFormat(timeFormat);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
For Container:

NOTE: Since MDM 5.4.1, only Android users (Owner/Guest user) administrator can call this API. For container, API will return false. 

 // When you create container successfully, containerID will be returned via intent.
 // Use this containerID in below API.
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
 DateTimePolicy mDateTimePolicy = kcm.getDateTimePolicy();
 String timeFormat = "12";
 try {
     mDateTimePolicy.setTimeFormat(timeFormat);
 } catch(SecurityException e) {
   Log.w(TAG,"SecurityException: "+ e);
 }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Multiuser Environment
User Scope
See Also

public boolean setTimeZone (String timeZoneID)

Since: API level 2

Deprecated in API level 35

API to set the device time zone by providing a time zone Id.

Parameters
timeZoneID The time zone Id variable (e.g., America/Detroit).
Returns
  • true if time zone is set successfully, else false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to provide a time zone Id that sets the device time zone parameter. The list of possible values can be seen on device DateTimeSettings in the Settings application. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 DateTimePolicy mDateTimePolicy = edm.getDateTimePolicy();

 String timeZone = "America/Sao_Paulo";
 try {
     mDateTimePolicy.setTimeZone(timeZone);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DATE_TIME" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Dependency
setAutomaticTime must be disabled
Multiuser Environment
Global Scope
See Also