NDRGEN(1ONBLD) | illumos Build Tools | NDRGEN(1ONBLD) |
The ndrgen utility takes an input protocol definition file and generates an output C source file that contains the marshalling routines to implement the RPC protocol. If the input file is named proto.ndl, ndrgen generates NDR routines in proto_ndr.c. Applications must define the service definition and server-side stub table for use with the RPC protocol.
The following is an example stub table and service definition:
static service_t net_svc = {
"NETSVC", /* name */
"Network Service", /* description */
"\\netsvc", /* endpoint */
"\\pipe\\netsvc", /* secondary address port */
"12345678-1234-abcd-ef0001234567abcd", 1, /* abstract syntax */
"8a885d04-1ceb-11c9-9fe808002b104860", 2, /* transfer syntax */
0, /* bind_instance_size */
0, /* bind_req() */
0, /* unbind_and_close() */
0, /* call_stub() */
&TYPEINFO(svc_interface), /* interface ti */
net_svc_stub_table /* stub_table */
};
The C preprocessor, which can be specified in the CC environment variable or on the command line, is run on the input file before it is interpreted by ndrgen. The NDRGEN preprocessor symbol is defined by ndrgen for use by the ndrgen programmer.
The NDR generated by ndrgen is an MSRPC compatible implementation of OSF DCE NDR. This implementation is based on the X/Open DCE: Remote Procedure Call specification (CAE Specification (1997), DCE 1.1: Remote Procedure Call Document Number: C706), enhanced for compatibility with MSRPC Unicode (UCS-2) strings.
The following table shows the DCE RPC layering compared against ONC RPC.
There are two major differences between the DCE RPC and ONC RPC:
The following terminology is used in the subsequent discussion of NDR.
The following DCE RPC terminology is used in the subsequent discussion.
MSRPC strings are always varying and conformant format and not null terminated. This format uses the size_is, first_is, and length_is attributes:
The size_is attribute is used to specify the number of data elements in each dimension of an array.
The first_is attribute is used to define the lower bound for significant elements in each dimension of an array. For strings, this value is always zero.
The length_is attribute is used to define the number of significant elements in each dimension of an array. For strings, this value is typically the same as size_is, although it might be (size_is - 1) if the string is null terminated.
MSRPC Unicode strings are not null terminated, which means that the recipient must manually null-terminate the string after it has been received. Note that there is often a wide-char pad following a string, which might contain zero but this situation is not guaranteed.
Despite the general rule, some MSRPC services use null-terminated Unicode strings. To compensate, MSRPC uses the following additional string wrapper with two additional fields. Note that LPTSTR is automatically converted to string_t by the NDR library.
Here, length is the array length in bytes excluding any terminating null bytes and maxlen is the array length in bytes including the terminating null bytes.
The following shows the C data type associated with the NDRGEN NDL:
#include "ndrtypes.ndl"
/*
* Opnums: note that ndrgen does not automatically number
* operations and the values do not have to be sequential.
*/
#define SVC_CLOSE 0x00
#define SVC_OPEN 0x01
#define SVC_READ 0x02
#define SVC_WRITE 0x03
/*
* Define a file handle - choice of UUID format is
* arbitrary. Note that typedef's cannot be declared
* with the struct definition.
*/
struct svc_uuid {
DWORD data1;
DWORD data2;
WORD data3[2];
BYTE data4[8];
};
typedef struct svc_uuid svc_handle_t;
struct xferbuf {
DWORD nbytes;
DWORD offset;
SIZE_IS(nbytes) BYTE *data;
};
typedef struct xferbuf xferbuf_t;
/*
* Define the RPC operations.
*/
OPERATION(SVC_CLOSE)
struct svc_close {
IN svc_handle_t handle;
OUT DWORD status;
};
OPERATION(SVC_OPEN)
struct svc_open {
IN LPTSTR servername;
IN LPTSTR path;
OUT svc_handle_t handle;
OUT DWORD status;
};
OPERATION(SVC_READ)
struct svc_read {
IN svc_handle_t handle;
IN DWORD nbytes;
IN DWORD offset;
OUT xferbuf_t buf;
OUT DWORD status;
};
OPERATION(SVC_WRITE)
struct svc_write {
IN svc_handle_t handle;
IN xferbuf_t buf;
OUT DWORD nbytes;
OUT DWORD status;
};
/*
* Define the interface.
*/
INTERFACE(0)
union svc_interface {
CASE(SVC_CLOSE)
struct svc_close net_close;
CASE(SVC_OPEN)
struct svc_open net_open;
CASE(SVC_READ)
struct svc_read net_read;
CASE(SVC_WRITE)
struct svc_write net_write;
};
typedef union svc_interface svc_interface_t;
EXTERNTYPEINFO(svc_interface)
#endif /* _SVC_NDL_ */
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Availability | SUNWbtool |
October 22, 2007 |