An interface declaration consists property definitions and functions declarations.
The following is an example,
1 interface test {
2 property TRANSPORT_PROTOCOL = tcp;
3 int my_read(
4 out char [maxsize=maxlen, size=return>0?return:0] buf,
5 int maxlen
6 )
7 {
8 property FORK_ON_CALL = true;
10 };
12 int my_write(in char [size = len] buf, int len);
13 } = 12221;
At line 1, the keyword interface followed by the identifier test
announces our RPC. At line 2, we set the TRANSPORT PROTOCOL
of the RPC to be TCP. Properties are optional settings that customize
RPCes on the client or server side. If the TRANSPORT_PROTOCOL property is not set,
the default is tcp_and_udp, meaning the client can connect to the server
via both protocols. From line 3 to line 10, we declared an RPC function
my_read(char* buf, int maxlen), the out keyword on line
4 says that the buf is used for output only, and its maximum size
is determined by the second argument maxlen, its size is determined
by the expression (return > 0? return:0), where the return
keyword
is the return value of the RPC function. Obviously, return
can ONLY be used in size expressions for out arguments.
The FORK_ON_CALL
property says that the RPC server will fork a child upon receiving the my_read()
call, so the parent can handle other requests. Line 12 declares another
RPC function int my_write(char* buf, int len), in this case, the
buf is used for input only, the size of buf is determined by the
len argument. my_write() does not have additional properties,
unlike my_read(), the server will not fork a child to handle it.
Line 13 specifies that the test RPC is identified
by the program number 12221. The program number is a long integer used to
identify the RPC program, and it should not be in conflict with other RPC
programs.
PowerRPC IDL allows you to specify the direction of the argument as one of in, out and inout, the default direction is in. You can use an argument in the size expression for an array argument.
The property definitions have scopes. When a property is defined in the scope of the interface, it is shared by all RPC functions. However, a function can redefines a particular property, and overrides the common value.
RPC properties are very useful in customizing how RPC works. They can be a boolean that toggle between options, or a value to set a parameter, or a function to be called at a particular point.