eyeOS 2.

x
Developer Manual
English

Translated by Douglas McKechie, October 2010

Contents
0. License................................................................................................................... 3 1. Introduction............................................................................................................ 4 1.1. What is eyeOS?................................................................................................ 4 1.2. The application system..................................................................................... 4 2. Operation................................................................................................................ 5 2.1. System Structure.............................................................................................. 6 2.2. The Database and users Personal Folders........................................................7 3. Development Environment..................................................................................... 7 4. Examination of the components.............................................................................8 4.1. Kernel............................................................................................................... 8 4.2. Services............................................................................................................ 8 4.3. Libraries............................................................................................................ 9 4.4. Frameworks...................................................................................................... 9 4.5. Bootstrap.......................................................................................................... 9 5. Directory Structure............................................................................................... 10 6. MMAP, Exec, and extern....................................................................................... 12 6.1. MMAP.............................................................................................................. 12 6.2. Exec................................................................................................................ 13 7. Structure and function of an application..............................................................13 8. Creating our first application................................................................................ 16 9. Qooxdoo............................................................................................................... 17 9.1. Qooxdoo classes used by eyeOS....................................................................18 10. Application Modules (execmodules)...................................................................18 11. User Manager..................................................................................................... 19 12. Proc Manager...................................................................................................... 20 13. File System Interface.......................................................................................... 21 14. Security Manager ............................................................................................... 22 15. Metadata............................................................................................................ 24 16. Conversion of office documents.........................................................................25 17. Dbus................................................................................................................... 25 2 EyeOS Developer Manual, English

18. NetSync, real time.............................................................................................. 26 19. Database connection.......................................................................................... 27 19.1. Generic DAO................................................................................................. 28 19.2. Direct connection......................................................................................... 30 20. References and further reading..........................................................................30

0. License
The contents of this document are published under the Creative Commons Licence: Attribution NonCommercial - Share Alike 3.0 Unported. You can view a summary of the terms of the license at... http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en You can view the full text of this license at the following address... http://creativecommons.org/licenses/by-nc-sa/3.0/legalcode

You are free: To share to copy, distribute and transmit the work.

To Remix to adapt the work. Under the following conditions: Attribution You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Non commercial You may not use this work for commercial purposes. Share Alike If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

3 EyeOS Developer Manual, English

1. Introduction
The aim of this document is to provide the necessary knowledge to develop on the eyeOS environment; being able to build applications, modify existing applications, to develop components for the system in general, and to understand its architecture. The audience for this document is technical people, for example analysts and web developers. Knowledge of JavaScript and PHP is required, as well as an overall understanding of web development. Understanding of object-orientated programming would also be helpful.

1.1. What is eyeOS?

eyeOS is an online desktop that gives users an interface similar to the interface of the desktop that they most likely have on their computer. For a developer eyeOS provides a set of tools that allow you to develop online desktop applications in a way similar to how you would on a local desktop. Applications in eyeOS are developed using JavaScript graphics libraries which allow the developer to work with higher level concepts, for example windows, buttons, lists, etc, instead of working with layers or low level XHTML. The goal of eyeOS is that for both the user and developer, applications will work in a manner similar to a local desktop by hiding the problems that stem from the fact of working in a web environment. eyeOS is ideal for those wanting to provide their users with a web interface to access resources in a controlled way, with access controls and user accounts, to have the ability to adapt the environment to fit the image of their company or organisation, and to create all new features and functionality to meet their needs.

1.2. The application system

Due to the high importance of being able to develop an application with absolute certainty that another application does not interfere with yours, we have developed eyeOS to be an entire application system where development is as simple as possible. In a sense eyeOS is like a traditional operating system, where each application is run separately, with its own process and its own process id (PID), and where each application can have different execution privileges. 4 EyeOS Developer Manual, English

Thus, an application in eyeOS is an independent component that you can install or uninstall just like any application in Windows or Linux. You may also define a set of security rules so that only one user or user group can see, install, and use the application on their desktop. As will be seen later, the system provides an API to manage applications that a user is running, for example to close a running application, or to run new applications. It is through this API that the system is able to run each application without it interfering with another and to even run multiple instances of the same application. The eyeOS system handles low-level operations, for example when the user closes an application the process is removed automatically. The developer does not have to worry about these details, but if desired, can intervene and change the default behaviour and actions throughout the system.

2. Operation
Technically, eyeOS is a web application developed in PHP and JavaScript. PHP is used to develop the architecture on the server side, while JavaScript is used to create and manage the desktop and applications displayed in the web browser client. All the eyeOS applications, such as Login, Register, or Calculator, are a set of JavaScript and PHP scripts. Even the desktop itself is an eyeOS application that can be modified. When the system first loads, the users web browser downloads all the necessary JavaScript libraries and then begins to communicate with the server using AJAX. In this way, throughout the user's session there is only one page load; the remaining operations are performed using AJAX requests. In the first load of eyeOS only the JavaScript libraries that are needed for the operation of the system are downloaded. JavaScript files specific to each application are downloaded on demand when the application runs for the first time. The next time an application is run the system will use the JavaScript already in memory. When the users run an application in eyeOS a visual window usually appears so that they can interact with it. The window is created by a high-level JavaScript library called Qooxdoo; this is much like GTK, Qt, Java Swing, or similar development toolkits with user interfaces. When the user interface requires the JavaScript to perform an operation on the server, communication libraries are used to send

