Summary: Nested Classes | Constants | Methods | Inherited Methods | [Expand All]
Since: API level 6
public class

LockscreenOverlay

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.lockscreen.LockscreenOverlay

Class Overview

This class provides APIs to customize the device lock screen.
The lock screen can be customized in the following ways

    1. By configuring a lock screen wallpaper. (setWallpaper(String))
    2. By configuring a default style. The content of this style can be configured but the style itself cannot be configured. ( configure(String, String, String, String))
    3. By setting multiple images that appear as an overlay on top of the lock screen. (configure(LSOImage[]))
    4. By setting an enterprise emergency phone number that appears on top of the lock screen and, when clicked, allows the user to make a call to the configured enterprise emergency phone number without unlocking the device. ( setEmergencyPhoneInfo(LSOEmergencyPhoneInfo))
The customized element appears on the top of every type of device lock screen and disappears as soon as the user touches the screen.
When the user touches the enterprise emergency call button, a voice call is established with the administrator provided enterprise emergency number.

Since
API level 6
MDM 4.0

Summary

Nested Classes
class LockscreenOverlay.LSOEmergencyPhoneInfo This class defines the Lock Screen Overlay Emergency Phone information and is given as an input parameter when configuring the lock screen enterprise emergency phone number. 
class LockscreenOverlay.LSOImage This class defines the Lock Screen Overlay image and is given as an input parameter when configuring Lockscreen Overlay. 
Constants
float DEFAULT_ALPHA_LEVEL Default Alpha Level.
int ERROR_BAD_STATE Indicates that the requested operation cannot be completed in the current state.
int ERROR_FAILED Indicates that requested operation failed due to some internal error.
int ERROR_NONE Indicates that requested operation was successful.
int ERROR_NOT_ALLOWED Indicates that requested operation was already requested by another administrator and is currently active or in progress.
int ERROR_NOT_READY Indicates that service is not yet ready.
int ERROR_NOT_SUPPORTED Indicates that feature is not supported on this device.
int ERROR_PERMISSION_DENIED Indicates that caller does not have permission to perform the requested operation.
int ERROR_UNKNOWN Indicates an unknown error.
Public Methods
boolean canConfigure()
API to check whether the calling administrator is allowed to customize the lock screen.
boolean changeLockScreenString(String statement)
API to change the text displayed on the lock screen.
int configure(String enterpriseName, String enterpriseLogo, String enterpriseAddress, String enterprisePhone)
API to customize the lock screen overlay.
int configure(LSOImage[] imageList)
API to customize the lock screen overlay.
float getAlpha()
API to retrieve lock screen overlay alpha level set earlier using setAlpha(float).
String getCurrentLockScreenString()
API to get the current text displayed on the lock screen.
String getEmergencyPhone()
API to retrieve the enterprise emergency phone number set earlier using API setEmergencyPhone(String).
LockscreenOverlay.LSOEmergencyPhoneInfo getEmergencyPhoneInfo()
API to retrieve information on the enterprise emergency phone number set earlier using API setEmergencyPhoneInfo(LSOEmergencyPhoneInfo).
boolean isConfigured()
API to check whether the lock screen has been customized.
void removeEmergencyPhone()
API to remove the enterprise emergency phone number.
void resetAll()
API to reset entire lock screen customization (overlay, Wallpaper, and enterprise emergency number).
void resetOverlay()
API to reset or remove lock screen overlay customization.
void resetWallpaper()
API to reset lock screen Wallpaper.
int setAlpha(float alphaLevel)
API to set the lock screen overlay alpha level (overlay transparency).
int setEmergencyPhone(String emergencyPhoneNumber)
API to configure enterprise emergency phone number.
int setEmergencyPhoneInfo(LockscreenOverlay.LSOEmergencyPhoneInfo phoneInfo)
API to configure enterprise emergency phone number display options.
int setWallpaper(String enterpriseWallpaper)
Deprecated in API level 27
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final float DEFAULT_ALPHA_LEVEL

Since: API level 6

Default Alpha Level.

Since
API level 6
MDM 4.0
Constant Value: 1.0

public static final int ERROR_BAD_STATE

Since: API level 6

Indicates that the requested operation cannot be completed in the current state.

Since
API level 6
MDM 4.0
Constant Value: -6 (0xfffffffa)

public static final int ERROR_FAILED

Since: API level 6

Indicates that requested operation failed due to some internal error.

Since
API level 6
MDM 4.0
Constant Value: -4 (0xfffffffc)

public static final int ERROR_NONE

Since: API level 6

Indicates that requested operation was successful. configure(LSOImage[])

Since
API level 6
MDM 4.0
Constant Value: 0 (0x00000000)

public static final int ERROR_NOT_ALLOWED

