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 (inte

ger) return value of the system call, and fills in any by-refer

ence arguments.

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

D0 and A0 specify the initial values of the D0 and A0 regis

ters. 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 arbi

trary length. The length of the data is specified with

argv[i].size. argv[i].data.raw_v must point to a buffer of suf

ficient 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 other

wise. 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 val

ue) will be nonzero.

SEE ALSO

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

BSD Aug 16, 2001

BSD