Marshalling code library

MSRPC2 uses the MSDR library to marshal and unmarshal data to/from the underlying communication format. MSDR defines a set of encoding and decoding rules for each possible data type. Each rule is specified in a functional form. Three types of operations can be invoked on an instance of a particular type, namely encoding, decoding and freeing. The encoding operation is used to encode an instance of a type into a form suitable for transmission using MSRPC2 protocols to the destination. The decoding rule is used by a receiver to convert the underlying protocol data into an instance of the appropriate type. The freeing rule is used to discard an instance of a particular type, once it is no longer required.

For each of the basic MSRPC2 types there is a corresponding MSDR type, listed below. For each MSDR type 3 functions are provided in the MSDR library to encode, decode and free data of that type. The encoding function is prefixed with m_, the decoding function is prefixed with u_, and the freeing function is prefixed with f_. The basic MSDR types are:

Constructed types, declared in MSRPC2 MIDDL interfaces, are also marshalled and unmarshalled using MSDR primitives. For each type in the interface, the interface compiler generates the 3 MSDR functions for encoding, decoding and freeing data of that type. These functions will make use of the basic MSDR primitives declared in the MSDR library. It is therefore possible to marshal data of any type, simply by making use of a set of basic marshalling primitives.

Associated with each MSRPC2 session binding at the client and server is an MSDR ``handle'' which refers to an object which maintains the state on the (de)serialisation of data corresponding to arguments and results of RPC calls. Both the client and server link with the same stub library and use the same MSDR routines to perform the (un)marshalling of the data. The MSDR object is initialised with a memory management structure containing pointers to 2 functions, for allocating and freeing memory. These are passed into the library by the client or server when creating the binding.

Wire representation

MSDR is endian dependent. Each interface reference contains information which describes the endian of the interface instance. A client is expected to marshal data in the endian format of the server. Similarly the client must convert data from the endian of the server into its own endian when results are received. This conversion is carried out automatically by the MSDR library. Each MSDR object has an associated endian, which it uses to marshal the data in the correct way. The endian of the data on the wire is thus the endian of the interface instance.

The wire representation of MSRPC2 RPC calls can differ according to the protocol being used for communication. For MSNL, the protocol defines two words of header per message. These are as follows:

• For an RPC call/announcement: word 0 contains a sequence number indicating the sequence number of the call since the beginning of the session; word 1 contains an integer representing the remote operation which is to be invoked.
• For returned results: word 0 contains the sequence number used in the invocation of the operation, to allow the client to associate the results with the appropriate invocation; word 1 contains a status code which indicates whether or not the RPC succeeded. If the status is not MSRPC2STAT_SUCCESS , then it indicates that an exception has been raised at the server, and the appropriate exception handler should be invoked.

• For an RPC call/announcement: word 0 contains an integer representing the remote operation which is to be invoked.
• For returned results: word 0 contains a status code which indicates whether or not the RPC succeeded. If the status is not MSRPC2STAT_SUCCESS , then it indicates that an exception has been raised at the server, and the appropriate exception handler should be invoked. The internal exceptions which can be raised are listed below.

• MSRPC2STAT_CLNT_NO_BUFS - the client cannot obtain an I/O buffer for communication
• MSRPC2STAT_CLNT_CANT_SEND - failure in sending call/reply
• MSRPC2STAT_CLNT_CANT_RECV - failure in receiving call/reply
• MSRPC2STAT_CLNT_OUT_OF_MEM - out of memory
• MSRPC2STAT_CLNT_IPC_ERROR - failed in setting up IPC
• MSRPC2STAT_CLNT_CANT_ENCODE_ARGS - the client cannot encode the arguments to the call, possibly due to a lack of buffer space
• MSRPC2STAT_CLNT_CANT_DECODE_RES - client cannot decode results received from the server
• MSRPC2STAT_CLNT_TIMED_OUT - call timed out
• MSRPC2STAT_CLNT_BAD_EXCEPTION - bad exception raised at client
• MSRPC2STAT_CLNT_NO_EXCPT_HANDLER - exception raised has no handler
• MSRPC2STAT_UNKNOWN_PROTO - unknown protocol requested in interface reference
• MSRPC2STAT_BIND_FAILED - probably server has moved on
• MSRPC2STAT_OFFER_FAILED - server cannot initialise a new offer
• MSRPC2STAT_SVC_IPC_CLOSED - client closed connection
• MSRPC2STAT_SVC_NO_BUFS - the server has run out of I/O buffers
• MSRPC2STAT_SVC_CANT_SEND - failure in sending call/reply - usually due to a protocol error at a lower level
• MSRPC2STAT_SVC_CANT_RECV - failure in receiving call/reply - usually due to a protocol error at a lower level
• MSRPC2STAT_SVC_OUT_OF_MEM - out of memory
• MSRPC2STAT_SVC_IPC_ERROR - failed in setting up server side of communication path
• MSRPC2STAT_SVC_CANT_DECODE_ARGS - server couldn't decode arguments
• MSRPC2STAT_SVC_CANT_ENCODE_RES - server cannot encode results
• MSRPC2STAT_SVC_TIMED_OUT - listen timed out
• MSRPC2STAT_SVC_BAD_PROCNO - illegal procedure (operation) requested
• MSRPC2STAT_THREAD_ERROR - thread package problem
• MSRPC2STAT_USER_ERROR - a user level exception has been raised