DlpRPC(3)

NAME
DlpRPC - make remote procedure call on PalmOS device

LIBRARY
libpconn

SYNOPSIS
#include <palm.h>
#include <pconn/pconn.h>
int
DlpRPC(PConnection *pconn, uword trap, udword *D0, udword *A0, int argc, struct DLPRPC_param *argv);

DESCRIPTION
DlpRPC makes a remote procedure call on the Palm. That is, this function requests that the Palm execute a particular system function with certain arguments. DlpRPC then returns the (integer) return value of the system call, and fills in any by-reference arguments.

trap specifies the trap number of the system call to make.

D0 and A0 specify the initial values of the D0 and A0 registers. After the remote procedure call, these arguments are filled in with the new values of D0 and A0. D0 is typically used for the return value.

argc specifies the number of arguments in argv.

argv is an array of function arguments to pass. The elements of argv are in reverse order from the function declaration. That is, if a system call is declared as SysFunc(a, b, c), then argv[0] will contain a, argv[1] will contain b, and argv[2] will contain c ( argc should, of course, be set to 3). The DLPRPC_param structure is defined as

    struct DLPRPC_param {
    	Bool byref;
    	ubyte size;
    	char type;
    	union {
    		ubyte bool_v;
    		ubyte byte_v;
    		uword word_v;
    		udword dword_v;
    		void *raw_v;
    	} data;
    };

where byref is true if this argument is passed by reference, size specifies the size of the argument (this is only required for raw arguments), type specifies the argument type (see the RPCP_* constants in <pconn/dlp_rpc.h> ), and data contains the actual argument data.

This should be relatively straightforward for boolean and integer arguments. Raw arguments deal with byte strings of arbitrary length. The length of the data is specified with argv[i].size. argv[i].data.raw_v must point to a buffer of sufficient size to hold the returned data. DlpRPC reads from and writes to this pointer, but does not allocate or free it.

RETURN VALUE
DlpRPC returns 0 if successful, or a negative value otherwise. Note that it is quite possible for DlpRPC to succeed, and for the remote procedure call to fail. For example, if DlpRPC is used to read a nonexistent memory range, DlpRPC will return 0, but D0 (which is typically used for the system call's return value) will be nonzero.

SEE ALSO
libpconn(3), RDLP_ROMToken(3), RDLP_MemMove(3).