Remote Desktop Module provides means by which the admin capture the device screen content. More...

#include <RemoteDesktop.h>

Public Member Functions
virtual bool	init ()=0
	API to initialize remote desktop session.
virtual void	getScreenInfo (int width, int height, int bytesPerPixel, int pixelFormat)=0
	API to get Frame Buffer's Resolution/PixelFormat information.
virtual bool	getFrameBufInfo (int fd, FDType fdType)=0
	API to get Frame Buffer Information.
virtual bool	setListener (IRemoteDesktopListener *listener)=0
	API to register Screen Event listener.
virtual bool	captureScreen (DirtyRegion &region)=0
	API to capture the screen.
virtual void	getScreenPixelFormatInfo (PixelFormatDetail &formatDetail)=0
	API to get screen pixel format information.
virtual bool	setScreenInfo (int prefW, int prefH, int prefFormat)=0
	API to set the framebuffer's width, height and format preferred by the admin.
virtual void	getDefaultScreenInfo (int hwwidth, int hwheight, int hwbytesPerPixel, int hwpixelFormat)=0
	API to get the default screen information.
virtual int	getDefaultDexScreenInfo (int hwwidth, int hwheight, int *hwbytesPerPixel)=0
	API to get the default Dex screen information.
virtual bool	setDexScreenInfo (int prefW, int prefH)=0
	API to set Dex screen framebuffer's width and height by the admin.
virtual void	getDexBufInfo (int *fdDex)=0
	API to get Dex screen Frame Buffer Information.
virtual void	getDexScreenInfo (int width, int height, int *bytesPerPixel)=0
	API to get Dex screen Frame Buffer's Resolution.
Static Public Member Functions
static IRemoteDesktop *	getInstance ()
	Returns an instance of a RemoteDesktop client.

Detailed Description

Remote Desktop Module provides means by which the admin capture the device screen content.

It provides the following features for EDM client

Access to screen content through shared memory from Surface Flinger.

(Note: Surface Flinger is android's composition engine that composes the

UI content and updates to the display

or Access to screen content through Read-only access to the framebuffer device.

Screen Changed Notifications

( This prevents the EDM client from having to poll the screen content continuously

to check for changes. The notifications shall be received for both approaches fb0

and surface flinger.)

Dirty Region feedback after capture

The decision to use framebuffer device (fb0) or Surface Flinger mechanism is made based on the

following aspects

Availability of the approach

(Eg: - Only Surface Flinger approach works in some devices as the frame buffer

device is not accessible/available),

Frame rate yielded by individual approach and

Accuracy of the screen content

(Eg: - FB0 misses some overlay content. Lets say, Wallpaper is present in one

layer, Status Bar present in one layer, remaining UIs present in another layer).

Note: This decision is done for every device at build time.

The EDM client can register a listener to receive notifications when the screen changes.

On occurrence of screen change, the Remote Desktop module sends a screenChanged callback and

waits for the capture request from the client.

(Note: Subsequent screen changes are detected, but they are not notified to the client until

the capture request for the outstanding callback is received.)

In case of Remote Desktop session

1) If Remote Desktop Session is started at owner space

a) It can capture owner space screens

b) It can capture Android guest user's screens

2) If Remote Desktop Session is started at Android guest user

a) It can't capture owner space screens

b) It can capture its own user space screens

Events injected by Remote Injection are not injected into user space where Remote Desktop

is disabled.

PolicyGroupID:: Remote Control

Since:: API level 3; MDM 2.1

Permission:: This policy requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission

which has a protection level of signature.

Member Function Documentation

virtual bool knoxremotedesktop::IRemoteDesktop::captureScreen ( DirtyRegion & region ) [pure virtual]

API to capture the screen.

Admin can use this API to capture the screen. Remote Desktop

module returns the changed region or dirty region in response

to this request. (This API updates the screen contents to shared memory

if fdType == FD_SHARED_MEM.)

[NOTE] It is recommended to follow the following sequence:

