Window permissions

Window permissions allow a window to control who has accessibility to it; they can provide some specific accessibility that would otherwise require root permissions.

You can set your window permissions through the window property, SCREEN_PROPERTY_PERMISSIONS. This property can be retrieved and set by using the Screen API functions screen_get_window_property_iv() and screen_set_window_property_iv() respectively.

Window permissions can be set dynamically; this means you can set window permissions at any time. However, note that window permissions are not cached. If you change permissions, you need to ensure that it doesn't interfere with any ongoing processing that your application is doing. For example, a screen_blit() could be successful, but then if permissions are incorrectly changed, the subsequent call to screen_blit() will fail.

Window permissions apply only to window properties that can be changed by the owner of the window. Window properties that can be changed only by the parent window remain unaffected regardless of the setting of your SCREEN_PROPERTY_PERMISSIONS property. The exception is that if the window has no parent or if there is no window manager, then the window permissions will apply to all window properties.

Similar to setting file permissions with chmod (change file modes in POSIX), if you want someone to have special access to a window, you need to set the appropriate permissions on that window. Again, following file permissions conventions, window permissions control the read, write and execute accessibilities to your window.

Read, write and execute permissions can be specified for each class of user for a window. Note that in the case of window permissions, the following mapping applies:

read

Read permission means that the following functions can be performed on the window:

screen_read_window()
screen_get_window_property()
screen_blit() when the window is the source

write

Write permission means that the following functions can be performed on the window:

screen_set_window_property()
screen_blit() when the window is the destination

execute

Execute permission means that the screen_inject_event() function can be performed on the window.

Class	Mask group	Description	Permission masks
Window	WIN	If you are the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRWIN SCREEN_PERMISSION_IWWIN SCREEN_PERMISSION_IXWIN
Parent	TOP	If you are the parent of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRTOP SCREEN_PERMISSION_IWTOP SCREEN_PERMISSION_IXTOP
User ID	USR	If you have the same user ID as the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRUSR SCREEN_PERMISSION_IWUSR SCREEN_PERMISSION_IXUSR
Group ID	GRP	If you have the same group ID as the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRGRP SCREEN_PERMISSION_IWGRP SCREEN_PERMISSION_IXGRP
Process ID	PID	If you have the same process ID as the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRPID SCREEN_PERMISSION_IWPID SCREEN_PERMISSION_IXPID
Process group ID	PGP	If you have the same process group ID as the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRPGP SCREEN_PERMISSION_IWPGP SCREEN_PERMISSION_IXPGP
Application group	AGP	If you are in the same application group as the owner of this window, you will have the specified permissions to this window.	SCREEN_PERMISSION_IRAGP SCREEN_PERMISSION_IWAGP SCREEN_PERMISSION_IXAGP
Others	OTH	Anyone will have the specified permissions to this window.	SCREEN_PERMISSION_IROTH SCREEN_PERMISSION_IWOTH SCREEN_PERMISSION_IXOTH

For example, let's say that SCREEN_PERMISSION_IRPID, SCREEN_PERMISSION_IWPID, and SCREEN_PERMISSION_IXPID are set for a window. In this case, if you have the same process ID as that window, then you are permitted to perform the following on that window respectively:

call screen_read_window()
call screen_set_window_property()
call screen_inject_event()
call screen_blit() with that window as either source or destination

If you do not explicitly set the window permissions for your window, then the SCREEN_PROPERTY_PERMISSIONS property for your window has the following permissions by default:

Class	Permission masks
Window	SCREEN_PERMISSION_IRWIN SCREEN_PERMISSION_IWWIN SCREEN_PERMISSION_IXWIN
Parent	SCREEN_PERMISSION_IRTOP SCREEN_PERMISSION_IXTOP
User ID	SCREEN_PERMISSION_IXUSR
Group ID	SCREEN_PERMISSION_IXGRP
Process ID	SCREEN_PERMISSION_IXPID
Process group ID	SCREEN_PERMISSION_IXPGP
Application group	SCREEN_PERMISSION_IXAGP

Note: SCREEN_PROPERTY_PERMISSIONS is changed by calling screen_set_window_property_iv() and this function is delayed in its execution. That is, the command is queued for batch processing at a later time. Remember to perform a flush using screen_flush() to ensure that your permissions are changed and will take effect when you expect them to.