5 EyeOS Developer Manual, English

messages (which are low-level AJAX requests) to the PHP functions defined by the creator of the application. Throughout this document it will become clearer how eyeOS works; to begin with it will be quite useful to give you an overview of the system. Applications run in an environment isolated from other applications. Because it is forced to perform any transactions through the system, the system can guarantee safety. In no case should the developer access resources or information from the system without using the systems API's (because nobody would be checking the privileges or operational safety).

2.1. System Structure

In eyeOS the functionality of the system and components is divided between JavaScript and PHP. There are a number of functions available on the JavaScript side that simplify application development, including a specific structure for applications that must be used. Similarly, in the PHP running on the server side there are libraries and API's available to work with.

As you can see, applications are divided into two parts; the part that runs on the client (web browser), and the part that runs on a web server. The part that runs on the client draws the user interface using JavaScript. When you need to do some operation, for example reading the database, you call a PHP function on the server side using the provided API.

6 EyeOS Developer Manual, English

2.2. The Database and users Personal Folders

In eyeOS all components are modular, meaning that the eyeOS system consists of a series of components, such as user management. This in turn is divided internally into smaller components, such as the public user manager API, the component that handles a users software, and the component that manages a users data. The latter component, which is responsible for saving and retrieval of a users data, is called a provider. A provider is the piece within a component whose job is to save eyeOS data. This modularisation allows us to program the entire system without worrying about the type of database in the back end. If we want to use a different type of database then we can simply develop a new provider without needing to touch a single line of code in the rest of the component or application. Because of this, when someone asks you where users are stored eyeOS, there is really no clear answer. In fact, everything depends on the provider used. The default is to use a MySQL database, however we could very easily develop a provider for Oracle, or Microsoft SQL Server, or even on a non-relational engine. A users files within the eyeOS system are stored in the servers file system. Later we will thoroughly examine the eyeOS directory structure; the important thing for now is to understand that a users files are not stored in the database.

3. Development Environment
Since eyeOS applications are developed in JavaScript and PHP, any text editor and web browser are enough to begin development. However, a common text editor does not have syntax colouring, indentation or code completion functionality. Although it is possible develop without all this it would not be the ideal environment. Because eyeOS is a web application, it requires a web server, database, and modern web browser to run. A typical setup is for a developer to have a web server installed on their local machine, so that they dont need to upload changes to an external server to test. In a business environment it is typical for development teams to have eyeOS installed on an internal development server so that development can be done in a collaborative way. For the web server where eyeOS will be installed, please read the eyeOS installation manual which details the required and recommended software and how to install eyeOS. As for a web browser, Firefox is recommended because it is free, cross platform, and supports the use of extensions or plugins which add functionality to the 7 EyeOS Developer Manual, English

browser. It also has great respect for web standards and runs JavaScript quickly. Firefox is available from: http://www.mozilla.com/firefox/ To add functionality to Firefox for debugging of code, error reporting, and many other features that are really helpful for web development, you should install the firebug extension from: http://getfirebug.com/ For a code editor, there are plenty of free programs available on the internet. Something like Notepad++, Netbeans, Jedit, etc, will be sufficient.

4. Examination of the components

It has been mentioned that there are PHP APIs available to the applications, in fact there are a number of components on the PHP side, these are the... 1. 2. 3. 4. 5. Kernel Services Libraries Frameworks Bootstrap

4.1. Kernel
The eyeOS kernel is the component that manages the other components. Because eyeOS is a web application, the kernel is not like one in an operating system, but the kernel is the core component that manages the implementation of the remaining components that form the engine of eyeOS. For the developer, the kernel is an invisible component; you do not need to interact with it directly, so its study will not have too much interest.

4.2. Services
Services are components of the system which are completely necessary for the eyeOS system to work and manage its own internal functioning. For example, a component that is responsible for managing users would be a service. A component that responsible for extracting zip files would not because it is not essential for the operation of eyeOS. Most services are discussed separately later and in more depth, but examples include the process manager or the user manager, because both are essential internal components of eyeOS.

8 EyeOS Developer Manual, English

All services have a public API accessible by applications so that they can interact with the system, for example creating a new user through the public API of the Users service.

4.3. Libraries
The libraries are small components of the system that are responsible for providing support and security to the eyeOS system. An example of a library is support for utf8. Because PHP does not currently have total support for utf8, there is a library in eyeOS that adds this support. Libraries are essential to make the system work, but differentiated from services in that they do not manage anything in eyeOS, they are in a lower layer, providing support and security, making sure everything is correct in the environment to run eyeOS.

4.4. Frameworks
The Frameworks are the highest level components in the system, i.e. they are those closer to the applications and further away from the low-level details. A Framework is a nonessential component that adds functionality to eyeOS but not eyeOS operations of its own, for example Manage Users is not a framework because that would be a service. A Framework, for example, would be the component that is responsible for converting Office documents which applications use to other file formats. Another example would be a Framework for extracting ZIP files.

