version 0.1.

0

- 2 -
Index

1. Introduction
1.1 What is eyeOS
1.2 eyeOS basic structure
1.3 The Kernel
1.4 System Services
1.5 Libraries
1.6 eyeOS code organization
1.7 Settings.php
1.8 Versions
2. Basic Services
2.1 VFS, Virtual File System
2.2 UM, User Manager
2.3 MMAP, Message Mapping
2.4 PROC, Process Manager
2.5 EYEX, eyeOS X System
2.6 EXTERN, external files Manager
2.7 LOG, Logging System
2.8 SEC, Security Manager
3. System Libraries
3.1 errorCodes
3.2 eyeXML
3.3 i18n
3.4 eyeWidgets
4. How an application works
4.1 Preparing the environment
4.2 Downloading the code
4.3 Structure of an application
4.4 Initializind and ending of an application

- 3 -
4.5 Events
4.6 Extern
4.7 Explained example
5. The eyeOS Toolkit in a nutshell
5.1 How the Toolkit works
5.2 The JavaScript side and the PHP side
5.3 Messages
5.4 Serialization
5.5 Friends
6. Groups
7. Aliases
8. Listener Service Calls
9. Full Screen
10. Message Tables
11. Important eyeOS Libraries
11.1 eyeSockets
11.2 eyeURL
11.3 SimpleZip
11.4 eyePear
12. Extras Directory
13. How sessions work with eyeSessions
14. Sharing your work with the eyeOS Community
15. About this manual
15.1 License
15.2 Authors and contributors

- 4 -
1. Introduction
This document is an introduction to the application development for the eyeOS web Operating
System. Some PHP knowledge is required to read this document, and it is not necessary to have
experience programming with CSS, JavaScript or XHTML, although knowing these technologies will
help you understand better eyeOS and its internal functioning.
1.1 What is eyeOS
From a technical point of view, eyeOS (http://www.eyeos.org) is a platform for web applications,
created with the idea to make easy the application development.
There are currently a lot of web-related technologies, such as PHP, XHTML, CSS and JavaScript, so
it is required to master a lot of languages and understanding numerous concepts to be able to
create web applications. In addition, every web browser has a different interpretation of the code
and every PHP version and configuration works slightly different from the others.
eyeOS intends to cover those and other problems derived from the web development, offering the
programmers a homogeneous platform to develop their web applications, using only PHP code and
leaving to the system the resource management, the communication with the browser, the
security, etc.
1.2 eyeOS basic structure
Before studying the eyeOS components, we must know its basic structure. The platform is created
over a client-server architecture, in which eyeOS is the server, and the client is usually a web
browser.





Note: Unless specifying the contrary, this manual will assume the client is a web browser.
1.3 The Kernel
The first step we must take to know eyeOS is the study of its kernel.
Since eyeOS is a microkernel-based platform, the kernel is only thought to unify the system
services. In other words, eyeOS has many services for specific tasks, and the kernel is responsible
for its communication and location.



Server

Client

- 5 -






With this architecture, applications don't need to specify how to invoke a service, they just need to
know its name, and the kernel does the rest of the job.
1.4 System Services
The Services in eyeOS perform low-level tasks. For example, the applications do not manipulate
files directly: instead of that, they use a service designed for that purpose. Thus, security is
guaranteed since the services apply restrictions to the applications' requests.
The only form to communicate with a service is the kernel, as stated above in section 1.2. To do
that, the service() function (defined in system/kernel/kernel.eyecode) must be used.
service() takes 3 arguments:
service( string $servicename , string $functionName [, array $params] );

The first argument specifies the name of the service to call. In eyeOS there are eight services, and
they will be studied later.
The second argument corresponds to the function to call, given that a service is a collection of
functions and we must specify what function we want to use. For example, if we are using the
filesystem manager service, we need to specify if we want to copy, delete or create a file.
The third and last argument is an array containing the parameters passed to the function. For
example, if we are using the filesystem manager service, we need to tell it which file we want to
delete.
An example of a call would be:
service('vfs','delete',array('file.txt'));
This code would call the vfs service (the filesystem manager) to delete a file named file.txt.
1.5 Libraries
The libraries in eyeOS are similar to the services. They too are called using the kernel, but unlike
the services, they do not handle low level tasks (such as files, users or processes), instead they
make the development of applications easier, making available sets of functions the applications
might need.
Kernel

Applications

Services

- 6 -
eyeOS includes lots of libraries (that will be studied later). Libraries can be used by any application.
For example:
eyeZip – allows to work with ZIP files (extract, compress...)
eyeURL – allows to request URLs
eyeXML – allows to work with XML files (read, write...)
The way to use a library is very similar to that of a service, being the only difference the fact that
the reqLib() function is used instead of service(). reqLib() takes the same arguments as service():
reqLib( string $libName , string $functionName [, array $params] );
The first argument is the name of the library to use, such as eyeZip.
The second argument corresponds to the function to use, such as extractZip (of eyeZip).
The third and last argument are the parameters passed to the called function.
An example showing the use of this function to extract a ZIP file to a directory using the eyeZip
library would be:
reqLib('eyeZip','extractZip',array('file.zip','Documents/'));

1.6 eyeOS code organization
It is important to know how eyeOS is organized to be able to develop applications for. In eyeOS
everything has its right place to be put on.
The eyeOS directory tree can be summarized as:

eyeOS/accounts – Information and credentials about the users. See chapter 2.2.
eyeOS/apps/ - Directory where the applications are located. See chapter 4.
eyeOS/extern/ - Files visible from the exterior, such as CSS stylesheets, images, etc. See chapter
2.6.
eyeOS/extras/ - Extra files. See chapter 12.
eyeOS/groups/ - Groups directories. See chapter 6.
eyeOS/i18n/ - I18n and eyeOS translation directory. See chapter 3.3.
eyeOS/log/ - System logs directory. See chapter 2.7.
eyeOS/system/ - System directory. Contains the services, libraries, kernel and global
configurations.
eyeOS/tmp/ - Directory where files are stored temporarily.
eyeOS/users/ - Users' directory where all their documents and files are stored. See chapter 2.2.
The code of eyeOS is stored in files with the .eyecode extension (for example: kernel.eyecode)

- 7 -
which contain normal PHP code, usually using the eyeOS Toolkit classes and functions.
1.7 Settings.php
One of the most important files that defines the eyeOS functioning is the settings.php file (located
in the eyeOS root, along with the index.php file). In this file constants are defined and later used in
all the eyeOS code. For example:
define('ROOTUSER','root');

Defines the name of the root user (the administrator of the system).
All the settings of this file will be studied later in this manual.
1.8 Versions
eyeOS releases a new version of the platform every 2 months for normal versions, and every 3
months for special versions.
The version numbers always use 4 digits. For example:
1.5.0.1
Where the first number (1) indicates the major eyeOS version, the second number (5) indicates the
minor version, the third number (0) indicates the sub-version and the last number (1) indicates the
revision.
Thus, eyeOS 1.5.0.1 indicates that the eyeOS is type 1 serie (the previous eyeOS belonged to the 0
series), version 5 (the fifth version of the eyeOS 1 series), sub-version 0, revision 1, which means
that some bugs have been fixed from the 1.5.0.0 version.
When a new eyeOS version is released, it may contain some errors. Those errors are fixed and a
new version is released, changing only the last version number and adding no new features, only
patches to fix bugs.
An example of this would be the 1.5.0.6 version, a fixed (patched) version of eyeOS series 1,
version 5.

- 8 -
2. Basic services
As explained in chapter 1.3 there are 8 services in eyeOS, which are:
• extern
• eyeX
• log
• mmap
• proc
• sec
• um
• vfs

They are located in the eyeOS/system/services/ directory.
2.1 VFS, Virtual File System
One of the most important services in eyeOS is VFS, which is the responsible of providing
functions to work with files and directories.
Absolutely no operation with files must be performed directly using PHP functions such as fopen()
and unlink(). The VFS service must always be used in these operations.
VFS guarantees that a user is unable to read or edit another user's files. If an application executed
by a user requests VFS to read a file over which the user does not have enough permissions, VFS
will return false and will activate the error code VFS_INSUFFICIENT_PERMISSIONS (read chapter
3.1).
Thus, it's VFS that ensures the security and not the applications. The applications do not need to
worry whether the user has enough permissions on a file.
The VFS internal work is done in a modular way. This means that the VFS functioning can be
modified using new modules. The default module is the virtual module, although it can be
specified which module to use changing the value of the VFS_MODULE parameter on the
settings.php file.
The virtual module uses two files for every file the user creates. One file is used to store the
content of the file and other file is used to store information about it using the XML format.
In addition, the virtual module concatenates a 32 character length random string to every file
name, making it impossible to guess from the outside the name of a file.
For example, if we call VFS with the virtual module to create a file:
seivice('vfs','cieate',aiiay('file.txt')):
The system will actually create two files, being one called:
file.txt_[RANDOM_STRING].eyeFile, which will store the content of the new file.

- 9 -
And another called:
file.txt_[RANDOM_STRING].eyeInfo, which will contain information about the new file, such as its
author, its real name (file.txt) and the creation date.
VFS always manages these low-level tasks. For example, if we want to delete the file called file.txt
we just need to call VFS once and both files will be deleted:
seivice('vfs','uelete',aiiay('file.txt')):
If we want to open the file to read it:
$fp = seivice('vfs','open',aiiay('file.txt','i')):
and from here we can use the file resource $fp using fread(), fwrite() and fclose() from PHP. The
opening modes of VFS open are the same as the fopen() function used in PHP.
Apart from this method using pairs of files, the virtual module has methods to deal with normal
files which do not use the eyeInfo and eyeFile pairs. These methods are called real methods.
The real methods work exactly like the virtual ones, but their name is preceded with the prefix
real_. Let's see an example:
seivice('vfs','ieal_cieate',aiiay('file.txt')):
This code would generate a file called file.txt in the system. It would not create an eyeFile and
eyeInfo file.
The reason there exist real methods (real_open, real_create, real_delete, etc) and virtual methods
(open, create, delete) is that a user's files are stored as virtual files to control their creation date,
their author and other parameters, while the system files, such as a user's configurations, are real
files.
As stated in chapter 2.2, every user has a home directory to work in. Inside every home directory
there are:
• conf/ - the configuration files are stored here as real files with XML format.
• files/ - the virtual files (using eyeInfo and eyeFile) are stored here, and are visible to
the user from the File Manager.
The form to decide whether to use a virtual or a real method is as simple as thinking: “Do I need to
work with a user's file or with a configuration file?”
One detail to bear in mind is that the real functions do not have the same restrictions as the virtual
ones.
The virtual functions have permissions to read and write the files in the files/ directory of a user's
home, and to create files in the groups' directories where the user belongs (see chapter 6). Inside a
group's directory, the virtual functions can only edit and delete files that belong to the user.
The real functions have permissions to create and edit files everywhere in a user's home (including

- 10 -
files/, conf/, etc), but they have no read nor write permissions on the groups's folders.
These restrictions exist for security reasons. It would be dangerous that real files of groups could
be altered, so they can only be accessed with virtual functions.
2.2 UM, User Manager
The UM service manages the users in the system and provides the methods necessary for
registering, logging in, obtaining the path to a user's home, etc.
One important characteristic is that UM provides a global variable accessible at any place, called
$currentUser, which contains the username of the current user. For example:
global $currentUser;
This way, applications can know which user executes them.
Furthermore, UM provides indispensable methods to build applications, like getCurrentUserDir(),
which returns the path to the current user's home directory. For example:
$path = seivice('um','getCuiient0seiBii'):
Knowing the path to the home of the user that executed the application is useful to save files. Let's
imagine, for example, we are creating a text editor and we want to save what the user wrote (using
methods explained later) to a file called 'myFile.txt' inside of the “Documents” folder of the user's
home:
$path = seivice('um','getCuiient0seiBii'): ¡¡We get the usei's home uii
$path .= 'files¡': ¡¡We auu files¡ since usei's files aie in this foluei
$path .= 'Bocumentois¡myFile.txt': ¡¡We auu the iest of the path to the file
seivice('vfs','cieate',aiiay($path)):

