3 Quick Start

This section illustrates how ONC RPC clients and servers can be implemented using Guile-RPC. ONC RPC defines a language to describe RPCs and the data types they depend on (see RFC 4506, Section 6 and RFC 1831, Section 11). This language, which we refer to as the XDR/RPC language or simply RPC language, is essentially an interface description language (IDL). It resembles the C programming language and borrows C’s type definition constructs and adds the program and version constructs that introduce RPC definitions.

Consider the following RPC definition, written using the XDR/RPC language:

struct result_t
{
  int          integer_part;
  unsigned int decimal_part;
};

program ARITHMETIC_PROGRAM
{
  version ARITHMETIC_VERSION
  {
    /* Return the integer part and the 1000th of the
       given double-precision floating point number.  */
    result_t split_number (double) = 1;
  } = 0;
} = 80000;

It defines a simple RPC interface named ARITHMETIC which contains only one procedure called split_number (). The interface itself has a program number that identifies it (here, 80000). Normally, program numbers below 20000000 (hexadecimal) are assigned by Sun Microsystems, Inc. and thus should not be used unless the number has been properly registered (see RFC 1831, for details). It also has a version number (here, 0) that is user-defined and should be increased when the interface changes (e.g., when procedures are added, modified, etc.). Finally, the procedure split_number () has a procedure number (here, 1) that allows it to be distinguished from other procedures.

People vaguely familiar with the C programming language should have guessed by now that this simple interface defines a procedure that takes a double-precision floating-point number and returns a structure that contains two fields.

Client and server creation are two-step. Since the first step—data type definition—is the same for both, that leaves us with a total of three steps, described below. Nicely, each of these steps can be automated using the XDR/RPC language compiler (see grpc-compile).

More details about the XDR type definition as well as client and server creation are available in the API reference (see API Reference).