4.5. Bootstrap
The bootstrap is responsible for loading the entire system before any operation takes place. While applications are loaded on demand, i.e. when the user opens them, all the libraries, services and Frameworks are loaded on each request so that every time the user runs an application all components are loaded and available to the code. There is a configuration file in eyeOS/system/conf/bootstrap/boot.xml that determines the order in which things are loaded in the system. The syntax is a series of elements, like so...
<element> <type>library</type> <name>exceptions</name>

9 EyeOS Developer Manual, English

<priority>20</priority> </element>

Within each element there are sub elements that specify the component type, name, and the load priority. The load priority is what determines the order the components are loaded. By default all components have priority 0 and are loaded in alphabetical order. If you want a component loaded before another one, just make the number for its priority greater (10, 20, 30, etc).

So as seen, the developer has a series of layers that run underneath the program and protect them from the low-level details such as PHP version or the modules installed. The application can then focus on functionality and business logic.

5. Directory Structure
It is important to know the structure of the system so that you can locate configuration files and other components. If you look at the files that make up eyeOS, you will see that in the first level we have only index.php, settings.php and a directory called eyeOS. Settings.php is a configuration file. Within it are defined a number of constants that can be changed to affect the behaviour of eyeOS. For example the connector to the database is configured here, as well as many other things. In the installation manual instructions are given for modifying this file. Index.php is the file that communicates with all of the eyeOS system. Whenever a request is made to eyeOS either to run an application, or to perform any action, it is through this file. The eyeOS directory, known in slang as eyeroot or root, contains the entire eyeOS structure, including all a users data. Within this directory is a file called 10 EyeOS Developer Manual, English

.htaccess with a rule deny from all inside, this is to make it impossible to visit this directory from a browser. Only index.php has access to the files within the eyeOS root directory. In the eyeOS directory there is the following directory tree... apps/ extern/ extras/ system/ tests/ users/ workgroups/ apps/ In apps are the applications that run on the eyeOS desktop or make up the desktop itself. Each application has its own separate directory, for example the calculator application is in eyeos/apps/calculator. extern/ Because only the index.php file is accessible from the outside, eyeOS must have some way to make the JavaScript files, CSS, images, etc, available to the browser so that it can load them. This is what the extern directory is for. All resources that need to be accessible by the browser must be placed in the extern directory, or a subfolder within it. When index.php receives a request like index.php?extern=some_image.jpg, the contents of some_image.jpg within the extern directory is returned to the browser so that it can be loaded. This is discussed in more depth later. extras/ All scripts and files needed to install or configure eyeOS, but are not necessary for eyeOS work, are in this directory. For example the SQL files to create the database for the first time is in extras. After that they are not used any more. system/ The system directory contains all the system components, discussed earlier. Within the system directory we have /frameworks which contains the Frameworks, bootstrap/ that contains the bootstrap, conf/ containing general system configuration that the administrator can modify, and kernel/ that contains the libraries and the services. tests/

11 EyeOS Developer Manual, English

The tests directory contains unit tests of the system and should be of no interest for application developers. users/ In the users directory there is one sub-directory for each user. This sub-directory contains the users files including documents and settings types of files. For example, the directory for a user called JoeyBloggs will be eyeos/users/JoeyBloggs. workgroups/ The workgroups directory contains the working groups of users. If a user creates a group called myGroup the directory will be eyeos/workgroups/myGroup.

6. MMAP, Exec, and extern

Before starting to develop applications, within the inner workings of eyeOS there are three concepts that must be understood, and therefore they have a chapter to themselves. MMAP is a service, Extern is a service and exec is a function in JavaScript.

6.1. MMAP
As we have seen in Chapter 5, all requests to eyeOS must pass through index.php, always! This means that index.php performs an action depending on the type of request it receives. You can send index.php GET or POST variables, but make it one or the other. MMAP is the system service responsible for identifying the type of request made and executing a component or another service of eyeOS. MMAP works with a system of plugins; it has a plugin for each type of request it is able to manage. When a request is made to index.php, index.php calls MMAP and MMAP checks all the plugins looking for one who can handle the request. For example, there is a plugin that says if the request does not have anything to get, i.e. the user has visited index.php without any parameters being passed in, then it shows the login screen. There is another plugin which says that if the parameter extern exists, then it reads the contents of the specified file and returns it to the browser. In eyeOS there are other types of requests, for example, when you want to run an application a request to index.php passing the name of the application you want to execute, the checknum (process id PID of the currently running process), and any arguments will be sent. 12 EyeOS Developer Manual, English

The full URL will look something like the following... http://www.mysite.com/index.php? getApplication=calculator&checknum=570515413&args=null MMAP runs the application and collects other types of messages, for example when an applications JavaScript wants to communicate with the applications PHP via AJAX, to perform an action such as reading the database. Most of these requests are invisible, and the developer does not need to understand them to build applications. However, understand that all requests go to index.php, and then MMAP decides what is done with each.

6.2. Exec
Exec is a function available in JavaScript through the eyeOS object. The eyeOS object in JavaScript is used by applications to access basic system functions, for example to run applications. An application can call the exec function at any time, from JavaScript, as follows:
eyeos.execute('myApplication', checknum, args);

The first argument is the name of the application to execute, the second argument is the identifier for the current application process, and the third is for parameters that the application must receive when executed. Note that the args can be specified as null or can be omitted from the function call. So, this request reaches index.php, which passes it to MMAP, which then finds the plugin that can manage the execution of applications. The run application plugin inserts a new process in the user's process table, reads the JavaScript content of the application, and returns it to the browser. The application is then run and displayed on the eyeOS desktop.

