OSF DCE Application Development Guide--Introduction and Style Guide

OSF DCE Application Development Guide—Introduction and Style Guide
server.
The top-level pointer is thus the address of the parameter container, and obviously,
this value should not change during the course of the call. If it did, the return value
would be written to some undetermined place in the client address space. Hence, the
top level of [out] and [in,out] parameters have reference pointer semantics. The IDL
compiler enforces this for [out] parameters by permitting only the [ref] attribute. It
does not force this for [in, out] parameters, but the behavior is exactly the same.
Remember, the actual parameters of an RPC call are always passed by value: hence a
call cannot change the value of a top-level pointer. It can only change the value of
something passed by reference.
• To pass an [in] parameter by reference, you can pass its address as a pointer of either
style. The server stub will allocate and deallocate the required memory for the
pointer referent. Since an [in] pointer has no reason to change its value, it is at least
slightly more efficient to use a reference pointer in this case.
• Since [out] semantics do not consider the contents of such storage to be meaningful,
an [out] parameter is not marshalled on the call. The server stub will allocate
memory to hold the referent as long as the size of the referent is known at compile
time. The stub obviously cannot allocate memory for referents whose size is
determined arbitrarily by the the server application. For such parameters (such as
linked lists) the server application must allocate space.
One tricky case to consider is a linked list. The server stub allocates space for the
head element, since it knows the size of such an element. The server manager then
allocates space for the remaining elements and marshalls them back to the client.
The client stub will allocate all necessary space for the server-created receive
parameters.
A server-created structure may contain reference pointers which the server may then
set to point to objects it also allocates. All of this will be mirrored by the client stub.
Note that this does not violate the rules for reference pointers, since the contained
pointers do not change value during the call; they are created by the server
application and passed back to the client exactly the same way that top-level
reference pointers are created by clients and passed to servers.
When an application wishes to have the callee allocate space for an [out] parameter,
it needs to use two levels of indirection: a reference pointer to a full pointer to the
data structure to be allocated. The client allocates the full pointer, setting it to
NULL, and passes its address to the call. The server application then allocates the
data structure and sets the full pointer to point to it. The client stub will then allocate
space for the data structure on the return.
• An [in,out] reference pointer behaves exactly like the [out] reference pointer case,
except that the server stub may be able to allocate space for a referent even if its size
is not known at compile time. This will be the case when the client application
creates an instance of a variable sized referent, such as a linked list. In such a case,
the server stub will allocate sufficient space for the referent supplied by the client.
• You must take care when a server deallocates a [ptr] pointer referent. For an [in,out]
parameter, the client-side stub does not deallocate the client-side referent, but the
application should treat the referent as undefined, as if, in effect, the deallocated
pointer referent had been unmarshalled by the client stub. By default, in the case of
an [in] parameter, the value of the pointer referent remains unchanged on the client
6− 12 Tandem Computers Incorporated 124246