Since: API level 6

Indicates that requested operation was already requested by another administrator and is currently active or in progress.

Since
API level 6
MDM 4.0
Constant Value: -1 (0xffffffff)

public static final int ERROR_NOT_READY

Since: API level 6

Indicates that service is not yet ready.

Since
API level 6
MDM 4.0
Constant Value: -5 (0xfffffffb)

public static final int ERROR_NOT_SUPPORTED

Since: API level 6

Indicates that feature is not supported on this device.

Since
API level 6
MDM 4.0
Constant Value: -3 (0xfffffffd)

public static final int ERROR_PERMISSION_DENIED

Since: API level 6

Indicates that caller does not have permission to perform the requested operation.

Since
API level 6
MDM 4.0
Constant Value: -2 (0xfffffffe)

public static final int ERROR_UNKNOWN

Since: API level 6

Indicates an unknown error.

Since
API level 6
MDM 4.0
Constant Value: -2000 (0xfffff830)

Public Methods

public boolean canConfigure ()

Since: API level 6

API to check whether the calling administrator is allowed to customize the lock screen.

Returns
  • false if lock screen is configured by another administrator, else true .
Usage
An administrator can use this API to determine whether they are allowed to configure the lock screen. Returns false if the lock screen has already been configured by another administrator. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 if (lso.canConfigure()) {
     Log.w(TAG, "Administrator can customize lock screen");
 } else {
     Log.w(TAG, "Administrator cannot customize lock screen");
 }
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public boolean changeLockScreenString (String statement)

Since: API level 6

API to change the text displayed on the lock screen.

Returns
  • true if operation is successful, else false
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can change the lock screen text. The lock screen text appears only when the device is locked and secured with a pattern, PIN, or password. The text marquees if the data is too big to display at once. System information like low battery or device charging notifications take precedence over the lock screen text. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 String statement = "Custom Text";
 try {
     boolean result = lso.changeLockScreenString(statement);
     if (result == true) {
         Log.d(TAG, "changeLockScreenString has succeeded!");
     } else {
         Log.d(TAG, "changeLockScreenString has failed.");
     }
 } 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_SECURITY" permission which has a protection level of signature.
Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope

public int configure (String enterpriseName, String enterpriseLogo, String enterpriseAddress, String enterprisePhone)

Since: API level 6

API to customize the lock screen overlay. This API customizes the lock screen with enterprise details such as
"ENTERPRISE NAME",
"ENTERPRISE ADDRESS",
"ENTERPRISE NUMBER" and
"ENTERPRISE LOGO".

Parameters
enterpriseName Company name.
enterpriseLogo Image file location of company logo.
enterpriseAddress Company office address.
enterprisePhone Company phone number (maximum number of letter is 30)