With this code, we have created the empty file. For that process, we needed to obtain the path to
the user's home directory to create the file.
2.3 MMAP Message Mapping
Before introducing MMAP, we must first get to know the communication between the client and
the server.
The eyeOS applications reside in the server, storing and processing the data in it, being for the
client the medium to visualize and interact with the application. For example, the client is
responsible of displaying a window, or sending a message to the server indicating a button has
been clicked.
The communication between the client and the server is done via messages. A message is a
petition made by the client to the server, sending or asking certain information.
Now that we know what a message is, we can move on and explain how MMAP takes part in this
process.

- 11 -
MMAP is responsible for routing every received message in the server to the applications. A good
comparison could be made with a postal system. When a mail arrives to the post central, it is
classified according to its addressee, and finally it is delivered by the postman. MMAP would do
the parts of organizing and delivery, since it classifies and transmits the message to the
applications.







As a final note, you must know that MMAP is an automated service: it does not require any
interaction with the developer at all. Nevertheless, it is important to know how to receive its
messages, and that is explained in chapter 4.
2.4 PROC
PROC is responsible for the process managing, and provides methods to launch, end, list
processes, etc.
When an application is launched with PROC, two very important variables for the application
development are defined: myPid and checknum.
myPid is a unique 4 characters length numerical value that identifies every process and
checknum, just like myPid, is a unique number, although it is 8 characters length and identifies
every process in the client-server communication.
In this application, application “app1” executes the application “app2” and then it terminates itself.
global $myPiu: ¡¡Piu of application "app1"
$piu = $myPiu: ¡¡We stoie the piu in anothei vaiiable
seivice('pioc','launch',aiiay('app2'): ¡¡We call launch, inuicating the name of the application to open
seivice('pioc','close',aiiay($piu): ¡¡We call close inuicating the piu of app1

PROC provides a wide variety of process managing methods, not limited to launching or closing
applications. For example, the findPidByName() function, locates a given process with specified pid
and returns the name of its application name.
2.5 eyeX
As said in chapter 2.3, the mmap service manages the messages coming from the client. All
messages have a response in XML format, which is interpreted by the browser.
Client
App A
Messages
App B
App C
MMAP
Application A
Application B
Application C

- 12 -
The response XML contains basic orders to modify the interface of the client. For example, we
create a button that creates a new window when it is clicked:






In the first case, the message goes from the browser to the server. In the second case, the
response to the message includes the orders for the browser to create a new window.
The eyeX service is the responsible for managing the response XML sent by the server. The
applications request eyeX basic operations, such as creating windows or showing an image, and it
is eyeX that transforms those orders in an XML message.
For example, we can use eyeX to create a message box in the browser, just calling eyeX with
service():
seivice('eyeX','messageBox',aiiay('content'=>'This is a message')):
2.6 Extern, external file manage
The extein seivice allows the client to uownloau files fiom the seivei. Those files must be locateu
insiue the extein¡ uiiectoiy. (see chaptei 1.6).
Extein allows to cieate 0RLs accessible fiom the outsiue, allowing to host images, CSS files, IavaSciipt
files, etc.
Its woiking is veiy simple: if we want to get a file calleu style.css insiue of a uiiectoiy calleu 'test'
locateu in eye0S¡extein¡ we just shoulu use the 0RL:
inuex.php.extein=test¡style.css

This service exists to allow the developers to use images, stylesheets and other files in their
applications, without worrying about the eyeOS/ directory is not visible from the outside.
2.7 Log
Log does not require any interaction with the developer. It works autonomously registering the
system's activity to log files, annotating the time and user of every action. Its presence does not
reverberate at all at the time of building applications.

Browser
a button is clicked
Server
Server
creates a new window
Browser

- 13 -
2.8 Sec
Sec is another autonomous system service, although it reverberates on the developers, unlike the
log service.
Sec is responsible of making eyeOS run in a secure environment. To do that, it disables PHP's
magic_quotes and register_globals when initiating.
Thus it's not necessary to worry whether these options are enabled or not: you will always see
them disabled.

- 14 -
3. System libraries
As we saw in chapter 1.5, the libraries are collections of functions we can use from our
applications to make the development easier.
In eyeOS there are libraries for a wide range of tasks, although there are some very important
ones, such as eyeWidgets, eyeXML, i18n and errorCodes.
In this chapter we will study how those libraries work and how we can use them in our
applications.
3.1 errorCodes
When parts of our application are delegated to third parts (services, libraries, etc.) it is compulsory
to standarize the error reporting so we can identify the errors ocurred in any moment. The
errorCodes library exists to cover this need, implementing a unified and extensible method to
report errors.
This library provides two functions: setErrorCode and getErrorCode.
setErrorCode() is used to store a value that indicates the type of error (normally represented by a
number).
getErrorCode() retrieves the error previously stored by setErrorcode so that it can be identified.
All system services have values of errors reserved and defined as a constant. Each one of these
value is called an “errorCode”.
Some errorCodes (you can check the documentation pages for all of them):
EYEOS_LOG_BAD_VALUE = -404
EYEOS_LOG_SERVICE_IGNORED = -401
In this example, we can see how the errorCodes library is used to handle a common action:
$path = '¡etc¡shauow': ¡¡File's uiiectoiy
$fp = seivice('vfs','open',aiiay($path)): ¡¡We tiy to access the file
¡¡If vFS ietuins false, we move on to examine which eiioi coue was set
if($fp == false) {
if($fp == vFS_INS0FFICIENT_PERNISSI0NS) {
¡¡We uisplay a message box showing what type of eiioi occuiieu
seivice('eyeX','messageBox',aiiay('content'=>"You uo not have enough peimissions.")):
}elseif($fp == vFS_FILE_N0T_EXISTS){
seivice('eyeX','messageBox',aiiay('content'=>"The file uoes not exist.")):
}else{
seivice('eyeX','messageBox',aiiay('content'=>"An unknown eiioi occuiieu.")):
}
ietuin false:
}

- 15 -
In the example, we are trying to open a file that in Unix systems normally is only accessible by the
administrator, and that in Windows systems it does not exist.
As you can note, in both cases we have a lot of possibilities the file is not accessible, and that is
the reason we use errorCodes to discover the exact type of error and report it.
3.2 eyeXML
The XML format is widely used in eyeOS, so much that it would even be considered one of its
pillars. For example, it is used to store configurations, transport data and messages, among much
other uses. Nevertheless, the use eyeOS gives to XML differs from the usual form, using the arrays
as XMLs, and the XMLs as arrays. To make this model possible, two main functions are used,
called array2xml() and xml2array.
Don't be frightened if it sounds a bit abstract; we provide an example to show how simple it is:
¡¡We have a vaiiable stoiing XNL with infoimation about a usei calleu main, anu we want to ietuin its cieation
uate using eyeXNL's methous
$myXml = "
<eye0sei>
<useiname>main<¡useiname>
<passwoiu>4fSfbauSa866u7a21Sfe91bu477SS689<¡passwoiu>
<email><¡email>
<cieateBate>2u¡u2¡2uu7<¡cieateBate>
<gioup>phpCoueis<¡gioup>
<¡eye0sei>":
¡¡Now, we tiansfoim the XNL to an aiiay using xml2aiiay()
$myAiiay =ieqLib('eyeXNL','xml2aiiay',aiiay($myXml)):
¡¡We only ietuin the value of the fielu cieateBate
ietuin $myAiiay|'eye0sei']|u]|'cieateBate']|u]:
The XML is transformed to the following array:
Array
(
[eyeUser] => Array (
[0] => Array(
[username] => Array(
[0] => main
)
[password] => Array(
[0] => 4f5fba03a86607a215fe91bd47735689
)
[email] => Array(
[0] =>

- 16 -
)
[createDate] => Array(
[0] => 20/02/2007
)
[group] => Array(
[0] => phpCoders
)
)
)
)
eyeXML also provides functions to open and write XML files easily (with the methods getXMLfile
and setXMLfile) and to directly handle XML configuration files (with methods getXMLconfig and
setXMLconfig).
3.3 i18n Internationalization
The internationalization system is integrated in the eyeWidgets library (see chapter 3.4) and it
works almost automatically. Nevertheless, in some occasions it is necessary to add manually the
feature, specially in cases in which the Toolkit is not used such as some special visualization in the
client (for example, the use of methods rawjs and runjs).
To implement the internationalization automatically is as easy as making a call to the translate()
function before sending any text to the client. We need to bear in mind that the text to translate
must be written in English.
$myText = "Bello Woilu!": ¡¡0ui oiiginal text must always be wiitten in English
$myTextTianslateu = ieqLib('i18n','tianslate',aiiay($miTexto)): ¡¡We tianslate the text
$js = "aleit('$myTextTianslateu'):": ¡¡Iavasciipt coue using the tianslateu text
seivice('eyeX','iawjs',aiiay('js'=>$js)): ¡¡We senu the iawjs oiuei with oui Iavasciipt coue
In this example, we see how to translate a given static text. In most occasions this method is
sufficient for most cases, but there may be some situations in which the use of this method could
not be appropiate, such as with dynamic texts. i18n is also capable of translating these kind of
texts. Let's see an example:
$myText = "Bi %s, my piu is %s":¡¡We ieplace with an %s the useiname anu the piu
$tokens = aiiay($cuiient0sei,$myPiu):
$myText = ieqLib('i18n','tianslate',aiiay($myText,$tokens)): ¡¡We tianslate oui text with the tokens
¡¡The iesulting text tianslateu in Spanish woulu be: "Bola ioot, mi piu es 4182"
As the example shows, translating a text with dynamic data is easy: we only have to replace that
data with “%s” and provide the function an array with every dynamic data in it.


- 17 -
3.4 eyeWidgets
The eyeWidgets library provies a quick form of creating graphical interfaces in eyeOS.
This library provides a set of classes used to create and modify visual elements in applications.
Among other uses, it allows to create windows, buttons, images, texts, tables, etc.
For example, creating a new window in our application is as simple as typing:
$myWinuow = new Winuow(aiiay(
'name'=>'Winuow1',
'fathei'=>'eyeApps',
'cent'=>1,
'wiuth'=>6uu,
'height'=>Suu,
'title'=>'Test Winuow'
)):
$myWinuow->show():

This way, with eyeWidgets we can create graphic elements a user can interact with.
eyeWidgets works with eyeX (see chapter 2.5), telling it to append to its response (the response
ultimately sent to the client as XML) the necessary orders to draw windows, buttons, or other
widgets.