7. Structure and function of an application

So far we have seen how the system works and that an application is split into two parts; one file with JavaScript that creates the user interface, and one with PHP containing any required server side processing such as database access. An application is placed within its very own directory within eyeOS/apps/. The directory should have the same name as the application, for example the notepad application is in eyeOS/apps/notepad. Within this directory you will see that there is at least two files; one called notepad.js and another called notepad.php. 13 EyeOS Developer Manual, English

As you probably guessed, the notepad.js file has the JavaScript code to create the user interface, and notepad.php contains the business logic. Within the PHP file are functions that can be called from the JavaScript file via the eyeOS API which uses AJAX. When calling a PHP function the JavaScript has the ability to pass parameters, the system takes care of this. If a PHP function returns data, it returns back to the JavaScript that started the request. All this is done by using the callMessage function which is part of the eyeOS object. The syntax is...
eyeos.callMessage(checknum, 'funtionname', args, function(e) { alert(e); });

Where the first argument is the current application checknum, functionname is the name of the function in the PHP file to call, args are the arguments to be sent to the function, and finally we define a function that is executed when the call ends - this feature is known as callback. In the above example the callback function simply alerts the value returned from the PHP function. The JavaScript and PHP files which make up the application (in our case and notepad.php & notepad.js) must have a concrete structure for the application to work. For notepad.js the minimum required code is as follows...
function notepad_application(checknum, pid, args) { var app = new eyeos.application.notepad(checknum, pid, args); app.drawGUI(); } qx.Class.define('eyeos.application.notepad', { extend: eyeos.system.EyeApplication, construct: function(checknum, pid, args) { arguments.callee.base.call(this, 'notepad', checknum, pid); }, members: { drawGUI: function()

14 EyeOS Developer Manual, English

{ // code to create the GUI is here. } } };

The first block of code defines a function called notepad_application; this function is the entry point in to the application, it is called when the application runs. Below a class representing the application is defined, because it is an eyeOS application it inherits from eyeos.system.EyeApplication. A method called drawGUI is defined and executed from the notepad_application function. drawGUI is where the code to create the Graphical User Interface (GUI) of the application is placed. The minimum bit of code in the PHP file should be...
<?php Abstract class NotepadApplication extends EyeosApplicationExecutable{} ?>

Here we define an abstract class (it cannot be instantiated) called NotepadApplication which extends from EyeosApplicationExecutable. Later in the execmodules chapter, you will see that applications can be extended from that class. If you would like to add a function to your PHP file that the JavaScript can run, place the keywords public and static in front of the function name. The function must be placed within the class definition as follows...
<?php abstract class NotepadApplication extends EyeosApplicationExecutable { public static function myFunction() { return "Hello World"; } } ?>

And now myFunction is a valid function name that can be called using callMessage in the JavaScript part of your application, as seen earlier. Note that no mention of the info.xml file seen in the application directories is made in the original developers manual. This is used to specify the application name, icons, description, author, and other metadata for the application.

15 EyeOS Developer Manual, English

8. Creating our first application

To practice a bit of everything explained, and more, we will develop an application which displays the current date and time from the server when a button called Get server time is clicked. 1. Create a new directory inside the apps directory called servertime. 2. Create a JavaScript file inside the servertime directory called servertime.js 3. Place the following code in to this file...
// Create main function. function servertime_application(checknum, pid, args) { var app = new eyeos.application.servertime(checknum, pid, args); app.drawGUI(); } // Define class for this application. qx.Class.define('eyeos.application.servertime', { extend: eyeos.system.EyeApplication, construct: function(checknum, pid, args) { arguments.callee.base.call(this, 'servertime', checknum, pid); }, members: { drawGUI: function() { // Create the window. var mainWindow = new eyeos.ui.Window(this, tr("Server Time"), 'index.php?extern=/images /16x16/apps/hwinfo.png'); // Set the layout manager the window is to use to Vertical Box. mainWindow.setLayout(new qx.ui.layout.VBox()); // Create label to display the time and add it to the main window. var timeLabel = new qx.ui.basic.Label("Press the button below to see the Server Time."); mainWindow.add(timeLabel); // Create button to call the PHP function to get the time. var aButton = new qx.ui.form.Button("Get Server Time"); // Add listener to do something when the button is clicked. aButton.addListener('click', function() { eyeos.callMessage(this.getChecknum(), 'getTimeFromServer', null, function(theTime) { timeLabel.setValue("The time is : " + theTime); }, this); }, this); // Add the button to the main window. mainWindow.add(aButton); // Set min width and height of the window to stop it being too small. mainWindow.setMinWidth(300);

16 EyeOS Developer Manual, English

mainWindow.setMinHeight(150); mainWindow.setAllowMaximize(false); // Remember to open the window, otherwise nothing will show on the screen. mainWindow.open(); } } });

4. Create a file called servertime.php 5. Within this file place the following code...
<?php abstract class ServertimeApplication extends EyeosApplicationExecutable { public static function getTimeFromServer() { return date('Y-m-d h:i:s'); } } ?>

To run the application within the eyeOS desktop you will need to go to the applications menu/tab along the top of the screen, then select Add Applications, and click the green plus (+) button next to servertime in the list. Once added to your menu of applications you run it by clicking on it. So like explained in the previous chapters, the program is made up of two files, servertime.js and servertime.php. The code in the JavaScript file creates the user interface and contains an event listener to do something when the button is clicked. The PHP file contains the code to get the date and time from the server. The event listener in the JavaScript file uses the callMessage API to get eyeOS to call the getTimeFromServer function in the PHP file and return back the value. This is done without a page refresh by using AJAX. The application code is programmed in JavaScript using a graphics library called qooxdoo (qx for short). Qooxdoo allows you to develop a GUI using JavaScript instead XHTML and CSS. In qooxdoo, you work with Windows, buttons and other elements that are added to the window.

9. Qooxdoo
As we have seen in the previous chapter, qooxdoo is a graphics library to create user interfaces similar to how you would in other desktops by using libraries like Qt, Gtk, or Swing. Qooxdoo is a free software project independent of eyeOS, its website is... http://qooxdoo.org/ 17 EyeOS Developer Manual, English

eyeOS already includes Qooxdoo so the developer does not have to download or add anything. All applications in eyeOS are developed with the qx graphics library. It is essential to read the tutorial or API documentation on qooxdoo, so that you can understand and therefore develop in it. Qooxdoo is completely object oriented and allows you to define classes, do inheritance, and all the typical OO things. The API and other documentation can be found here... http://qooxdoo.org/documentation

9.1. Qooxdoo classes used by eyeOS

Although eyeOS mostly uses the standard Qooxdoo classes, for example qx.ui.button to draw a button, there are some special cases where eyeOS has extended the qooxdoo classes, creating our own with added functionality. For example the eyeos.ui.Window class is an extension of qx.ui.Window. The problem was that as an application developer you would do qx.ui.Window MyWindow = new () and get a window, but that needed to be inserted somewhere because in the architecture of qooxdoo all widgets must be inserted into a parent to be displayed. But what is the parent of a window that appears on the desktop? In fact, its a bit complex. To prevent the developer having to worry about this we created eyeos.ui.Window, which when instantiated and the open method is called, causes the window to automatically be inserted in to the desktop and displayed without requiring the developer to know who is the parent widget in that window. Currently a developer doing normal applications shouldnt worry about any more cases than eyeos.ui.Window because the remaining classes that are extended by eyeOS are for very specific internal operations.

10. Application Modules (execmodules)

We have seen that you can add functions in the PHP of application in the form of static public methods that are called from JavaScript by callMessage. However, there are a number of methods that all applications should have, for example a 'close' function in the PHP that closes the application. It would be a pain to have to remake this function every time you made a completely new application, which is why the applications already have some functions like this in a parent PHP class called EyeosApplicationExecutable. These 18 EyeOS Developer Manual, English

functions can be called from the JavaScript using callMessage, just like any other function defined by the developer. This in effect means that applications now have a set of PHP functions available to be executed by them, although the developer has not defined any in the PHP of the application itself. The default functions that are in eyeOS are located in eyeos/system/Frameworks/Applications/ Executables/EyeosModuIes/ For example, if you open eyeos/system/Frameworks/Applications/Executables/EyeosModules/ ContactsExecModule.php, inside you will find a series of functions that are available to be executed by callMessage in your application. For example:
public static function getAllContacts($params)

If you wanted to run it from the JavaScript in your program then you would write the following...
eyeos.callMessage(checknum, '__Contacts_getAllContacts', params, function ());

callMessage is just like a normal, but for the name of PHP function to run, because it is in the ContactsExecModule, you must include the name of the package before the function name. The package name must have 2 underscores in front of it and one after it (i.e. __Contacts_). Many applications use these functions to avoid having duplicate local copies of the exact same code.

11. User Manager

The User Manager (UM) is a service that allows eyeOS applications interact with the eyeOS Users service. Some of its functions include the creation of new users in the system, listing of all users, delete users, etc. Like the other eyeOS services, all calls are monitored to check the permissions of the user running the action, for example a non-administrator user cannot create new users or remove existing ones through calls to UM. For example from PHP we can use UM to see if a user exists or not...
$exists = false;

19 EyeOS Developer Manual, English

try { $MyUManager->getUserByName ($username); $exists = true; } catch (EyeNoSuchUserException $ e) {}

If the user does not exist, then when you call getUserByName it will cause an exception, this in turn causes the $exist=true to be skipped so it will remain false. We may also use UM go get a list of all users in the system...
$users = UMManager::getInstance()->getAllUsers();

$users will be populated with an array; every object in the array represents a user in the system, for example to get the name of the first user, you could do...
$username = $users[0]->getName();

12. Proc Manager

The Process Manager or Proc Manager is an eyeOS service that provides an API to applications so they can run applications, list the processes, close processes, etc. A user can only list the processes belonging to their session and not to the session of another user. Proc Manager has a method to obtain the current process, so that applications can call their own process and manipulate it, for instance close itself. The user privileges are associated with each process, so that a user may have many applications running with different privileges, such as in a traditional operating system. If an application wants to get who the current user is, it must use a proc manager to get the current process, and then from there extract the privileges of the process and the user, for example...
$currentUser = ProcManager::getInstance()->getCurrentProcess()->getLoginContext()-> getEyeosUser();

In this way, to consult the process manager, a developer calls the current process, and then asks for the LoginContext, which is the object that contains the privileges of the user associated with that process.

20 EyeOS Developer Manual, English

Although it may seem far-fetched, this way of working allows us to do advanced operations, like creating applications that always run with super user privileges, or with minimal privileges. An application can get a list of processes by consulting with the proc manager, for example...
$processes = ProcManager::getInstance()->getProcessesTable();

You will get an array of all the processes that belong to the user. Each object within that array contains the information of the running process, for example you could get the name of first process by writing...
$procName = $process[0]->getName();

13. File System Interface

When developing an application, there are different ways to access a file through native PHP functions. Most developers have worked with well known PHP file functions such as, fopen, readfile, file_get_contents. These functions may work differently depending on the environment the PHP code is running on. For example in the official PHP documentation there is a notice which warns that Microsoft IIS returns a "SSL: Fatal Protocol Error" and it is explained that the developer is responsible for detecting and suppressing this warning. The problem of working with files is that you have to take into account the environment and operating system. In particular there is the problem of how to guarantee a level of security for files, such as allowing only eyeOS users who have the correct permissions access to a file, and allowing reading or writing depending on whether the particular user has read or write permissions. The eyeOS development environment provides a layer of abstraction, called the FSI (File System Interface), which is responsible taking care of the details for the developer, including properly managing files to ensure that all operations on the file system happen under the supervision of the security service. Another layer of abstraction, that you will see later, is able to manage permissions of files and chooses to allow or disallow a particular operation. The FSI provides an API for developers so the developer is does not have to deal with the problems of security and consistency. It is also capable of working with different types of files depending on your URL scheme (i.e. ftp:// or http://).

21 EyeOS Developer Manual, English

For example, a path like home://~JoeyBloggs/Images/image.jpg will translated as /var/www/eyeOS/ users/JoeyBloggs/files/Images/image.jpg, where /var/www/eyeOS is the path where eyeOS is installed and JoeyBloggs is the eyeOS user. Through this system the FSI is able to read and write files that are physically on the server hard disk, on an FTP server, in a shared folder, etc, through different protocols. One of the main functions of the FSI is GetFile which takes a path as parameter and returns, after translating the URL scheme and checking permissions, an object of type EyeFile. For example if you want to access a file whose path is home://~JoeyBloggs/Images/image.jpg the syntax is...
$file = FSI::getFile("home://~JoeyBloggs/Images/image.jpg");

The API is responsible for translating the URL home:// correctly to get the actual path of this file and verify the permissions, for example does the current user who is not the owner of this file have read permissions? If the file exists and if permissions are good, the GetFile function returns an Object for the developer to work with. For example if you want to know whether the object $file is a directory, the syntax is...
$file->isDirectory();

To delete a file, you would do the following...

$file->delete(true);

In conclusion, the FSI is one of the most important eyeOS services, and developers should always access files through this API so that it is the system who handles all the details.

14. Security Manager

All components of eyeOS that conduct operations on data or system information or access resources check the privileges of the user who executed the process before any operation takes place. The privileges are checked against a set of rules, ACL style, which determine whether the user can perform that action or not. The eyeOS component responsible for conducting these checks is the Security Manager. From a programmer's point of view the Security Manager is not much interest, however it is important to understand it in order to understand that eyeOS denies

22 EyeOS Developer Manual, English

certain operations, or to modify the system to do things that are normally not permitted. The rules of the Security Manager are in XML format within the file eyeOS/system/conf/services/ security/SecurityManager.xml. These are a set of Policies and within are a set of handlers. A policy is a rule applied to an object type, i.e. a class. Normally a developer uses classes to access system resources, and the security manager is used to specify rules about these classes for example the objects that represent a file, or the objects that represent a process. The best way to understand a policy is to first study what appears in file...
<policy objectClass="EyeUserFile">

This policy applies when somebody tries to manipulate an object of the type eyeUserFile. This object is used when accessing a file belonging to a user through FSI::getFile. It is important to realise that handlers are processed from top to bottom, starting with the first then executing though to the last. The 'flag' parameter of each handler specifies whether to continue evaluating handlers or not. The first handler (in the policy shown above) is...
<handler class="SystemGroupSecurityHandler" flag="sufficient"> <param name="groups" value="admin" /> </handler>

This handler specifies that if the user in the group 'admin' (note the <param> there within the handler), then this is already 'Sufficient' and it is no longer necessary check anything else, the user can access the file. The next handler of this policy is...
<handler class="SystemGroupSecurityHandler" flag="requisite"> <param name="groups" value="vfs" /> </handler>

This handler checks whether the user belongs to group 'vfs', the flag requisite indicates that if the user does belong to the group then they do have access, but the security manager continues assessing the other handlers. Then there is...
<handler class="ShareableObjectSecurityHandler" flag="Sufficient" />

ShareableObjectsSecurityHandler is called with the flag Sufficient which means if the file is a shared file then access is granted. And finally... 23 EyeOS Developer Manual, English

<handler class="EyeosFileSecurityHandler" flag="required" />

EyeosFileSecurityHandler is a basic handler which checks if the file belongs to the user, so if they can access it (users can always access their own files). By specifying required, if this rule is met the user will be allowed access, but the other rules will continue to be evaluated (although there is actually no more within this policy). So to summarise, with these handlers this policy permits you to access the file if you are an admin, if the file is shared, or if the file is yours. If the file is not shared, you are not an admin, and the file is not yours, then you must be in the group vfs to access it, otherwise access is denied. The handlers which are called from inside this xml file are defined in eyeOS/system/kernel/services/ Security/implementations/handlers/. Anyone can create a new handler and call it from inside the SecurityManager.xml file.

15. Metadata
There are many cases where you might need to associate data with an object and then be able to retrieve that data later. For example if you have an EyeUserFile object obtained by FSI::getFile and you want to add a rating and then retrieve this rating again when you use getFile. This type of associated information is called metadata. eyeOS provides a simplified API which allows you to associate key-value pairs to an instance of a class so that next time you have this instance you can retrieve that information. This is used internally for a user's personal data, etc. A basic example to get the metadata associated with a user is...
$user = UMManager::getInstance()->getUserById($userId);

Where $userId is the id of the user in the system. With this call to UM an object of type eyeUser will be obtained which represents the user with that id. Now you can get the metadata associated with this user object like so...
$settings = MetaManager::getInstance()->retrieveMeta($user);

In $settings will be an object of the type metadataInformation which has a get and set method. We get a particular item of metadata as follows...
$firstName = $settings->get('eyeos.user.firstname');

This obtains the first name of the user. 24 EyeOS Developer Manual, English

16. Conversion of office documents

The document conversion API allows a developer to easily convert office documents between different formats. For example converting an ODS, XLS, ODT, DOC, etc, from one to the other or to XHTML. One of the main uses of the converter is to convert Microsoft Office Documents or OpenOffice format documents to XHTML so they can be displayed by the browser without installing any plugin. One of the steps in the eyeOS installation manual is to install OpenOffice on the server where eyeOS is running. The API for conversion of documents is connected to this and asks OpenOffice to do the conversion. The office document converter only needs two parameters; the file to convert and what it is to be converted to. It returns a path to a temporary file which is in the desired format; this temporary file can be copied to another site or simply displayed on screen. One example...
$myConverter = new Converter(); $path = $myConverter->Convert($filePath, 'HTML(StarWriter)');

It does not matter if $filePath is a path to a doc, odt, xls, or whatever file; the converter simply connects to OpenOffice and this makes the conversion. The office document converter, like the rest of the eyeOS components, uses the security manager to check for privileges to read the file you are trying to convert. The time it takes to convert depends on the speed server processing, and of course the size of the file.

17. Dbus
Dbus is a technology available on the JavaScript side of applications; it provides a channel of communication common to all applications where any application can send a message and any application can read it. Its main mission is the communication between JavaScript applications. For example, when the File Uploader (to upload a file to a directory) is finished, it sends a dbus message by reporting that the file has been created so that if there are any open file managers looking in that directory they know to update and display the new file. This technology is used for many things internally within the eyeOS desktop. 25 EyeOS Developer Manual, English

The architecture is based on events so that if you want to send a new message to dbus, simply send it, and if you want to receive dbus events, add a dbus listener and a callback (to be executed when the message is received) to your application. To prevent overloading, all messages in dbus have a 'type' which is like a label that classifies them. When listening to the dbus messages, do not listen for all the messages, just listen for the types that you are interested in. Here is an example of the code the File Uploader uses to send a dbus message...
var bus = eyeos.messageBus.getInstance(); bus.send('upload', 'uploadFinished');

First get an instance of the message bus and then send the uploadFinished message with the type of upload. It will only trigger a listener who is looking for the type upload. This dbus message can be captured like so...
bus.addListener('eyeos_upload_uploadFinished', function () { alert ('new message'); }, this);

18. NetSync, real time

Because eyeOS can be used simultaneously on the same server by multiple users, users can send invitations of friendship (among many other things) to each other. eyeOS has a mechanism so that when a user performs an action, other users can be notified in real time (without having to refresh the page). The HTTP protocol is a non-persistent connection; the client connects to the server, makes requests, and then disconnects. The problem is that if a user connects and makes a request which affects another user, the other user may not be notified (for instance visually) until that user makes another request to the server. This usually tends not to be until refresh of the page, which is rare because eyeOS uses AJAX. Some websites have developed a mechanism by which an AJAX request runs steadily from time to time, asking if there pending notifications. The problem with this method (known as the HTTP polling) is that it is resource intensive on the server, swamping it with useless requests, and consuming much bandwidth. eyeOS uses a far more advanced system to make notifications real time. First, on the server a messages queue is installed called ActiveMQ. This is a daemon that can 26 EyeOS Developer Manual, English

leave messages in a queue and anyone who is subscribed to this queue will receive the messages. For a browser to communicate with this queue service, a Proxy (Kaazing) is used which translates the browser's http requests to the protocol that ActiveMQ can understand. To avoid having to be making regular requests to this proxy asking ActiveMQ if there are any messages, ActiveMQ simulates a persistent connection through this proxy using an HTTP request that never ends, which is how we take the messages. By using this technology eyeOS gives the developer a simplified mechanism, called NetSync, to send a message to other Dbus users, so that other users who are running Dbus listeners will receive the message in real time. The API for Dbus we have already seen, so you only need to see how to use NetSync send a message to another user.
var netSync = eyeos.netSync.NetSync.getInstance(); var message = new eyeos.netSync.Message( { type: 'Playground' name: 'test', data: { test1: 'test', test2: 'test2' }, to: 'eyeID_EyeosUser_root' }); netSync.send(message);

For this example, we first obtain an instance of the netSync object and then create a message that is eventually sent via NetSync. The message object contains within it the following information: The 'type', the name, the data associated with the message, and who it is addressed to. The user for whom the message is to be sent to is specified using their user id, not their username.

19. Database connection

Internally eyeOS works with the default MySQL database engine, but using an abstraction layer so that any standard SQL database can be worked with, if desired.

27 EyeOS Developer Manual, English

If an application also needs to connect to the database, for example to create its own tables and store information in them etc, you have two ways of doing so... The first is through a normal connection to the database, eyeOS provides a range of methods to get a connection to the database at any time. The second way is to use Generic DAO; an advanced eyeOS API that allows the developer to use the table like an object and not worry about writing SQL.

19.1. Generic DAO

Generic DAO is an API that is used internally throughout the system. Developers can also use it in their applications. For Generic DAO, Transfer Objects are used. A Transfer Object is a class that represents a table within the database. For example suppose there is a table called users in the database with two fields, username and password, the Transfer Object for this table would be...
class usersTO { private $username; private $password; public function getPassword() { return $this->password; } public function setPassword($password) { $this->password = $password; } public function getUserName() { return $this->username; } public function setUserName($username) { $this->username = $username; } }

As you can see, the userTO class has an attribute for each field in the table, and a get and set method for each attribute. In this way, the usersTO class represents the users table and Generic DAO can use this class to manage the users table.

28 EyeOS Developer Manual, English

To work with this Transfer Object, Generic DAO uses the Transfer Object as if were the table, for example if you wanted to create a new user, you simply specify the values for the attributes in the Transfer Object (which in this case is username and password) and then call the Generic DAO create method. To obtain an instance of GenericDAO we must ask the storage manager as in this example...
$this->dao = StorageManager::getInstance()->getHandler('SQL/EyeosDAO', array ('prefix' => 'mail')); $usersTO = new usersTO(); $usersTO->setUserName('john'); $usersTO->setPassword ('12345'); $this->dao->create($usersTO);

Generic DAO extracts the Table name from the Transfer Object class, removing the TO to get just users. Then it generates an SQL statement which will incorporate all the attributes and executes it on the database. Generic DAO provides a method to read existing entries in the table and return a Transfer Object filled with data. First create a new Transfer Object, fill only the class attribute which matches the field in the table that is the key primary, and then execute the read method. Assuming that the primary key field is the user (username), you would do it like this...
$this->dao = StorageManager::getInstance()->getHandler('SQL / EyeosDAO', array ('prefix' => 'mail')); $usersTO = new usersTO(); $usersTO->setUserName('john'); $usersTO = $this->dao->read($usersTO);

And at the end of this $usersTO will be filled with the other attributes obtained from the database, in this case password. In addition Generic DAO allows for all table records to be read in to a Transfer Objects array using the readAll method like so...
$this->dao = StorageManager::getInstance()->getHandler('SQL / EyeosDAO', array ('prefix' => 'mail')); $usersTO = new usersTO(); $ALLUSERS = $this->dao->readAll($usersTO);

You can delete a user from the table by filling $usersTO with only the id of the user, in this case username, then calling the delete method instead of read. To update the information for a user you make a read, change something such as the password, and then call the update method using the modified Transfer Object.

29 EyeOS Developer Manual, English

The goal of Generic DAO is to hide the SQL from developers so that they can focus on business logic.

19.2. Direct connection

For SQL statements directly into the database without using Transfer Objects, the Generic DAO send method is used. This is for when you wish to do more complex queries, for example a query that contains a sub query.
$this->dao = StorageManager:: getInstance ()->getHandler('SQL / EyeosDAO', array ('prefix' => 'mail')); $this->dao->send('SQL HERE');

Thus, any application can execute SQL directly in the database. Using the send method works the same way as the native PHP function mysql_query, the only difference is that Generic DAO, which has the parameters to connect to the database, is used to perform the mysql_connect.

20. References and further reading

To begin developing an application it is vital to stay in touch with the community to get help and advice, you can view and write on the forum at http://forums.eyeos.org. Due to the ever-growing state of eyeOS, you may need to look directly at the code of some components to understand how they work and the attributes, methods, and options and limitations that are there. EyeOS is not to be understood as a closed black box, but as a set of libraries that you can view the code of to understand, improve, extend etc. In order to develop a successful application, is also essential to have a good understanding of qooxdoo, not just what it is but how to use it. This will require you to read the API and other documentation found at http://qooxdoo.org/documentation. You may also find it useful to examine the code of existing eyeOS applications - Calculator and Login are the simplest. You may also find the pages at the following 3 links very helpful for learning qooxdoo... http://demo.qooxdoo.org/1.2.x/playground/# http://demo.qooxdoo.org/1.2.x/showcase/# http://manual.qooxdoo.org/1.2/pages/widget.html

30 EyeOS Developer Manual, English