Objects and Syscalls

Each platform provides a set of objects and syscalls.

Objects

Objects package large chunks of device functionality and come from platforms. Not all objects are supported by every platform — this is the whole point of having them defined within platforms in the first place.

In Tibbo BASIC/C, objects cannot be instantiated (multiplied). They exist as a given. You can think of them as "embedded libraries" — unchangeable and always available.

Many objects are asynchronous and non-blocking. This means that if your application (running on the virtual machine of process two) requests an action — for example, opening a TCP connection — this is actually executed by process one. Your application doesn't wait for this to happen, it moves right on with its life in process two. By the time a TCP link is established, your app has potentially executed a significant amount of code. Process one will inform your application of its progress establishing a connection by generating events.

You interact with objects through their events, properties, and methods.

Object events are what TiOS relies on for its operation. Nothing ever happens until an event is generated.

When processing an event, TiOS calls an event handler for this event, provided that this event handler is defined in your application.

Event handlers are subs in Tibbo BASIC and void functions in Tibbo C. This was covered in Procedures and Event Handlers.

Object properties are like internal object variables. Reading and writing them defines objects' behavior.

Some properties are read-only. You cannot set their values. Such properties exist to relate useful information about the current objects' state.

Object methods are actions you can ask an object to perform. It is through methods that you get objects to do useful things.

The list of available objects, their properties and methods can be found in the Browser-Project pane: View > Project-Browser, then Platforms -> Objects.

Object events are listed separately, under the Events branch.

Here is a code example of interacting with objects:

Tibbo BASIC

							sub on_sys_init()                          'using an event of a system (sys.) object
   ...   
   sock.protocol=PL_SOCK_PROTOCOL_TCP      'setting up properties of a socket (sock.) object 
   sock.localportlist="1000"               'the socket will be accepting incoming TCP connections on port 1000
   sock.inconmode=PL_SOCK_INCONMODE_ANY_IP_ANY_PORT
   sock.reconmode=PL_SOCK_RECONMODE_3   
end sub

sub on_sock_data_arrival()                  'using an event of a socket (sock.) object
   sock.setdata(sock.getdata(sock.txfree))  'invoking 3 different methods of a sock. object on a single line!
end sub
						

In C, you must write method invocations with parentheses, even if there are no arguments to pass, like this:

Tibbo C

							...
sock.connect(); //parentheses are important
						

Syscalls

Syscalls are API functions that are built into platforms. You can see the current syscall list here.

Not all syscalls are supported by every platform — again, this is the whole point of having them in platforms.

The list of available syscalls can be found in the Browser-Project pane: View > Project-Browser, then Platforms -> Syscalls.

You can think of syscalls as platform procedures (functions).

Here is a little example of how syscalls are used; it shows the use of string-related syscalls:

Tibbo C

							string s="This is a test and this test tests some string syscalls";   //implicit "string load" syscall invocation
unsigned char x=instr(1,s,"test",3);                                  //using the instr() syscall to find the third occurrence of the word "test"
s=mid(s,x,255);                                                       //using the mid() syscall to cut out a portion of the string
...
						