From this point of view, eyeOS is a graphical Toolkit, similar to local toolkits such as QT, but with
the difference it works via web.
Application
new Window()
eyeWidgets eyeX
Orders in XML

(see chapter
2.5)
Browser

- 18 -
4.How an application works
4.1 Preparing the environment
All projects must be developed in an adequate environment. If, for example we are developing an
application for GNU/Linux, it is better to use a GNU/Linux environment, otherwise the task would
become quite a bothersome task. Let's see which requirements our environment should have:
• Subversion Client: we will need it to download the latest eyeOS code.
• Apache2 Server: the only server officially supported.
• PHP 5: the required version since eyeOS 1.2 and above.
• PHP Editor: any suitable text editor is valid.
Our ideal environment is a personal preference: not everybody feels comfortable with the same
applications. The eyeOS team uses all the same environment, which we thoroughfully recommend:
• Official Subversion Client: http://subversion.tigris.org
• IDE Eclipse PDT.
• A Unix-like OS: OpenBSD, FreeBSD, GNU/Linux etc.
• Mozilla Firefox 2.X.
o Firebug Extension.
o ANEC (Add n edit cookies) Extension.

4.2 Downloading the code
The eyeOS code is in a Subversion (our Version Control system) server, and it is organized as
follows:
• trunk: contains stable and secure code, and it is the main eyeOS working branch.
• branches:
o unstable: contains applications that do not match the eyeOS quality standard.
• tags: contains the freezed code for each version released.
The SVN server can be found at http://svn.eyeos.org.

4.3 Structure of an application
One important thing you should know to manage in eyeOS is the structure of an application. The
directory and files tree of an application is as follows:
• eyeOS/apps/ -Directory that contains the PHP code of each application
• eyeOS/apps/Application/ -Application's main directory

- 19 -
• eyeOS/apps/Application/apps.eyecode -Initializing and ending code of an application
• eyeOS/apps/Application/events.eyecode -Event reception code
• eyeOS/extern/apps/Application -Main directory for the external resources of an
application
The files and directorios marked in bold are required for an application to work properly.
We will focus to explain the use of every file and directory in the next sections.
4.4 Initializing an ending of an application
The initialization and ending of an application is contained in the apps.eyecode file.
This file contains two functions:
• ApplicationName_run: function called by PROC when launching an application.
• ApplicationName_end: function called by PROC when terminating an application in case it
exists.
The only required function in this file is the _run function. Its use varies enormously depending of
the kind and size of the application. A graphical application normally uses it to initialize the User
Interface, but non-graphical and small applications concentrate all their code in this function.

4.5 Events
An event is described as an interaction by the user with the interface of our application. For
example, when a user clicks a button an event is produced. The generated information of every
event is sent to the server in the form of a message. As we explained above, the responsible part
of treating those messages is the MMAP service.
MMAP is able to deliver every message thanks to the fact that each message contains the
checknum of the addressee application and the name of the event. To deliver the message, MMAP
finds a file named events.eyecode in the directory of the addressee application and tries to call a
function named ApplicationName_on_EventName, passing as an argument the body of the
message. An example of a valid event function would be:
function !"!#$%&'"_on_(!)&*!#!+,!--./!(01.(.2-){
if(!$paiams) {
ietuin false:
}
seivice('eyex','messageBox',aiiay('content'=>'New message ieciveu')):
}
• eyeNotify: name of the application to which the message is addressed.
• reciveNewMessage: name of the event received.
• $params: parameters sent from the client.


- 20 -
4.6 Extern
Using extern in our application is very easy. We only have to place the file we want to access in
extern/apps/ApplicationName/ and then use a URL to the file as stated in chapter 2.6.
The use of extern in an application is quite useful since it allows to load icons, CSS files, images,
etc.
4.7 Explained Example
Now that we know how the files and functions affect an application's working, it is time to see an
example:
apps.eyecode:
¡¡Initializing function that cieateu the inteiface
function eyeBasic_iun($paiams=null) {
¡¡Winuow wiuget
$myWinuow1 = new Winuow(aiiay(
'name' => 'eyeBasic_WNB',
'fathei' => 'eyeApps',
'cent' => 1,
'wiuth' => 2Su,
'height' => 1Su,
'title' => 'Example eyeApp'
)):
¡¡We uiaw the winuow now that it is uefineu
$myWinuow1->show():
¡¡Button wiuget
$myButton1 = new Button(aiiay(
'name'=>'eyeBasic_BTN',
'fathei'=>'eyeBasic_WNB_Content',
'caption'=>'I'm a basic eyeApp. Click me!',
'x'=>4u,
'y'=>8u,
'signal'=>'buttonPiess'
)):
¡¡We uiaw the button
$myButton1->show():
}
¡¡Enuing function: it iemoves the inteiface
function eyeBasic_enu($paiams=null) {
eyeWiugets('unseiialize'):
}
As we can see, the initializing function of the application only creates the interface. It is not time

- 21 -
to explain how the eyeOS Toolkit works right now (that part is covered in chapter 5), however it is
important to notice in the parameter called 'signal' in the button widget.

events.eyecode:
¡¡Function that ieceives the event geneiateu when the button is clickeu
function eyeBasic_on_buttonPiess($paiams="") {
¡¡We show a message inuicating that the button has been piesseu
seivice('eyex','messageBox',aiiay('content'=>'The Button has been piesseu!')):
}
¡¡Function that ieceives the event geneiateu when the winuow is closeu
function eyeBasic_on_Close(){
¡¡We make the application teiminate itself
seivice('pioc','enu'):
}

The event receiver functions have a characteristic syntax as explained earlier, and are always called
by MMAP.
As we can see, the name of the event 'buttonPressed' matches the content of the signal parameter
of the button. The details about the Toolkit will be explained in chapter 5.


- 22 -
5. The eyeOS Toolkit in a nutshell
The Toolkit is the main part of an application in eyeOS. It is the library that helps programmers
managing and creating graphical interfaces.
The basic element of this Toolkit is the window, inside of which other elements are created. All
visual elements of the Toolkit, such as buttons, bars, boxes or windows among other are
designated as widgets.
5.1 How the Toolkit works
Every visual element of an application has a class that represents it: in other words, every widget is
a class.
With this model, adding a widget in our application is as easy as instantiating a class.
All the classes of the Toolkit take as an argument an indexed array when they are instantiated.
This array contains parameters shared in common with other widgets and specific parameters for
each widget.
The common parameters of all widgets are:
name – the name given to the widget, such as 'window1', 'button2', etc. This name will be used to
refer to the widget in the application.
father – the father of the widget. In other words, the widget inside of which this widget is placed.
If, for example we create a window in our application and want to create a button inside the
window, we must indicate the name of the window as the father of the button. The background is
a layer called eyeApps, which is the father of all windows that are not placed inside another
window.
• X – the horizontal coordinate with regard to its father.
• Y – the vertical coordinate with regard to its father.
• Horiz – this flag specifies the form in which the horizontal (X) coordinates are taken. If it is
set to 0 (the default value) the pixels are counted from the left. If set to 1, the pixels are
counted from the right.
• Vert – exactly like Horiz, but with the vertical (Y) coordinates.
The use of horiz and vert is justified: we may want to stick some element to the right or
down border of a window, and those flags eliminate the need to calculate the size of the
window to place the element.
• Cent – this key is used to center widgets. When it is set to 0 (the default value) nothing is
changed. If it is set to 1, it makes the horizontal and vertical coordinates (X and Y,
respectively) given be ignored, and centers the widget at the center of the father. If set to
2, the widget is centered horizontally, and when it is set to 3 it is centered vertically.
Aside from these parameters in the array, each widget has its own specific parameters. We will se

- 23 -
an example using a window widget to see this
$myWindow = new Window(array(
'name'=>'Window1',
'father'=>'eyeApps',
'cent'=>1,
'width'=>600,
'height'=>500,
'title'=>'Example1',
));
$myWindow->show();
This example creates a window with a 600x500 pixels size, centered in the screen and with a title
called 'Example1'.
5.2 The JavaScript side and the PHP side
Since eyeOS is executed in the server using PHP and it is visualized in the client, using XHTML and
Javascript, it is necessary a mechanism to communicate both parts.
An eyeOS application could be defined this way:





The PHP side is where the classes reside, and in the Javascript side there is a system to draw the
widgets, although the programmer does not need to deal with it.
To communicate both sides, Messages are used. They normally consist of Ajax calls that are made
by the system when the user interacts with some part of an application. For example, if the user
clicks a button, it emits a message, an Ajax call to the server, telling it the button is pressed.
The most interesting part of this process is that it occurs automatically, and the programmer only
has to worry about creating the widgets and managing the events in a free way.
5.3 Messages
The messages in eyeOS are the way to call the events of an application. Those events, normally
being Ajax calls to the server have 3 parameters (although the programmer does not need to deal
with it, since it is automatically handled by eyeOS).
The first parameter is the checknum, a unique random number assigned to every application that
lets eyeOS know to which application a message is directed to.
The second parameter is the signal, which is the name of the event of the application. As said
Javascript+XHTML
PHP

- 24 -
above, with each message received, eyeOS tries to execute a function from the events.eyecode file
called applicationName_on_signal.
Most widgets capable of sending messages use their name as the signal to send. However, their
constructor allows to specify a key named 'signal' to set the name of the signal sent to a desired
value.
$myButton = new Button(array(
'name'=>'Button1',
'signal'=>'doSignal'
'caption'=>'Click me!',
'father'=>'Window1',
'x'=>30,
'y'=>30
));
This example creates a button with the text “Click me!”, that will produce the event 'doSignal'
when clicked.
In addition, the messages have a third param, which is their value. This value is the content of the
widget that produces the event. For example, a textbox that sends a signal when you enter the
text on it would send its text. This parameter lets the PHP side to stay coordinated with the values
of the Javascript/XHTML side.
5.4 Serialization
In eyeOS, the serialization consists in storing all the widgets of an application in the user's session
so that the widgets remain available when an event is triggered. Let's see an example:
We create a textbox and a button, and we want to change the text of the textbox to the string
'Hello, World!' every time the button is clicked.
$myTextbox = new Textbox(array(
'name'=>'textBox',
'width'=>212,
'father'=>'Window1',
'x'=>30,
'y'=>50
));
$myTextbox->show();

$myButton = new Button(array(
'name'=>'button1',
'caption'=>'Change text',
'father'=>'Window1',
'x'=>120,

- 25 -
'y'=>90,
'signal'=>'change'
));
$myButton->show();

Now we have the two elements drawn in the window (named Window1). Now we make that when
the message 'change' is received, the event of the events.eyecode file changes the text inside the
textbox:
function ejemplo1_on_change($params=null) {
$textBox->setText('Hello, world!');
}
Since we gave the textbox the name 'textBox' when we created it, we can access this textbox just
by referring it with this name. This way, we can access and modify the textbox using its class
methods.
Serializing affects the memory of the server. We may be interested in drawing widgets without
serializing them. To avoid serializing a widget is as easy as passing the number 1 as the argument
of the show() method of the widget:
$myTextbox = new Textbox(array(
'name'=>'textBox',
'width'=>212,
'father'=>'Window11',
'x'=>30,
'y'=>50
));
$myTextbox->show(1); //This widget is not serialized! We won't be able to access it from
the events
5.5 Friends
The friends concept in eyeOS is a way to tie widgets so that an event on a widget causes another
widget to refresh its content.
As we saw above, when a widget produces an event, it includes in the message its new content so
that the PHP can have its most recent content.
However, we may want the widget to update the content of other widgets when producing an
event. For example, in an application with a button and a textbox, we want to retrieve the content
of the textbox when the button is pressed.
To update the content of that textbox when the button is pressed, we must make the textbox a
friend of the button. Let's see an example:

- 26 -
$myTextbox = new Textbox(array(
'name'=>'textBox',
'width'=>212,
'father'=>'Window1',
'x'=>30,
'y'=>50
));
$myTextbox->show();

$myButton = new Button(array(
'name'=>'button1',
'caption'=>'Change',
'father'=>'Window11',
'x'=>120,
'y'=>90,
'signal'=>'change'
));
$myButton->addFriend($myTextbox); //Now the textbox is a friend of the button
$myButton->show();
This way, in the events.eyecode file, we can retrieve the content of the textbox this way:
function example_on_change($params=null) {
$text = $textBox->text;
}
Now $text contains the text of the textbox at the moment of clicking the button.



- 27 -
6. Groups
Every user is member of at least one group, normally the public group. Each group has a folder
with its name inside the groups/ directory where all the shared files between the group members
are stored.
Currently there are few functions for group managing, although both the UM and VFS services
offer some interesting ones:

• um_getCurrentGroups: returns a list of all existing groups.
• vfs_real_getDirContent_group: returns the contents of the folders of a group.
The files stored in a group do not have any type of restriction to the other members. For example,
user A can delete a file of user B in the group.



- 28 -
7 Aliases
The aliases in eyeOS are used to shorten the syntax of certain system calls, such as services or
libraries calls.
All the aliases can be found in system/kernel/alias.eyecode. Not all libraries have an alias, only the
most used ones have aliases. Some of the most used aliases are:
• vfs($call,$arg): alias of the function service('eyex',$call,$arg)
• eyeXML($call,$arg): alias of the function reqLib('eyeXML',$call,$arg)
A code using aliases is much clearer, so the use of aliases is encouraged.

3

- 29 -
8 Listener Service Calls3
There are certain cases in which it is necessary to make our application know when other
applications make service calls. A clear example of this necessity would be a process monitoring
application. To solve this need, the eyeOS kernel provides the listener service calls feature.
A listener service call (LSC from now on) is just a notification from the kernel to our application
that a call to the function X of service Y has been made. To make this notification the kernel uses a
similar method to that of MMAP, but this time using a file called com.eyecode.
When we register a LSC, we indicate the kernel 3 parameters: a function, a service and an
identifier. The identifier is used to call the function with the name applicationName_com_identifier
in the file com.eyecode of the registrar application. An example would be:
auuListeneiSeiviceCall('onKill','pioc','close',1):
• onKill: the identifier
• proc: service of the function to listen
• close: function to listen
• 1: specifies that the LSC must be called after the execution of the function
This example adds a listen to the call of the function “close” of the service “proc” and would call
the function applicationName_com_onKill from the file com.eyecode after performing the service
call.


- 30 -
9 Full Screen
Currently, this Toolkit does not have capability to make applications in full screen mode.
Nevertheles it is easy for an application to use this mode making the following changes:

1 - Obtain the width and height of the session screen (variable $_SESSION['SCREEN']).
2 - Create a window with the obtained width and height, specifying the window has a
FIXED_WINDOW type.
3 - Send the following Javascript code:
¡¡We move the content of the winuow at the top
eyeX('iawjs',aiiay('js' => 'uocument.getElementByIu("'.$myPiu.'_winuowName_Content").style.top="upx":')):
¡¡We lowei the z-inuex of the fixeu elements of the uesktop (the uefault value is 1uuuu)
eyeX('iawjs',aiiay('js' => 'uocument.getElementByIu("minimizeuAppsLeft").style.zInuex="u":')):
eyeX('iawjs',aiiay('js' => 'uocument.getElementByIu("minimizeuAppsRight").style.zInuex="u":')):
eyeX('iawjs',aiiay('js' => 'uocument.getElementByIu("minimizeuApps").style.zInuex="u":')):

This way, the created window will not use borders, and will appear in full screen mode. An
important issue is that the application is responsible of restoring the elements of the desktop to
the previous state.
Note that this feature is a hack, and must be always used carefully.


- 31 -
10 Message Tables
As explained in chapter 2.3, MMAP is responsible of addressing the messages, and to do that it
calls functions that use the pattern applicationName_on_eventName. Normally, this system is
enough to satisfy most of the programmers' needs to have a clean and well-organized code.
However, you might want to skip that syntax, and that's why the message tables exist.
To use the message tables we simply must create an indexed array that relates the name of the
event to the function we want to be called. Let's see an example applied to the example of chapter
4:
events.eyecode
$messageTable['buttonPress']['function'] = 'launchMessageBox';
function launchMessageBox($params="") {
¡¡We show a message saying the button has been piesseu
seivice('eyex','messageBox',aiiay('content'=>'The Button has been piesseu!')):
}

As it can be seen, the function called by the event is now launchMessageBox instead of
eyeBasic_on_buttonPress.

- 32 -
11 Important eyeOS Libraries
11.1 eyeSockets
When it comes to sockets, PHP provides lots of function to manage them. Nevertheless, their use is
sometimes unintuitive and unclear. To solve this problem, eyeOS provides the eyeSockets library.
eyeSockets provides a class that offers a clean, quick and efective programming when establishing
and using a connection. In example, we have multiple functions to write and read with this class.
11.2 eyeURL
The eyeURL library provides a simple and solid class to make HTTP requests. This protocol is
necessary to interact with multiple services, and at the same time some protocols are based on it,
such as the XML-RPC protocol.
The uses of eyeURL are numerous and varied, providing eyeOS an infinity of possibilities, like for
example file downloading, web services interaction, etc. Its use is very simple, let's see it with an
example:
$httpClient = eye0RL('getBTTPClient'):
¡¡Biiection 0RL
$httpClient->set0RL('http:¡¡www.google.com¡'):
¡¡We senu the iequest
$httpClient->senuRequest():
¡¡We only obtain the bouy of the iesponse
$html = $httpClient->getResponseBouy()):

This example makes a request to the well-known web search service, and obtains the body of the
response.
11.3 simpleZip
A powerful library to create ZIP files. Its syntax is very simple, and it can be very useful in our
application if we want it to have the ability to generate ZIP files on the fly and offer them for
download.
11.4 eyePear
One of the best qualities in PHP is its large community, and an example of this is the PEAR project
(http://pear.php.net/).
PEAR is a framework and a distribution system for reusable PHP components. In eyeOS only the
framework is used (the collection of its libraries), having to do few little modifications to totally
adapt a library from PEAR to eyeOS.
All libraries from PEAR complement themselves, and at the same time they are based in a class
called PEAR in which they delegate some actions, such as the error reporting. If we want to port a

- 33 -
PEAR library to eyeOS, we must follow only 3 steps:
• Provide the PEAR class to the libraries (eyeOS automatically does this task)
• Check and modify the include parts (the eyeOS structure differs)
• Create a wrapper that will be called by the eyeOS kernel
A good example of this is the eyeCrypt library, which implements two functions: crypt and decrypt,
which are a wrapper of the PEAR classes.

- 34 -
12 Extras directory
The extras directory contains resources which are not integrated in the system, such as binary
applications, external configuration files, etc.
A good example of this kind of resources in this directory would be the conversion between
different formats, a task which is normally delegated to external programs.

- 35 -

13 How sessions work with eyeSessions
The eyeSessions library provides an abstracted method to obtain and save variables and arrays in
the session. An example of its use would be:
¡¡We check if the vaiiable exists
if(eyeSessions('checkvai',aiiay(TABLENANE)) == false){
¡¡If it uoes not exist, we cieate the aiiay
eyeSessions('makeAiiayvai',aiiay(TABLENANE)):
}

Despite seeming redundant in respect to the use of the superglobal variable $_SESSION, the use of
this library is really useful and clear when making intense use of the session.

- 36 -
14 Sharing your work with the eyeOS Community
eyeOS is an Open Source web operating system and applications platform, and aims to be the
strongest free, open source web development platform out there.
This can only be possible with the work of thousands of people who do release they work as Open
Source and share it with the rest of the eyeOS community. There are lots of available licenses out
there. We recommend to use the GNU ones, but you are free to choose what’s the best Open
Source license for your work.
For this reason, we aim you to release your work (from your very first application to a full system
of applications and system tweaks) in the eyeOS Applications Community:
http://www.eyeos-apps.org
You can also find help and updates about the system and its community in the official home page:
http://www.eyeos.org








- 37 -
15 About this manual
15.1 License
This manual is released under the Creative Commons Attribution-No Derivative Works 3.0
License.
You can read the full license text at:
http://creativecommons.org/licenses/by-nd/3.0/

15.2 Authors and contributors
Creators
Jose Carlos Norte
Alejandro Fiestas
English translator
Daniel Gil
Special thanks to
Pau Garcia-Milà
Marc Cercós
Anaël Ollier

You can contact the eyeOS Team at team@eyeos.org .

Index
1. Introduction 1.1 What is eyeOS 1.2 eyeOS basic structure 1.3 The Kernel 1.4 System Services 1.5 Libraries 1.6 eyeOS code organization 1.7 Settings.php 1.8 Versions 2. Basic Services 2.1 VFS, Virtual File System 2.2 UM, User Manager 2.3 MMAP, Message Mapping 2.4 PROC, Process Manager 2.5 EYEX, eyeOS X System 2.6 EXTERN, external files Manager 2.7 LOG, Logging System 2.8 SEC, Security Manager 3. System Libraries 3.1 errorCodes 3.2 eyeXML 3.3 i18n 3.4 eyeWidgets 4. How an application works 4.1 Preparing the environment 4.2 Downloading the code 4.3 Structure of an application 4.4 Initializind and ending of an application

-2-

4.5 Events 4.6 Extern 4.7 Explained example 5. The eyeOS Toolkit in a nutshell 5.1 How the Toolkit works 5.2 The JavaScript side and the PHP side 5.3 Messages 5.4 Serialization 5.5 Friends 6. Groups 7. Aliases 8. Listener Service Calls 9. Full Screen 10. Message Tables 11. Important eyeOS Libraries 11.1 eyeSockets 11.2 eyeURL 11.3 SimpleZip 11.4 eyePear 12. Extras Directory 13. How sessions work with eyeSessions 14. Sharing your work with the eyeOS Community 15. About this manual 15.1 License 15.2 Authors and contributors

-3-

1 What is eyeOS From a technical point of view. Some PHP knowledge is required to read this document. etc. although knowing these technologies will help you understand better eyeOS and its internal functioning. CSS and JavaScript. eyeOS has many services for specific tasks. so it is required to master a lot of languages and understanding numerous concepts to be able to create web applications. In addition. JavaScript or XHTML. There are currently a lot of web-related technologies. Introduction This document is an introduction to the application development for the eyeOS web Operating System.2 eyeOS basic structure Before studying the eyeOS components. the kernel is only thought to unify the system services. eyeOS (http://www. In other words. and it is not necessary to have experience programming with CSS. 1. Client Server Note: Unless specifying the contrary. using only PHP code and leaving to the system the resource management. eyeOS intends to cover those and other problems derived from the web development.org) is a platform for web applications. The platform is created over a client-server architecture. XHTML. Since eyeOS is a microkernel-based platform. the security.3 The Kernel The first step we must take to know eyeOS is the study of its kernel. offering the programmers a homogeneous platform to develop their web applications. and the client is usually a web browser. such as PHP. in which eyeOS is the server. and the kernel is responsible for its communication and location. this manual will assume the client is a web browser.eyeos. every web browser has a different interpretation of the code and every PHP version and configuration works slightly different from the others. 1. 1.1. created with the idea to make easy the application development. the communication with the browser. -4- . we must know its basic structure.

txt')). if we are using the filesystem manager service. they do not handle low level tasks (such as files. For example. applications don't need to specify how to invoke a service. the applications do not manipulate files directly: instead of that. they use a service designed for that purpose.array('file. they just need to know its name.Services Kernel Applications With this architecture. 1. array $params] ). They too are called using the kernel. For example. security is guaranteed since the services apply restrictions to the applications' requests. the service() function (defined in system/kernel/kernel. if we are using the filesystem manager service. The third and last argument is an array containing the parameters passed to the function. string $functionName [. we need to tell it which file we want to delete. The only form to communicate with a service is the kernel. Thus. and they will be studied later.eyecode) must be used.txt. The second argument corresponds to the function to call. as stated above in section 1. 1. This code would call the vfs service (the filesystem manager) to delete a file named file. making available sets of functions the applications might need. To do that. -5- .'delete'.5 Libraries The libraries in eyeOS are similar to the services. and the kernel does the rest of the job. For example. An example of a call would be: service('vfs'. delete or create a file. service() takes 3 arguments: service( string $servicename . users or processes).4 System Services The Services in eyeOS perform low-level tasks. The first argument specifies the name of the service to call. given that a service is a collection of functions and we must specify what function we want to use.2. instead they make the development of applications easier. but unlike the services. In eyeOS there are eight services. we need to specify if we want to copy.

eyeOS includes lots of libraries (that will be studied later).Directory where the applications are located.System directory. eyeOS/groups/ . such as eyeZip.zip'.) The way to use a library is very similar to that of a service. 1. Libraries can be used by any application.) eyeURL – allows to request URLs eyeXML – allows to work with XML files (read.3. write. The code of eyeOS is stored in files with the .System logs directory. being the only difference the fact that the reqLib() function is used instead of service()... In eyeOS everything has its right place to be put on. etc.eyecode extension (for example: kernel.6 eyeOS code organization It is important to know how eyeOS is organized to be able to develop applications for. See chapter 12. eyeOS/i18n/ .Users' directory where all their documents and files are stored.array('file.. such as CSS stylesheets. The third and last argument are the parameters passed to the called function. See chapter 3.Directory where files are stored temporarily.'Documents/')). The second argument corresponds to the function to use. eyeOS/apps/ .Files visible from the exterior. See chapter 2. kernel and global configurations.7.'extractZip'. An example showing the use of this function to extract a ZIP file to a directory using the eyeZip library would be: reqLib('eyeZip'. See chapter 2.I18n and eyeOS translation directory. The eyeOS directory tree can be summarized as: eyeOS/accounts – Information and credentials about the users. images. reqLib() takes the same arguments as service(): reqLib( string $libName . array $params] )..Groups directories. string $functionName [. eyeOS/system/ .Extra files.2. See chapter 4. libraries. compress. See chapter 2. See chapter 2. eyeOS/tmp/ . eyeOS/extras/ .6. The first argument is the name of the library to use. eyeOS/log/ . Contains the services. eyeOS/extern/ . See chapter 6. For example: eyeZip – allows to work with ZIP files (extract.2. eyeOS/users/ .eyecode) -6- . such as extractZip (of eyeZip).

0. version 5. and every 3 months for special versions. An example of this would be the 1.7 Settings.5. only patches to fix bugs. changing only the last version number and adding no new features.0.5.'root'). For example: define('ROOTUSER'. All the settings of this file will be studied later in this manual.1 indicates that the eyeOS is type 1 serie (the previous eyeOS belonged to the 0 series). along with the index. Those errors are fixed and a new version is released. which means that some bugs have been fixed from the 1.0.5. The version numbers always use 4 digits. For example: 1.0. a fixed (patched) version of eyeOS series 1. 1. version 5 (the fifth version of the eyeOS 1 series). 1. eyeOS 1. the third number (0) indicates the sub-version and the last number (1) indicates the revision.1 Where the first number (1) indicates the major eyeOS version.php file (located in the eyeOS root. sub-version 0.5. Defines the name of the root user (the administrator of the system). revision 1. usually using the eyeOS Toolkit classes and functions.which contain normal PHP code.php file). In this file constants are defined and later used in all the eyeOS code.0 version.8 Versions eyeOS releases a new version of the platform every 2 months for normal versions.php One of the most important files that defines the eyeOS functioning is the settings.6 version. -7- . When a new eyeOS version is released. the second number (5) indicates the minor version. Thus. it may contain some errors.

Basic services As explained in chapter 1.3 there are 8 services in eyeOS. Virtual File System One of the most important services in eyeOS is VFS. making it impossible to guess from the outside the name of a file. This means that the VFS functioning can be modified using new modules.1). In addition. The default module is the virtual module. -8- .1 VFS. If an application executed by a user requests VFS to read a file over which the user does not have enough permissions.eyeFile. which is the responsible of providing functions to work with files and directories. The applications do not need to worry whether the user has enough permissions on a file.txt_[RANDOM_STRING]. For example."/. The VFS internal work is done in a modular way. The virtual module uses two files for every file the user creates. VFS will return false and will activate the error code VFS_INSUFFICIENT_PERMISSIONS (read chapter 3. being one called: file. 2."(*+##+-'()%. which are: • • • • • • • • extern eyeX log mmap proc sec um vfs They are located in the eyeOS/system/services/ directory. if we call VFS with the virtual module to create a file: !"#$%&"'($)!(*(&#"+.2. although it can be specified which module to use changing the value of the VFS_MODULE parameter on the settings. The VFS service must always be used in these operations. which will store the content of the new file.(1123 The system will actually create two files. One file is used to store the content of the file and other file is used to store information about it using the XML format.0. it's VFS that ensures the security and not the applications.php file. Absolutely no operation with files must be performed directly using PHP functions such as fopen() and unlink(). the virtual module concatenates a 32 character length random string to every file name. Thus. VFS guarantees that a user is unable to read or edit another user's files.

if we want to delete the file called file. its real name (file. delete) is that a user's files are stored as virtual files to control their creation date. their author and other parameters. The opening modes of VFS open are the same as the fopen() function used in PHP. the virtual module has methods to deal with normal files which do not use the eyeInfo and eyeFile pairs."(*+##+-'()%. For example. and are visible to the user from the File Manager.eyeInfo. files/ . Inside every home directory there are: • • conf/ . and to create files in the groups' directories where the user belongs (see chapter 6). The virtual functions have permissions to read and write the files in the files/ directory of a user's home. but their name is preceded with the prefix real_. fwrite() and fclose() from PHP. The form to decide whether to use a virtual or a real method is as simple as thinking: “Do I need to work with a user's file or with a configuration file?” One detail to bear in mind is that the real functions do not have the same restrictions as the virtual ones. Let's see an example: !"#$%&"'($)!(*(#"+.2.".(1123 If we want to open the file to read it: 5)6373!"#$%&"'($)!(*(86"9(*+##+-'()%. The real functions have permissions to create and edit files everywhere in a user's home (including -9- . such as its author. The real methods work exactly like the virtual ones. real_create. These methods are called real methods. etc) and virtual methods (open. It would not create an eyeFile and eyeInfo file. Apart from this method using pairs of files.the configuration files are stored here as real files with XML format."/.txt_[RANDOM_STRING]. every user has a home directory to work in.0."/.(1123 This code would generate a file called file.(*(#(1123 and from here we can use the file resource $fp using fread(). are real files. As stated in chapter 2.0. which will contain information about the new file. while the system files.the virtual files (using eyeInfo and eyeFile) are stored here.txt) and the creation date. the virtual functions can only edit and delete files that belong to the user.:&#"+."/. The reason there exist real methods (real_open.And another called: file. real_delete. create."(*+##+-'()%. VFS always manages these low-level tasks.0. such as a user's configurations.txt in the system. Inside a group's directory.txt we just need to call VFS once and both files will be deleted: !"#$%&"'($)!(*(4".

For example. Now that we know what a message is. 2. For example: global $currentUser. etc.. One important characteristic is that UM provides a global variable accessible at any place.."!B(23BBC"3+443)%.@!"#A%#(123BBC"3>". Furthermore."3)%.8="34%#3 56+. User Manager The UM service manages the users in the system and provides the methods necessary for registering. This way.@!"#A%#(1233 Knowing the path to the home of the user that executed the application is useful to save files.. for example. . etc). which returns the path to the current user's home directory. It would be dangerous that real files of groups could be altered. the client is responsible of displaying a window. The eyeOS applications reside in the server.txt' inside of the “Documents” folder of the user's home: 56+... sending or asking certain information. 2. For example: 56+. we are creating a text editor and we want to save what the user wrote (using methods explained later) to a file called 'myFile.?<##"9. The communication between the client and the server is done via messages."!B3!%9&"3<!"#(!3)%.1123 3 With this code.3.."3#"!.0. UM provides indispensable methods to build applications. storing and processing the data in it. applications can know which user executes them. being for the client the medium to visualize and interact with the application.10 - ."/.. These restrictions exist for security reasons. we have created the empty file.8#!B=-D%. we needed to obtain the path to the user's home directory to create the file."36+.38)3. or sending a message to the server indicating a button has been clicked. we must first get to know the communication between the client and the server. which contains the username of the current user."3 !"#$%&"'($)!(*(&#"+. so they can only be accessed with virtual functions. obtaining the path to a user's home."!3+#"3%93.83.?<##"9. For that process. logging in.4"#3 56+. Let's imagine.2 UM.."(*+##+-'56+. we can move on and explain how MMAP takes part in this process. but they have no read nor write permissions on the groups's folders.."3<!"#(!3.373!"#$%&"'(<=(*(>"..373!"#$%&"'(<=(*(>".%!3)8. A message is a petition made by the client to the server.3. called $currentUser.3/73(A8&<="9.3/73()%.files/.(23BBC"3+443. conf/.3 MMAP Message Mapping Before introducing MMAP.. like getCurrentUserDir().

8!"(*+##+-'56%4123BBC"3&+. and provides methods to launch.%&+..(*+##+-'(+66J(123 BBC"3&+. since it classifies and transmits the message to the applications. >. and finally it is delivered by the postman.3. Nevertheless.8#"3. and that is explained in chapter 4. 2.MMAP is responsible for routing every received message in the server to the applications. locates a given process with specified pid and returns the name of its application name. MMAP would do the parts of organizing and delivery. which is interpreted by the browser.. All messages have a response in XML format. list processes.+<9&. A good comparison could be made with a postal system.%9>3."36%43%93+98. is a unique number.8E+.4 PROC PROC is responsible for the process managing.11 - . end.5 eyeX As said in chapter 2. When a mail arrives to the post central..8!"3%94%&+. the mmap service manages the messages coming from the client. When an application is launched with PROC. not limited to launching or closing applications. App C Client Messages App A App B Application C MMAP Application A Application B 2.%893.%9>3."39+="38)3.35=-F%423 BBF%438)3+66. it is important to know how to receive its messages. etc. application “app1” executes the application “app2” and then it terminates itself.*3%94%&+."3 !"#$%&"'(6#8&(*(."3+66. although it is 8 characters length and identifies every process in the client-server communication."#3$+#%+E.3.8386"93 !"#$%&"'(6#8&(*(&. For example..%893G+66HI3 56%43735=-F%423 BBC"3!.. two very important variables for the application development are defined: myPid and checknum. 3 3 3 3 3 3 3 As a final note.+<9&. you must know that MMAP is an automated service: it does not require any interaction with the developer at all..3&.%&+. it is classified according to its addressee."36%438)3+66H3 3 PROC provides a wide variety of process managing methods.. myPid is a unique 4 characters length numerical value that identifies every process and checknum. . just like myPid. In this application. the findPidByName() function.

.8!."38<.8#-3&+.8+43)%. In the second case.. the response to the message includes the orders for the browser to create a new window. stylesheets and other files in their applications."43(. we can use eyeX to create a message box in the browser.83. just calling eyeX with Browser creates a new window Server Browser a button is clicked Server service(): !"#$%&"'("-"K(*(="!!+>"L80(*+##+-'(&89.3E"3.!%4"*3+.8&+."#97..B!.6 Extern.12 - ."#9B3O"3Z<!..43<!"3."9. For example."!*3". without worrying about the eyeOS/ directory is not visible from the outside.%"9. and it is eyeX that transforms those orders in an XML message."3"0. external file manage N."3@RSX3 %94"0/6."3)#8=3.8#-/3'!""3&."X3%)3O"3O+9.3+3)%.6["0. The eyeX service is the responsible for managing the response XML sent by the server. 2.3.8&+."3@RS!3+&&"!!%E..8O!3."!."!3=<!..."3"0.3.!3O8#W%9>3%!3$"#-3!%=6.-.."43!."3!"#$"#/3N. Its presence does not reverberate at all at the time of building applications."3&+. annotating the time and user of every action.83&#"+.8348O9."/&!!3%9!%4"38)3+34%#"&. the message goes from the browser to the server.7 Log Log does not require any interaction with the developer."/&!!3 3 This service exists to allow the developers to use images. For example..8!"3)%. we create a button that creates a new window when it is clicked: 3 3 3 3 3 3 In the first case.The response XML contains basic orders to modify the interface of the client."43%93"-"YTB"0."#93+."#3H/P1/3 Q0.3!.%!3%!3+3="!!+>"(1123 2.."3&. such as creating windows or showing an image."!3)#8=3."#93!"#$%&"3+.83>".8<.3%=+>"!*3?TT3)%.8O%9>3."!."!*3U+$+T&#%6.3 )%.(7M(N.+6. It works autonomously registering the system's activity to log files.-. The applications request eyeX basic operations. .(3 ."43 %9!%4"3.&/3 V.8O!3."#9B34%#"&.

Sec is responsible of making eyeOS run in a secure environment.8 Sec Sec is another autonomous system service. To do that. it disables PHP's magic_quotes and register_globals when initiating.13 - . . Thus it's not necessary to worry whether these options are enabled or not: you will always see them disabled. although it reverberates on the developers. unlike the log service.2.

3. The errorCodes library exists to cover this need.1123 BBC"3.3.%&. although there are some very important ones. In this chapter we will study how those libraries work and how we can use them in our applications.36"#=%!!%89!/`1123 !"#$%&"'("-"K(*(="!!+>"L80(*+##+-'(&89."9."(!34%#"&. the libraries are collections of functions we can use from our applications to make the development easier.83+&&"!!3.1 errorCodes When parts of our application are delegated to third parts (services.5.3"##8#3&84"3O+!3!".3 3 3 3 3 3 3 3 3 3 b3 . 3.(7M`a8<348398. System libraries As we saw in chapter 1.. etc.8O%9>3O.373(B". i18n and errorCodes. Each one of these value is called an “errorCode”. we can see how the errorCodes library is used to handle a common action: 56+.#-3."3)%.+$"3"98<>. This library provides two functions: setErrorCode and getErrorCode."9... eyeXML. All system services have values of errors reserved and defined as a constant.3"0%!.+48O(233 BBD%.!"13]33 %)'5)63773\DT:V^T@DDV?VQ^N:FQR_VTTVY^T13]3 3 3 b".!"]3 3 b3 #".(7M`c93<9W98O93"##8#38&&<##"4/`1123 3 BBC"34%!6. In eyeOS there are libraries for a wide range of tasks. Some errorCodes (you can check the documentation pages for all of them): EYEOS_LOG_BAD_VALUE EYEOS_LOG_SERVICE_IGNORED = = -404 -401 In this example."3 BBV)3\DT3#"./`1123 b"."9.+.) it is compulsory to standarize the error reporting so we can identify the errors ocurred in any moment.&B!.<#93)+. getErrorCode() retrieves the error previously stored by setErrorcode so that it can be identified.+-3+3="!!+>"3E803!. setErrorCode() is used to store a value that indicates the type of error (normally represented by a number).83"0+=%9"3O.3.14 - %)'5)63773)+. such as eyeWidgets.<#9!3)+.!"*3O"3=8$"3893.8#-3 5)6373!"#$%&"'($)!(*(86"9(*+##+-'56+.-6"38)3"##8#38&&<##"43 !"#$%&"'("-"K(*(="!!+>"L80(*+##+-'(&89. implementing a unified and extensible method to report errors."348"!398.!"%)'5)63773\DT:DVSQ:^YN:QKVTNT1]3 . libraries."3)%.(7M`N.!"23 !"#$%&"'("-"K(*(="!!+>"L80(*+##+-'(&89.

we are trying to open a file that in Unix systems normally is only accessible by the administrator.1123 BBC"389. and the XMLs as arrays.J+##+-(*+##+-'5=-K=.83#".#+9!)8#=3.<#935=-c##+-m("-"@!"#(nmgnm(&#"+.<#93."3$+. For example.%893 4+.43&#"+."3<!%9>3"-"K_S(!3="."M3 3 d>#8<6M6.<"38)3. it is used to store configurations."A+. and that in Windows systems it does not exist.8#%9>3K_S3O%. the use eyeOS gives to XML differs from the usual form."3!."A+. so much that it would even be considered one of its pillars. called array2xml() and xml2array. among much other uses..In the example.2 eyeXML The XML format is widely used in eyeOS...3+3<!"#3&+."43=+%9*3+943O"3O+9."3 #". and that is the reason we use errorCodes to discover the exact type of error and report it.15 - .!3&#"+. two main functions are used.%893+E8<. As you can note.373`3 d"-"@!"#M3 3 3 3 3 3 d<!"#9+="M=+%9dB<!"#9+="M3 3 d6+!!O8#4Me)f)E+gh+iPPgj+JHf)"kHE4ejjhfPikdB6+!!O8#4M3 3 d"=+%. To make this model possible."3K_S3.84! 5=-K=. Nevertheless.MdB"=+%."A+.83+93+##+-3<!%9>30=.6?84"#!dB>#8<6M3 dB"-"@!"#M`23 BB^8O*3O"3. transport data and messages.+$"3+3$+#%+E..<#93%. Don't be frightened if it sounds a bit abstract.3%9)8#=+.3. using the arrays as XMLs. 3."(nmgn2 The XML is transformed to the following array: Array ( [eyeUser] => Array ( [0] => Array( [username] => Array( [0] => main ) [password] => Array( [0] => 4f5fba03a86607a215fe91bd47735689 ) [email] => Array( [0] => .-3#"."3)%".J+##+-'13 5=-c##+-37#"lS%E'("-"K_S(*(0=..M3 3 d&#"+. in both cases we have a lot of possibilities the file is not accessible."A+.. we provide an example to show how simple it is: BBC"3."MJgBgJBJggjdB&#"+.

'(5=-N"0.#+9!."(*+##+-'5=%N"0.."38<#3. the use of methods rawjs and runjs).+&"3O%."0."4(12`23BBU+$+!&#%6."3..%9>3.3."0.3+. i18n is also capable of translating these kind of texts..811233BBC"3.*3=%36%43"!3eHiJI3 As the example shows.%!...83C8#.#+9!. ."43.8W"9!11233BBC"3.3+93q!3.#+9!.3 5=-N"0."4373#"lS%E'(%Hi9(*(.*5. such as with dynamic texts."0.3 !"#$%&"'("-"K(*(#+OZ!(*+##+-'(Z!(7M5Z!11233BBC"3!"943.@!"#*5=-F%4123 5=-N"0.38<#3U+$+!&#%6. in some occasions it is necessary to add manually the feature.N#+9!. In most occasions this method is sufficient for most cases."3.3&84"3<!%9>3..+."43%93T6+9%!.+."93%93Q9>.+.+.#+9!.3 5Z!373`+.3. We need to bear in mind that the text to translate must be written in English.."3.N#+9!.. 3. To implement the internationalization automatically is as easy as making a call to the translate() function before sending any text to the client. specially in cases in which the Toolkit is not used such as some special visualization in the client (for example. Nevertheless.) [createDate] => Array( [0] => 20/02/2007 ) [group] => Array( [0] => phpCoders ) ) ) ) eyeXML also provides functions to open and write XML files easily (with the methods getXMLfile and setXMLfile) and to directly handle XML configuration files (with methods getXMLconfig and setXMLconfig).#+9!.3.+. 5=-N"0. translating a text with dynamic data is easy: we only have to replace that data with “%s” and provide the function an array with every dynamic data in it."(*+##+-'5=-N"0..8W"9!373+##+-'5&<##"9.."0. but there may be some situations in which the use of this method could not be appropiate."#."3#+OZ!38#4"#3O%. Let's see an example: 5=-N"0. we see how to translate a given static text.4p`23BBY<#38#%>%9+."3<!"#9+="3+943.43E"X3Go8.3 i18n Internationalization The internationalization system is integrated in the eyeWidgets library (see chapter 3.+3#88.16 - .+.3O%."0.4) and it works almost automatically.8W"9! BBN.373`o%3q!*3=-36%43%!3q!`2BBC"3#"6.."3..373#"lS%E'(%Hi9(*(.3=<!.3&84"3 In this example."3#"!<.+.+.373`o".3O8<."36%43 5.O+-!3E"3O#%.#+9!.

tables. eyeWidgets works with eyeX (see chapter 2. etc. similar to local toolkits such as QT. buttons..."(7M(N"!. telling it to append to its response (the response ultimately sent to the client as XML) the necessary orders to draw windows. images.."%>.17 - .8O'123 (9+="(7M(C%948OH(*3 ()+. or other widgets. eyeOS is a graphical Toolkit.4 eyeWidgets The eyeWidgets library provies a quick form of creating graphical interfaces in eyeOS.(7MPgg*3 (. buttons.3C%948O(3 This way. texts. Among other uses. 3 3 3 3 3 3 3 3 3 3 3 Application eyeWidgets eyeX new Window() Browser Orders in XML (see chapter 2.%.5). it allows to create windows. . This library provides a set of classes used to create and modify visual elements in applications..(7MH*3 (O%4. with eyeWidgets we can create graphic elements a user can interact with.5) From this point of view. creating a new window in our application is as simple as typing: 5=-C%948O3739"O3C%948O'+##+-'3 3 3 3 3 3 3 1123 5=-C%948OrM!."#(7M("-"c66!(*3 (&"9.3. For example.(7Mfgg*3 (. but with the difference it works via web.

PHP Editor: any suitable text editor is valid. it is better to use a GNU/Linux environment.eyeos. tags: contains the freezed code for each version released. Apache2 Server: the only server officially supported.1 Preparing the environment All projects must be developed in an adequate environment.4. otherwise the task would become quite a bothersome task. Let's see which requirements our environment should have: • • • • Subversion Client: we will need it to download the latest eyeOS code. GNU/Linux etc. The SVN server can be found at http://svn. FreeBSD. which we thoroughfully recommend: • • • • Official Subversion Client: http://subversion.X. branches: o • unstable: contains applications that do not match the eyeOS quality standard. 4. Mozilla Firefox 2.2 Downloading the code The eyeOS code is in a Subversion (our Version Control system) server.18 - . ANEC (Add n edit cookies) Extension. The eyeOS team uses all the same environment. 4. and it is the main eyeOS working branch.org IDE Eclipse PDT.2 and above. and it is organized as follows: • • trunk: contains stable and secure code.3 Structure of an application One important thing you should know to manage in eyeOS is the structure of an application. o o Firebug Extension.org. PHP 5: the required version since eyeOS 1. A Unix-like OS: OpenBSD. The directory and files tree of an application is as follows: • • eyeOS/apps/ eyeOS/apps/Application/ -Directory that contains the PHP code of each application -Application's main directory .How an application works 4. Our ideal environment is a personal preference: not everybody feels comfortable with the same applications.tigris. for example we are developing an application for GNU/Linux. If.

(. Its use varies enormously depending of the kind and size of the application./!'01.2-1]3 3 3 3 3 b3 • • • eyeNotify: name of the application to which the message is addressed. %)'p56+#+=!13]3 3 b3 !"#$%&"'("-"0(*(="!!+>"L80(*+##+-'(&89. $params: parameters sent from the client. ApplicationName_end: function called by PROC when terminating an application in case it exists. when a user clicks a button an event is produced. the responsible part of treating those messages is the MMAP service. This file contains two functions: • • ApplicationName_run: function called by PROC when launching an application.• • • eyeOS/apps/Application/apps.19 - . A graphical application normally uses it to initialize the User Interface.4 Initializing an ending of an application The initialization and ending of an application is contained in the apps. An example of a valid event function would be: )<9&. passing as an argument the body of the message.5 Events An event is described as an interaction by the user with the interface of our application.eyecode -Initializing and ending code of an application -Event reception code eyeOS/extern/apps/Application -Main directory for the external resources of an application The files and directorios marked in bold are required for an application to work properly.(7M(^"O3="!!+>"3#"&%$"4(1123 #".<#93)+.!"23 . 4. As we explained above.%893!"!#$%&'":89:(!)&*!#!+. MMAP is able to deliver every message thanks to the fact that each message contains the checknum of the addressee application and the name of the event. The only required function in this file is the _run function. reciveNewMessage: name of the event received. For example. To deliver the message.eyecode in the directory of the addressee application and tries to call a function named ApplicationName_on_EventName. We will focus to explain the use of every file and directory in the next sections.eyecode eyeOS/apps/Application/events. but non-graphical and small applications concentrate all their code in this function."9.eyecode file. MMAP finds a file named events. 4.!--. The generated information of every event is sent to the server in the form of a message.

13]3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 b3 BBQ94%9>3)<9&. it is time to see an example: apps."3%9.893 5=-L<."9..%893"-"L+!%&:"94'56+#+=!79<.3%..13]3 3 b3 As we can see..."3O%948O398O3.."43.%s%9>3)<9&..20 - BBC%948O3O%4>"."%>.(37M3Hfg*3 (."(37M3(Q0+=6.+. 4."3%9."#(37M3("-"c66!(*3 (&"9.%+.(*3 (&+6."3"-"c66(3 BBC"34#+O3.3 3 3 3 3 3 3 1123 3 5=-C%948OH3739"O3C%948O'+##+-'3 (9+="(37M3("-"L+!%&:C^A(*3 ()+.7 Explained Example Now that we know how the files and functions affect an application's working..%89X3%.3#"=8$"!3.8O'123 BBL<..6 Extern Using extern in our application is very easy. etc.eyecode: BBV9%.4...(37M3H*3 (O%4.89F#"!!(3 3 BBC"34#+O3. The use of extern in an application is quite useful since it allows to load icons."#)+&"3 )<9&..(7M(E<."#(7M("-"L+!%&:C^A:?89.3 5=-L<.%893"-"L+!%&:#<9'56+#+=!79<.89'+##+-'3 3 3 3 3 3 3 1123 (9+="(7M("-"L+!%&:LN^(*3 ()+...89HrM!.%&W3="p(*3 (0(7Meg*3 (-(7Mig*3 (!%>9+.3&#"+."3E<..3%!34")%9"43 5=-C%948OHrM!.. CSS files. images.."#)+&"3 )<9&..89H3739"O3L<.6..+..%s"(123 .(37M3Jfg*3 (. the initializing function of the application only creates the interface. It is not time .%893.!'(<9!"#%+.8O'123 3 "-"C%4>".%89(7M(V(=3+3E+!%&3"-"c66/3?.%.893O%4>". We only have to place the file we want to access in extern/apps/ApplicationName/ and then use a URL to the file as stated in chapter 2.

..8!"'1]3 3 3 b3 BBC"3=+W"3.8!"43 )<9&.%&+..%893..."93.+!3E""936#"!!"43 !"#$%&"'("-"0(*(="!!+>"L80(*+##+-'(&89."3%.21 - .+.to explain how the eyeOS Toolkit works right now (that part is covered in chapter 5).%893"-"L+!%&:89:?.)3 !"#$%&"'(6#8&(*("94(123 BBC"3!.893%!3&.+.+!3E""936#"!!"4p(1123 3 The event receiver functions have a characteristic syntax as explained earlier. As we can see."3"$"9..3>"9"#+.(7M(N...."3"$"9.8O3+3="!!+>"3%94%&+.+. the name of the event 'buttonPressed' matches the content of the signal parameter of the button.."3L<."3E<. however it is important to notice in the parameter called 'signal' in the button widget.!".3#"&"%$"!3..3>"9"#+.%893."3O%948O3%!3&.3."3E<."3+66.%893. . The details about the Toolkit will be explained in chapter 5."9.%893"-"L+!%&:89:E<.893."93.89F#"!!'56+#+=!7``13]3 3 3 b3 BBD<9&.%&W"43 )<9&.893. and are always called by MMAP.3#"&"%$"!3. events.eyecode: BBD<9&.%9>3..."43O."43O."#=%9+.

We will se . If set to 1. each widget has its own specific parameters. and when it is set to 3 it is centered vertically. we must indicate the name of the window as the father of the button. every widget is a class. inside of which other elements are created. The background is a layer called eyeApps. the widget inside of which this widget is placed. The common parameters of all widgets are: name – the name given to the widget. boxes or windows among other are designated as widgets. etc. • Cent – this key is used to center widgets. With this model. The use of horiz and vert is justified: we may want to stick some element to the right or down border of a window. If set to 2. • • • X – the horizontal coordinate with regard to its father. and centers the widget at the center of the father.1 How the Toolkit works Every visual element of an application has a class that represents it: in other words. This array contains parameters shared in common with other widgets and specific parameters for each widget. In other words. respectively) given be ignored. When it is set to 0 (the default value) nothing is changed. the widget is centered horizontally. father – the father of the widget. such as 'window1'. adding a widget in our application is as easy as instantiating a class. • Vert – exactly like Horiz.5. If it is set to 1. All visual elements of the Toolkit. such as buttons. If. The basic element of this Toolkit is the window.22 - . bars. This name will be used to refer to the widget in the application. Horiz – this flag specifies the form in which the horizontal (X) coordinates are taken. The eyeOS Toolkit in a nutshell The Toolkit is the main part of an application in eyeOS. for example we create a window in our application and want to create a button inside the window. 'button2'. which is the father of all windows that are not placed inside another window. Y – the vertical coordinate with regard to its father. It is the library that helps programmers managing and creating graphical interfaces. the pixels are counted from the right. Aside from these parameters in the array. it makes the horizontal and vertical coordinates (X and Y. but with the vertical (Y) coordinates. and those flags eliminate the need to calculate the size of the window to place the element. If it is set to 0 (the default value) the pixels are counted from the left. 5. All the classes of the Toolkit take as an argument an indexed array when they are instantiated.

The second parameter is the signal. 'width'=>600. This example creates a window with a 600x500 pixels size. it emits a message. although the programmer does not need to deal with it. and the programmer only has to worry about creating the widgets and managing the events in a free way. it is necessary a mechanism to communicate both parts. 'father'=>'eyeApps'. Those events. and in the Javascript side there is a system to draw the widgets. As said . 'cent'=>1. an Ajax call to the server. telling it the button is pressed. 5. if the user clicks a button. normally being Ajax calls to the server have 3 parameters (although the programmer does not need to deal with it. The first parameter is the checknum.23 - . since it is automatically handled by eyeOS). a unique random number assigned to every application that lets eyeOS know to which application a message is directed to. For example. They normally consist of Ajax calls that are made by the system when the user interacts with some part of an application.an example using a window widget to see this $myWindow = new Window(array( 'name'=>'Window1'. 'title'=>'Example1'. 'height'=>500. To communicate both sides. centered in the screen and with a title called 'Example1'. 5. Messages are used.2 The JavaScript side and the PHP side Since eyeOS is executed in the server using PHP and it is visualized in the client. An eyeOS application could be defined this way: Javascript+XHTML PHP The PHP side is where the classes reside. using XHTML and Javascript. The most interesting part of this process is that it occurs automatically. which is the name of the event of the application. )).3 Messages The messages in eyeOS are the way to call the events of an application. $myWindow->show().

4 Serialization In eyeOS.eyecode file called applicationName_on_signal. and we want to change the text of the textbox to the string 'Hello. Most widgets capable of sending messages use their name as the signal to send. 'width'=>212. 'x'=>120. 'x'=>30. eyeOS tries to execute a function from the events. that will produce the event 'doSignal' when clicked. which is their value. This value is the content of the widget that produces the event. 'y'=>50 )). $myButton = new Button(array( 'name'=>'button1'. $myButton = new Button(array( 'name'=>'Button1'.24 - . with each message received. 'father'=>'Window1'. their constructor allows to specify a key named 'signal' to set the name of the signal sent to a desired value. In addition. a textbox that sends a signal when you enter the text on it would send its text. 'y'=>30 )). 'x'=>30. the messages have a third param. Let's see an example: We create a textbox and a button. World!' every time the button is clicked. .above. 'signal'=>'doSignal' 'caption'=>'Click me!'. 5. This example creates a button with the text “Click me!”. This parameter lets the PHP side to stay coordinated with the values of the Javascript/XHTML side. $myTextbox->show(). 'father'=>'Window1'. $myTextbox = new Textbox(array( 'name'=>'textBox'. 'caption'=>'Change text'. the serialization consists in storing all the widgets of an application in the user's session so that the widgets remain available when an event is triggered. However. 'father'=>'Window1'. For example.

when a widget produces an event. We may be interested in drawing widgets without serializing them. } Since we gave the textbox the name 'textBox' when we created it. $myButton->show(). we want to retrieve the content of the textbox when the button is pressed. Let's see an example: . we can access and modify the textbox using its class methods. 'father'=>'Window11'. This way. However. we may want the widget to update the content of other widgets when producing an event. As we saw above. //This widget is not serialized! We won't be able to access it from the events 5. 'x'=>30. Serializing affects the memory of the server.25 - .'y'=>90. 'width'=>212. world!'). 'signal'=>'change' )). To update the content of that textbox when the button is pressed. it includes in the message its new content so that the PHP can have its most recent content. $myTextbox->show(1). the event of the events. Now we make that when the message 'change' is received. Now we have the two elements drawn in the window (named Window1). For example. in an application with a button and a textbox. we can access this textbox just by referring it with this name.eyecode file changes the text inside the textbox: function ejemplo1_on_change($params=null) { $textBox->setText('Hello. To avoid serializing a widget is as easy as passing the number 1 as the argument of the show() method of the widget: $myTextbox = new Textbox(array( 'name'=>'textBox'.5 Friends The friends concept in eyeOS is a way to tie widgets so that an event on a widget causes another widget to refresh its content. we must make the textbox a friend of the button. 'y'=>50 )).

eyecode file. 'father'=>'Window1'. This way. in the events. 'width'=>212.26 - . 'y'=>90. 'x'=>30. 'signal'=>'change' )). $myTextbox->show(). 'x'=>120. } Now $text contains the text of the textbox at the moment of clicking the button. 'caption'=>'Change'. //Now the textbox is a friend of the button $myButton->show(). $myButton->addFriend($myTextbox). we can retrieve the content of the textbox this way: function example_on_change($params=null) { $text = $textBox->text.$myTextbox = new Textbox(array( 'name'=>'textBox'. $myButton = new Button(array( 'name'=>'button1'. 'father'=>'Window11'. 'y'=>50 )). .

normally the public group. Currently there are few functions for group managing. vfs_real_getDirContent_group: returns the contents of the folders of a group.27 - .6. For example. Groups Every user is member of at least one group. user A can delete a file of user B in the group. The files stored in a group do not have any type of restriction to the other members. although both the UM and VFS services offer some interesting ones: • • um_getCurrentGroups: returns a list of all existing groups. . Each group has a folder with its name inside the groups/ directory where all the shared files between the group members are stored.

so the use of aliases is encouraged.$call. Not all libraries have an alias.$arg) A code using aliases is much clearer.7 Aliases The aliases in eyeOS are used to shorten the syntax of certain system calls. such as services or libraries calls.$arg): alias of the function reqLib('eyeXML'. 3 .eyecode.$arg): alias of the function service('eyex'. All the aliases can be found in system/kernel/alias.28 - .$call. only the most used ones have aliases. Some of the most used aliases are: • • vfs($call.$arg) eyeXML($call.

To make this notification the kernel uses a similar method to that of MMAP. A listener service call (LSC from now on) is just a notification from the kernel to our application that a call to the function X of service Y has been made. but this time using a file called com.8!"(*H123 • • • • onKill: the identifier proc: service of the function to listen close: function to listen 1: specifies that the LSC must be called after the execution of the function This example adds a listen to the call of the function “close” of the service “proc” and would call the function applicationName_com_onKill from the file com. . When we register a LSC. The identifier is used to call the function with the name applicationName_com_identifier in the file com..8 Listener Service Calls3 There are certain cases in which it is necessary to make our application know when other applications make service calls.eyecode."9"#T"#$%&"?+.29 - .(*(6#8&(*(&. the eyeOS kernel provides the listener service calls feature. A clear example of this necessity would be a process monitoring application. a service and an identifier. we indicate the kernel 3 parameters: a function.eyecode after performing the service call.eyecode of the registrar application. An example would be: +44S%!..'(89t%. To solve this need.

3.Q.`1/!.Q.."/sV94"07`g`2(1123 "-"K'(#+OZ!(*+##+-'(Z!(37M3(48&<="9."3sr%94"038)3.38)3."3&89.86 "-"K'(#+OZ!(*+##+-'(Z!(37M3(48&<="9."/."9."="9. Note that this feature is a hack.Obtain the width and height of the session screen (variable $_SESSION['SCREEN']). and must be always used carefully."="9.L-V4'`=%9%=%s"4c66!`1/!..Q.863'."/sV94"07`g`2(1123 This way. the created window will not use borders.3$+.. and will appear in full screen mode. Nevertheles it is easy for an application to use this mode making the following changes: 1 ..`1/!."3)%0"43".!38)3..."="9.-.L-V4'`=%9%=%s"4c66!S")."9.Create a window with the obtained width and height."34")+<."3O%948O3+."/sV94"07`g`2(1123 "-"K'(#+OZ!(*+##+-'(Z!(37M3(48&<="9.867`g60`2(1123 BBC"3."="9. this Toolkit does not have capability to make applications in full screen mode./>". An important issue is that the application is responsible of restoring the elements of the desktop to the previous state.L-V4'`=%9%=%s"4c66!R%>.-.Send the following Javascript code: BBC"3=8$"3."34"!W.`1/!.L-V4'`(/5=-F%4/(:O%948O^+=":?89.8O"#3. .. 3 .Q."="9.. 2 .<"3%!3Hgggg13 "-"K'(#+OZ!(*+##+-'(Z!(37M3(48&<="9./>"./>".."3./>".9 Full Screen Currently. specifying the window has a FIXED_WINDOW type.-.-.30 - .

and that's why the message tables exist.. and to do that it calls functions that use the pattern applicationName_on_eventName. function launchMessageBox($params="") { 3 3 b3 BBC"3!.893.eyecode $messageTable['buttonPress']['function'] = 'launchMessageBox'. However. the function called by the event is now launchMessageBox instead of eyeBasic_on_buttonPress.(7M(N. To use the message tables we simply must create an indexed array that relates the name of the event to the function we want to be called. you might want to skip that syntax..8O3+3="!!+>"3!+-%9>3.893. Let's see an example applied to the example of chapter 4: events.. MMAP is responsible of addressing the messages.31 - . Normally.+!3E""936#"!!"43 !"#$%&"'("-"0(*(="!!+>"L80(*+##+-'(&89."3E<.+!3E""936#"!!"4p(1123 As it can be seen.10 Message Tables As explained in chapter 2."9.3. ."3L<. this system is enough to satisfy most of the programmers' needs to have a clean and well-organized code.

6?. quick and efective programming when establishing and using a connection. 11.. PEAR is a framework and a distribution system for reusable PHP components.%"9.rM>".'123 BBC"389..php.(123 BBA%#"&. we have multiple functions to write and read with this class. In eyeOS only the framework is used (the collection of its libraries).. and at the same time some protocols are based on it.1 eyeSockets When it comes to sockets. In example.3 5. The uses of eyeURL are numerous and varied... like for example file downloading.+%93. 11.11 Important eyeOS Libraries 11..=.2 eyeURL The eyeURL library provides a simple and solid class to make HTTP requests.rM!"94R"l<"!.R"!689!"L84-'1123 This example makes a request to the well-known web search service.. eyeSockets provides a class that offers a clean. Its syntax is very simple.3735. This protocol is necessary to interact with multiple services. Its use is very simple.oNNF?."3#"!689!"3 5.."3#"l<"!.32 - .. PHP provides lots of function to manage them.6XBBOOO/>88>. such as the XML-RPC protocol.. having to do few little modifications to totally adapt a library from PEAR to eyeOS.%"9."/&8=B(123 BBC"3!"943. To solve this problem."3E84-38)3.rM!". and an example of this is the PEAR project (http://pear. Nevertheless. web services interaction. If we want to port a . providing eyeOS an infinity of possibilities.net/)..-38E.%"9. let's see it with an example: 5.. eyeOS provides the eyeSockets library. and obtains the body of the response. All libraries from PEAR complement themselves.4 eyePear One of the best qualities in PHP is its large community. and it can be very useful in our application if we want it to have the ability to generate ZIP files on the fly and offer them for download. and at the same time they are based in a class called PEAR in which they delegate some actions.%"9.373"-"@RS'(>". their use is sometimes unintuitive and unclear.%893@RS3 5. such as the error reporting.%"9.6?...3 simpleZip A powerful library to create ZIP files.6?.@RS'(.6?. 11. etc.

which implements two functions: crypt and decrypt. we must follow only 3 steps: • • • Provide the PEAR class to the libraries (eyeOS automatically does this task) Check and modify the include parts (the eyeOS structure differs) Create a wrapper that will be called by the eyeOS kernel A good example of this is the eyeCrypt library. .33 - . which are a wrapper of the PEAR classes.PEAR library to eyeOS.

12 Extras directory The extras directory contains resources which are not integrated in the system. external configuration files. such as binary applications. a task which is normally delegated to external programs. A good example of this kind of resources in this directory would be the conversion between different formats. . etc.34 - .

!"1]3 3 3 3 b3 BBV)3%.3"0%!."&W\+#(*+##+-'NcLSQ^c_Q113773)+."3+##+-3 "-"T"!!%89!'(=+W"c##+-\+#(*+##+-'NcLSQ^c_Q1123 3 Despite seeming redundant in respect to the use of the superglobal variable $_SESSION."&W3%)3."3.13 How sessions work with eyeSessions The eyeSessions library provides an abstracted method to obtain and save variables and arrays in the session.! %)'"-"T"!!%89!'(&.35 - ..*3O"3&#"+."3"0%!."3$+#%+E.348"!398. .. the use of this library is really useful and clear when making intense use of the session. An example of its use would be: BBC"3&.

There are lots of available licenses out there.eyeos.org .14 Sharing your work with the eyeOS Community eyeOS is an Open Source web operating system and applications platform. open source web development platform out there.36 - . We recommend to use the GNU ones. This can only be possible with the work of thousands of people who do release they work as Open Source and share it with the rest of the eyeOS community. but you are free to choose what’s the best Open Source license for your work.eyeos-apps. and aims to be the strongest free. For this reason. we aim you to release your work (from your very first application to a full system of applications and system tweaks) in the eyeOS Applications Community: http://www.org You can also find help and updates about the system and its community in the official home page: http://www.

15 About this manual 15. .37 - . You can read the full license text at: http://creativecommons.org .2 Authors and contributors Creators Jose Carlos Norte Alejandro Fiestas English translator Daniel Gil Special thanks to Pau Garcia-Milà Marc Cercós Anaël Ollier You can contact the eyeOS Team at team@eyeos.org/licenses/by-nd/3.0 License.1 License This manual is released under the Creative Commons Attribution-No Derivative Works 3.0/ 15.

Sign up to vote on this title
UsefulNot useful