Returns
Throws
InvalidParameterException If enterpriseName and/or enterpriseAddress is null or zero length.
SecurityException If caller does not have required permissions,
Usage
An administrator can use this API to configure enterprise details on top of device lock screen. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 int result = lso.configure("SAMSUNG TELECOM AMERICA", "/data/extSdCard/assets/samsung_logo.png",
         "1301 E Lookout Drive\nRichardson, TX 75082", "972-761-6000");
 
 if (LockscreenOverlay.ERROR_NONE == result) {
     Toast.makeText(mContext, "Lockscreen customized.", Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Failed to customize Lockscreen.", Toast.LENGTH_SHORT).show();
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permission with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public int configure (LSOImage[] imageList)

Since: API level 6

API to customize the lock screen overlay. This API customizes the lock screen with one or more images.

Parameters
imageList List of images with top and bottom positions in percentages (%).

Returns
Throws
SecurityException If caller does not have required permissions
InvalidParameterException If parameter do not follow the above mentioned rules.
Usage
An administrator can use this API to configure semi-transparent images on the device.
The following rules must be followed when passing one or more images as input parameters.
    1. Top and bottom position for each image element must be set in terms of screen percentage (%).
    2. Image top position should never be greater than or equal to its own bottom position.
    3. No two images should overlap.
          i.e. imageList[i+1].topPosition should be greater or equal than imageList[i].bottomPosition.
    4. All images in the imageList must be in sorted order of their top/bottom positions.
          i.e. image[i].topPosition cannot be less than image[i-1].topPosition and
          image[i].bottomPosition cannot be less than image[i-1].bottomPosition 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 LSOImage[] imageList = new LSOImage[2];
 imageList[0] = new LSOImage(25, "/data/extSdCard/assets/rib3.png", 65);
 imageList[1] = new LSOImage(70, "/data/extSdCard/assets/rib4.png", 90, ScaleType.CENTER);
 
 int result = lso.configure(imageList);
 
 if (LockscreenOverlay.ERROR_NONE == result) {
     Toast.makeText(mContext, "Lockscreen customized.", Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Failed to customize Lockscreen.", Toast.LENGTH_SHORT).show();
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permission with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public float getAlpha ()

Since: API level 6

API to retrieve lock screen overlay alpha level set earlier using setAlpha(float).

Returns
  • Lockscreen overlay Alpha value.
Usage
An administrator can use this API to get alpha (transparency) level for the lock screen overlay. The alpha level is a value in the range 0 to 1, where 0 means the view is transparent and 1 means the view is opaque.

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 float alpha = lso.getAlpha();
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public String getCurrentLockScreenString ()

Since: API level 6

API to get the current text displayed on the lock screen.

Returns
  • The current text string shown on the lock screen if successful, else null.
Throws
SecurityException If caller does not have required permissions
Usage
Returns the current text set by the administrator to be displayed on the lock screen. This text appears only when the device is locked and secured with a pattern, PIN, or password. 
 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 try {
     String text = lso.getCurrentLockScreenString();
     Log.d(TAG, "lockscreenString" + text);
  
 } 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_SECURITY" permission which has a protection level of signature.
Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope
See Also

public String getEmergencyPhone ()

Since: API level 6

API to retrieve the enterprise emergency phone number set earlier using API setEmergencyPhone(String).

Returns
  • Enterprise emergency phone number.
Usage
An administrator can use this API to retrieve the enterprise support or emergency phone number configured on the device. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 String eePhone = lso.getEmergencyPhone();
 
 if (eePhone != null) {
     Toast.makeText(mContext, "Emergency number is " + eeePhone, Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Unable to retrieve emergency phone number", Toast.LENGTH_SHORT)
             .show();
 }

Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public LockscreenOverlay.LSOEmergencyPhoneInfo getEmergencyPhoneInfo ()

Since: API level 6

API to retrieve information on the enterprise emergency phone number set earlier using API setEmergencyPhoneInfo(LSOEmergencyPhoneInfo).

Returns
  • Enterprise emergency phone number.
Usage
An administrator can use this API to retrieve information on the enterprise support or emergency phone number configured on device. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 LSOEmergencyPhoneInfo phoneInfo = lso.getEmergencyPhoneInfo();
 
 if (eePhone != null) {
     Toast.makeText(mContext, "Emergency number is " + phoneInfo.phoneNumber, Toast.LENGTH_SHORT)
             .show();
 } else {
     Toast.makeText(mContext, "Unable to retrieve emergency phone number", Toast.LENGTH_SHORT)
             .show();
 }

Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public boolean isConfigured ()

Since: API level 6

API to check whether the lock screen has been customized.

Returns
  • true if lock screen is configured, else false .
Usage
An administrator can use this API to determine whether the lock screen has been customized. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 if (lso.isConfigured()) {
     Log.w(TAG, "Lock screen is customized");
 } else {
     Log.w(TAG, "Lock screen is not customized");
 }
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public void removeEmergencyPhone ()

Since: API level 6

API to remove the enterprise emergency phone number.

Throws
SecurityException If caller does not have required permissions
AccessControlException If caller is not allowed to remove enterprise emergency phone number.
Usage
An administrator can use this API to remove the enterprise emergency phone number set earlier using setEmergencyPhone(String).

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 try {
     lso.removeEmergencyPhone();
 } catch (AccessControlException se) {
     Log.e(TAG, "Cannot remove as the lock screen is customized by another administrator.");
 } catch (SecurityException se) {
     Log.e(TAG, "Security Exception : " + se);
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public void resetAll ()

Since: API level 6

API to reset entire lock screen customization (overlay, Wallpaper, and enterprise emergency number).

Throws
SecurityException If caller does not have required permissions,
AccessControlException If caller is not allowed to reset lock screen.
Usage
An administrator can use this API to reset a customized lock screen to the default state. This API has no effect if no item was configured earlier or if another administrator customized the lock screen.

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 try {
     lso.resetAll();
 } catch (AccessControlException se) {
     Log.e(TAG, "Cannot reset as the lock screen is customized by another administrator.");
 } catch (SecurityException se) {
     Log.e(TAG, "Security Exception : " + se);
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public void resetOverlay ()

Since: API level 6

API to reset or remove lock screen overlay customization.

Throws
SecurityException If caller does not have required permissions
AccessControlException If caller is not allowed to reset lock screen overlay.
Usage
An administrator can use this API to reset the lock screen overlay. This API has no effect if no item was configured earlier or if another administrator customized the lock screen.
Lock screen customized overlay can be set using configure(String, String, String, String) or configure(LSOImage[]). 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 try {
     lso.resetOverlay();
 } catch (AccessControlException se) {
     Log.e(TAG, "Cannot reset as the lock screen is customized by another administrator.");
 } catch (SecurityException se) {
     Log.e(TAG, "Security Exception : " + se);
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public void resetWallpaper ()

Since: API level 6

API to reset lock screen Wallpaper.

Throws
SecurityException If caller does not have required permissions,
AccessControlException If caller is not allowed to reset lock screen Wallpaper.
Usage
An administrator can use this API to remove the lock screen Wallpaper set earlier using setWallpaper(String). This API has no effect if no item was configured earlier or if another administrator customized the lock screen.

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 try {
     lso.resetWallpaper();
 } catch (AccessControlException se) {
     Log.e(TAG, "Cannot reset as the lock screen is customized by another administrator.");
 } catch (SecurityException se) {
     Log.e(TAG, "Security Exception : " + se);
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public int setAlpha (float alphaLevel)

Since: API level 6

API to set the lock screen overlay alpha level (overlay transparency). The alpha level is a value in the range 0 to 1, where 0 means the view is transparent and 1 means the view is opaque. This API does not affect the overlay for enterperise emergency calls.

Parameters
alphaLevel Alpha level in the range 0 to 1.

Returns
Throws
SecurityException If caller does not have required permission
InvalidParameterException If value passed as parameter is not in the range 0 to 1.
Usage
An administrator can use this API to set the transparency level. The administrator should call this API only after the lock screen overlay is configured using configure(String, String, String, String) or configure(LSOImage[]). 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 lso.setAlpha((float) 0.5);
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public int setEmergencyPhone (String emergencyPhoneNumber)

Since: API level 6

API to configure enterprise emergency phone number.

Parameters
emergencyPhoneNumber Enterprise Emergency phone number.

Returns
Throws
SecurityException If caller does not have required permissions
InvalidParameterException If emergencyPhoneNumber is null or zero length.
Usage
An administrator can use this API to configure an enterprise support/emergency phone number on the device. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 int result = lso.setEmergencyPhone("972-761-6000");
 
 if (LockscreenOverlay.ERROR_NONE == result) {
     Toast.makeText(mContext, "Emergency number set.", Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Failed to set Emergency phone number.", Toast.LENGTH_SHORT).show();
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public int setEmergencyPhoneInfo (LockscreenOverlay.LSOEmergencyPhoneInfo phoneInfo)

Since: API level 6

API to configure enterprise emergency phone number display options.

Parameters
phoneInfo Emergency phone widget parameters.

Returns
Throws
SecurityException If caller does not have required permissions
InvalidParameterException If emergencyPhoneNumber is null or zero length.
Usage
An administrator can use this API to configure display options used when presenting the enterprise emergency phone number. For example, the administrator can use this API to configure the location on the screen where the emergency call widget must be displayed (Widget icon and text). 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 LSOEmergencyPhoneInfo phoneInfo = lso.getEmergencyPhoneInfo();
 phoneInfo.text = "SAMSUNG";
 phoneInfo.icon = "/data/data/com.samsung.testapp/callicon.jpg";
 phoneInfo.topPosition = 25;
 phoneInfo.bottomPosition = 75;
 phoneInfo.gravity = Gravity.TOP | Gravity.CENTER_HORIZONTAL;
 
 int result = lso.setEmergencyPhoneInfo(phoneInfo);
 
 if (LockscreenOverlay.ERROR_NONE == result) {
     Toast.makeText(mContext, "Emergency number set.", Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Failed to set emergency phone number.", Toast.LENGTH_SHORT).show();
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also

public int setWallpaper (String enterpriseWallpaper)

Since: API level 6

Deprecated in API level 27

API to customize lock screen Wallpaper.

Parameters
enterpriseWallpaper Image file location of Enterprise Wallpaper.

Returns
Throws
SecurityException If caller does not have required permissions
InvalidParameterException If enterpriseWallpaper is null or zero length.
Usage
An administrator can use this API to set lock screen Wallpaper.

NOTE: It is recommended administrator to use image with resolution which is in proportion to the device screen dimensions. 

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 LockscreenOverlay lso = edm.getLockscreenOverlay();
 
 int result = lso.setWallpaper("/data/extSdCard/assets/samsung_wallpaper.jpeg");
 
 if (LockscreenOverlay.ERROR_NONE == result) {
     Toast.makeText(mContext, "Lockscreen Wallpaper is changed.", Toast.LENGTH_SHORT).show();
 } else {
     Toast.makeText(mContext, "Failed to update Lockscreen Wallpaper.", Toast.LENGTH_SHORT).show();
 }
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_LOCKSCREEN" permissions with a protection level of signature
Since
API level 6
MDM 4.0
Multiuser Environment
Global Scope
See Also