Mobile Device Management
 
Native SDK
knoxremotedesktop::IRemoteDesktop Class Reference

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

#include <RemoteDesktop.h>

List of all members.

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.

Static Public Member Functions

static IRemoteDesktopgetInstance ()
 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::setScreenInfo (prefW, prefH, prefFormat) to set the desired screen width,height and pixel format

Step 3 : Call IRemoteDesktop::init()

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

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

Step 6 : Set screen update listener

Step 7 : 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;
	 int	  mFD;
	 FDType   mFDType;
	 bool ret;
	 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:
regionDirty 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 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:
hwwidthHardware Screen Width
hwHeightHardware Screen Height
hwbytesPerPixelHardware Pixel Size in Bytes
hwpixelFormatHardware Pixel Format.
Returns:
nothing
Since:
API level 3
MDM 2.1
See also:
getInstance()
init()
getFrameBufInfo(int *, FDType *)
setListener(IRemoteDesktopListener*)
captureScreen(DirtyRegion&)
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:
fdFile Descriptor
fdTypeFile 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&)

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:
widthScreen Width
heightScreen Height
bytesPerPixelPixel Size in Bytes
pixelFormatPixel 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:
formatDetailPixel 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::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:
listenerScreen 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:

  int w = 360, h = 640, format = PF_RGB_565;
  IRemoteDesktop *remoteDesktop = RemoteDesktop::getInstance();
  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:
prefWPreferred Screen Width
prefHPreferred Screen Height
prefFormatPreferred 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:
 All Classes Namespaces Functions Variables Enumerations