Step 1 : Call IRemoteDesktop::getInstance() to get an instance of IRemoteDesktop

Step 2 : Call IRemoteDesktop::getDefaultScreenInfo(&hwwidth,&hwheight,&hwbytesPerPixel,&hwpixelFormat) to get the hardware width,height,pixel size and format

Step 3 : Call IRemoteDesktop::setScreenInfo (prefW, prefH, prefFormat) to set the desired screen width,height and pixel format

Step 4 : Call IRemoteDesktop::init()

Step 5 : Call IRemoteDesktop::getFrameBufInfo() to get file descriptor and type of it

Step 6 : Call mmap() to map file descriptor to memory

Step 7 : Set screen update listener

Step 8 : Call IRemoteDesktop::captureScreen() to get dirty regions after screenChanged() callback is called

Example client call:

 class RemoteDesktopListener : public IRemoteDesktopListener {

 	 RemoteDesktopListener() {}

 	 virtual void screenChanged() {

 		 LOGI("RemoteDesktopListener :: screenChanged()");

		   	 // Capture Screen Request code

			 DirtyRegion dirtyRegion;

			 bool err = remoteDesktop->captureScreen(dirtyRegion);

			 if(err == false)  {

				 // failure code

			} else {

				 // success code

	 ....

	 IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

	 int w = 360, h = 640, format = PF_RGBA_8888;

	 //Only in case, when user is in Landscape mode and facing problem in starting the Remote Session in Android 10 device
	 int w = 640, h = 360, format = PF_RGBA_8888;

	 int	  mFD;

	 FDType   mFDType;

	 bool ret;

	 int	hwwidth, hwheight, hwpixelFormat, hwbytesPerPixel;

	 remotedesktop->getDefaultScreenInfo(&hwwidth, &hwheight, &hwbytesPerPixel, &hwpixelFormat);

	 ret = remoteDesktop->setScreenInfo(w,h,format);

	 if(ret == false){

		 // failure code

	 ret = remoteDesktop->init();

	 if(ret == false){

		 // failure code

	 ret = remoteDesktop->getFrameBufInfo(&mFD, &mFDType);

	 if(ret == false){

		 // failure code

	 if (mFDType == FD_DEV_FB0) {

		 struct fb_var_screeninfo vinfo;

		 if(ioctl(mFD, FBIOGET_VSCREENINFO, &vinfo) < 0) return false;

		 int offset = vinfo.xoffset * mBytesPerPixel + vinfo.xres * vinfo.yoffset * mBytesPerPixel;

		 mFrame = (unsigned short *) mmap(0, mFrameBufferSize, PROT_READ, MAP_PRIVATE, mFD, offset);

	 } else if (mFDType == FD_SHARED_MEM) {

		 mFrame = (unsigned short *) mmap(0, mFrameBufferSize, PROT_READ, MAP_SHARED, mFD, 0);

	 } else {

		 LOGE("mapFrameBuffer Failed");

		 return false;

	 IRemoteDesktopListener *remoteDesktoplistener = new RemoteDesktopListener();

	 remoteDesktop->setListener(remoteDesktoplistener);

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

region Dirty Region Information

Returns:: true if captured successfully, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getScreenInfo(int*, int*, int*, int*); getFrameBufInfo(int *, FDType *)

virtual int knoxremotedesktop::IRemoteDesktop::getDefaultDexScreenInfo	(	int *	hwwidth,
		int *	hwheight,
		int *	hwbytesPerPixel
	)		`[pure virtual]`

API to get the default Dex screen information.

Admin can use this API to get the default hardware screen dimensions and pixel byte size of Dex sreen. This new API is introduced for devices that support samsung Dex mode.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();
  bool ret = remoteDesktop->init();
  if(ret == false)  {
     // failure code
  } else {
     // success code	 
  // Dex state change callback received
     int	hwwidth, hwheight, hwbytesPerPixel;	
     int res = remotedesktop->getDefaultDexScreenInfo(&hwwidth, &hwheight, &hwbytesPerPixel);
  }

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

Parameters:

hwwidth	Hardware Screen Width of Dex screen.
hwHeight	Hardware Screen Height of Dex screen.
hwbytesPerPixel	Hardware Pixel Size in Bytes of Dex screen.

Returns:: Integer value -1 when user does not have permission to call this API.; Integer value 0 If successfully able to fetch the given parameters.; Integer value 1 when Dex is not connected to device.; Integer value 2 Due to some unknown error.

Since:: API level 30; KNOX 3.4.1

See also:: setDexScreenInfo(int prefW, int prefH); getDexBufInfo(int * fdDex); getDexScreenInfo(int *width, int *height, int *bytesPerPixel)

virtual void knoxremotedesktop::IRemoteDesktop::getDefaultScreenInfo	(	int *	hwwidth,
		int *	hwheight,
		int *	hwbytesPerPixel,
		int *	hwpixelFormat
	)		`[pure virtual]`

API to get the default screen information.

Admin can use this API to get the default hardware screen dimensions, pixel formats and

pixel byte size. This new API is introduced as getScreenInfo need not return the default screen

information as it returns the selected framebuffer information based on the preferences

set by the admin

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  {

     // failure code

  } else {

     // success code

     int	hwwidth, hwheight, hwpixelFormat, hwbytesPerPixel;

     remotedesktop->getDefaultScreenInfo(&hwwidth, &hwheight, &hwbytesPerPixel, &hwpixelFormat);

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

hwwidth	Hardware Screen Width
hwHeight	Hardware Screen Height
hwbytesPerPixel	Hardware Pixel Size in Bytes
hwpixelFormat	Hardware Pixel Format.

Returns:: nothing

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getFrameBufInfo(int *, FDType *); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

virtual void knoxremotedesktop::IRemoteDesktop::getDexBufInfo ( int * fdDex ) [pure virtual]

API to get Dex screen Frame Buffer Information.

Admin can use this API to get File Descriptor of Dex screen Shared memory.
[Note] For Dex screen file descriptor type (FDType) is always Shared Memory.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();
  bool ret = remoteDesktop->init();
  if(ret == false)  {
     // failure code
  } else {
     // success code	 
     // Dex state change callback received
     int mFDdex;
     int w = 640, h = 360;
     bool ret = remoteDesktop->setDexScreenInfo(w,h);
     remoteDesktop->getDexBufInfo(&mFDdex);
     if(mFDdex == -1)  {
         // failure code
     } else {
         // success code	 
     }
  }

Permission:: None

Parameters:

fd	File Descriptor for Dex screen buffer

Returns:: nothing

Since:: API level 30; KNOX 3.4.1

See also:: getDefaultDexScreenInfo(int *hwwidth, int *hwheight, int *hwbytesPerPixel); getDexScreenInfo(int *width, int *height, int *bytesPerPixel); setDexScreenInfo(int prefW, int prefH)

virtual void knoxremotedesktop::IRemoteDesktop::getDexScreenInfo	(	int *	width,
		int *	height,
		int *	bytesPerPixel
	)		`[pure virtual]`

API to get Dex screen Frame Buffer's Resolution.

Admin can use this API to get Dex screen framebuffer dimensions and pixel byte size.

Note: Client should use same pixel format info for Dex screen buffer that is returned for device screen buffer.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();
  bool ret = remoteDesktop->init();
  if(ret == false)  {
     // failure code
  } else {
     // success code	 
     // Dex state change callback received
     int w = 640, h = 360;
     bool ret = remoteDesktop->setDexScreenInfo(w,h);
     int width, height, bytesPerPixel;
     remoteDesktop->getDexScreenInfo(&width, &height, &bytesPerPixel);
  }

Permission:: None

Parameters:

width	Screen Width
height	Screen Height
bytesPerPixel	Pixel Size in Bytes

Returns:: nothing

Since:: API level 30; KNOX 3.4.1

See also:: getDefaultDexScreenInfo(int *hwwidth, int *hwheight, int *hwbytesPerPixel); getDexBufInfo(int * fdDex); setDexScreenInfo(int prefW, int prefH)

virtual bool knoxremotedesktop::IRemoteDesktop::getFrameBufInfo	(	int *	fd,
		FDType *	fdType
	)		`[pure virtual]`

API to get Frame Buffer Information.

Admin can use this API to get File Descriptor to

framebuffer device or Shared memory.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  {

     // failure code

  } else {

     // success code

     int	     mFD;

     FDType 	 mFDType;

     bool err = remoteDesktop->getFrameBufInfo(&mFD, &mFDType);

     if(err == false)  {

         // failure code

     } else {

         // success code

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

fd	File Descriptor
fdType	File Descriptor Type (Shared Memory or Frame Buffer)

Returns:: true if frame buffer information successfully retrieved, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getScreenInfo(int*, int*, int*, int*); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

static IRemoteDesktop* knoxremotedesktop::IRemoteDesktop::getInstance ( ) [static]

Returns an instance of a RemoteDesktop client.

Admin can use this API to initialize the remote desktop session

establishing the connection to the underneath capture mechanism.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  { // failure due to either permission

                      // denied or other initialization failures

     // failure code

  } else {

     // success code

Returns:: A remote desktop instance if successful, else null.

Since:: API level 3; MDM 2.1

virtual void knoxremotedesktop::IRemoteDesktop::getScreenInfo	(	int *	width,
		int *	height,
		int *	bytesPerPixel,
		int *	pixelFormat
	)		`[pure virtual]`

API to get Frame Buffer's Resolution/PixelFormat information.

Admin can use this API to get the framebuffer dimensions, pixel formats and

pixel byte size.

Note: PixelFormat returned by this API is not reliable. It will not give accurate information

on the exact position details of each pixel. Also for FB0 FDType, the pixel format may also be returned

as PF_UNKNOWN. It is recommended that client always rely on the API getScreenPixelFormatInfo().

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  {

     // failure code

  } else {

     // success code

     int	width, height, pixelFormat, bytesPerPixel;

     remoteDesktop->getScreenInfo(&width, &height, &bytesPerPixel, &pixelFormat);

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

width	Screen Width
height	Screen Height
bytesPerPixel	Pixel Size in Bytes
pixelFormat	Pixel Format.

Returns:: true if screen information successfully retrieved, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getFrameBufInfo(int *, FDType *); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

virtual void knoxremotedesktop::IRemoteDesktop::getScreenPixelFormatInfo ( PixelFormatDetail & formatDetail ) [pure virtual]

API to get screen pixel format information.

Admin can use this API to get the pixel format detailed information.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  {

     // failure code

  } else {

     // success code

     PixelFormatDetail formatDetail;

     remoteDesktop->getScreenPixelFormatInfo(formatDetail);

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

formatDetail Pixel Format Detail

Returns:: nothing

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getFrameBufInfo(int *, FDType *); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

virtual bool knoxremotedesktop::IRemoteDesktop::init ( ) [pure virtual]

API to initialize remote desktop session.

Admin can use this API to initialize the remote desktop session

establishing the connection to the underneath capture mechanism.

Example client call:

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  { // failure due to either permission

                      // denied or other initialization failures

     // failure code

  } else {

     // success code

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Returns:: true if successfully initialised, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); getScreenInfo(int*, int*, int*, int*); getFrameBufInfo(int *, FDType *); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

virtual bool knoxremotedesktop::IRemoteDesktop::setDexScreenInfo	(	int	prefW,
		int	prefH
	)		`[pure virtual]`

API to set Dex screen framebuffer's width and height by the admin.

Admin can use this API to set the preference for the remote capture of Dex screen dimensions considering the different factors like network bandwidth usage and performance. This may or may not be honoured based on the platform support. This API creates a separate frame buffer for Dex screen capture.

Example client call:

  int w = 640, h = 360;
  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();
  bool ret = remoteDesktop->init();
  // Dex state change callback received
  int hwwidth, hwheight, hwbytesPerPixel;	
  int res = remotedesktop->getDefaultDexScreenInfo(&hwwidth, &hwheight, &hwbytesPerPixel);
  ret = remoteDesktop->setDexScreenInfo(w,h);

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

Parameters:

prefW	Preferred Screen Width of Dex screen
prefH	Preferred Screen Height of Dex screen.

Returns:: true if intended operation is successful; false multiple cases like Dex is not connected, invalid parameter value, permission denied, remote session not started or unable to create buffer for Dex screen.

Since:: API level 30; KNOX 3.4.1

See also:: getDefaultDexScreenInfo(int *hwwidth, int *hwheight, int *hwbytesPerPixel); getDexBufInfo(int * fdDex); getDexScreenInfo(int *width, int *height, int *bytesPerPixel)

virtual bool knoxremotedesktop::IRemoteDesktop::setListener ( IRemoteDesktopListener * listener ) [pure virtual]

API to register Screen Event listener.

Admin can use this API to get Screen Changed Event Callbacks

from remote desktop module.

Example client call:

  class RemoteDesktopListener : public IRemoteDesktopListener {

      RemoteDesktopListener() {}

      virtual void screenChanged() {

	        LOGI("RemoteDesktopListener :: screenChanged()");

          // Capture Screen Request code

  ....

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  bool ret = remoteDesktop->init();

  if(ret == false)  {

     // failure code

  } else {

     // success code

     IRemoteDesktopListener *remoteDesktoplistener = new RemoteDesktopListener();

     bool err = remoteDesktop->setListener(remoteDesktoplistener);

     if(err == false)  {

         // failure code

     } else {

         // success code

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

listener Screen Change Event Listener

Returns:: true if listener is successfully set, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); init(); getScreenInfo(int*, int*, int*, int*); getFrameBufInfo(int *, FDType *); captureScreen(DirtyRegion&)

virtual bool knoxremotedesktop::IRemoteDesktop::setScreenInfo	(	int	prefW,
		int	prefH,
		int	prefFormat
	)		`[pure virtual]`

API to set the framebuffer's width, height and format preferred by the admin.

Admin can use this API to set the preference for the remote screen dimensions considering the

different factors like network bandwidth usage and performance. This may or may not be honoured based

on the platform support. Mostly in case of FB0, this will not be honoured.

Example client call:

  Note: If user faces problem in starting Remote Session in Landscape mode, then he/she should call 
  and refer getDefaultScreenInfo(&hwwidth,&hwheight,&hwbytesPerPixel,&hwpixelFormat) API about
  hardware width and hardware height before calling setScreenInfo(prefW, prefH, prefFormat) API.

  int w = 360, h = 640, format = PF_RGB_565;

  //Only in case, when user is in Landscape mode and facing problem in starting the Remote Session in Android 10 device
  int w = 640, h = 360, format = PF_RGB_565;

  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();

  int 	 hwwidth, hwheight, hwpixelFormat, hwbytesPerPixel;

  remotedesktop->getDefaultScreenInfo(&hwwidth, &hwheight, &hwbytesPerPixel, &hwpixelFormat);

  bool ret = remoteDesktop->setScreenInfo(w,h,format);

  if(ret == false)  { // failure due to either permission

                      // denied or other initialization failures

     // failure code

  } else {

     // success code

Permission:: The use of this API requires the caller to have the

"com.samsung.android.knox.permission.KNOX_REMOTE_CONTROL" permission which has a protection level

of signature.

Parameters:

prefW	Preferred Screen Width
prefH	Preferred Screen Height
prefFormat	Preferred Pixel Format

Returns:: true if success, else false.

Since:: API level 3; MDM 2.1

See also:: getInstance(); getScreenInfo(int*, int*, int*, int*); getFrameBufInfo(int *, FDType *); setListener(IRemoteDesktopListener*); captureScreen(DirtyRegion&)

The documentation for this class was generated from the following file:

remotecontrol/RemoteDesktop.h

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation