ACT

Purpose

act invokes a method on an object.

Synopsis

#include <types.h>
#include <stub.h>

int act(Message_Header *header1, char *buffer1, int size1, Message_Header *header2, char *buffer2, int size2);

Parameters

header1: a message header specifying the target object and the method to be invoked;
buffer1: parameters for the method;
size1: size in bytes of the outgoing parameter buffer;
header2: a message header including the status of the method invoked;
buffer2: parameters returned by the method;
size2: size in bytes of the incoming parameter byffer.

Description

act is the most important system call in Aboelha. It is mainly used by clients to invoke a method over an object. The first three parameters regard the method invocation request sent to the object server. The other three regard the reply sent from the object server.

In header1, the field to identifies the object, from identifies the client mailbox the server should send the reply and method specifies the method to be invoked. In addition to this fields, header1 also includes two other 4 bytes fields that can be used for parameter passing to the method. For most methods the header is enough to hold all the requested parameters. However, methods like write on a file will need much more space. In this cases, parameters can be stored in buffer.

In header2, the field to identifies the client mailbox specified in the field from from header1, i. e., the mailbox to where the server should send a reply for the method invoked. The field from identifies the object manipulated, while method specifies the status of the invoked method. As in the outgoing message, the method can return parameters through the two fields in header2 or through buffer2.

act can be used to invoke methods on kernel objects as well as on user objects. The object location is transparent to users, so remote objects, even kernel objects, can be manipulated just like local ones.

Return Values

On success, act returns 0 and that means the method has been invoked. It does not mean the method has been properly executed. The method results are passed through the field method in header2.

On fail, act returns a negative value indicating one of the following errors:

Invalid capability: the capability in header1.to is not valid;
Insufficient rights: the rights in header1.to are not enough for the requested method.

Notes

When the method in question is the creation of a new object, the capability to in header1 is not checked. Actually, only the server identification is used. The object capability is returned in the field from in header2.