13.5.1 Operation Parameters and Signatures
The following table displays the mapping for the basic OMG IDL
parameter passing modes and return type according to the type being
passed or returned. The following table displays the same
information for T_var
types. The following table is
merely for informational purposes; it is expected that operation
signatures for both clients and servers will be written in terms of
the parameter-passing modes shown in the following table, with the
exception that the T_out
types will be used as the
actual parameter types for all out
parameters.
It is also expected that T_var
types will support
the necessary conversion operators to allow them to be passed
directly. Callers must always pass instances of either
T_var
types or the base types shown in the following
table, and callees must treat their T_out
parameters
as if they were actually the corresponding underlying types shown
in the following table.
In following table, fixed-length arrays are the only case where
the type of an out
parameter differs from a return value, which is necessary because C++ does not allow a function to return an array. The mapping returns a pointer to a slice of the
array, where a slice is an array with all the dimensions of the original array
specified except the first dimension.
Table 13-7 Basic Argument and Result Passing
Data Type | In | Inout | Out | Return |
---|---|---|---|---|
short | Short | Short& | Short& | Short |
long | Long | Long& | Long& | Long& |
unsigned short | UShort | UShort& | UShort& | UShort& |
unsigned long | ULong | ULong& | ULong& | ULong& |
float | Float | Float& | Float& | Float& |
double | Double | Double& | Double& | Double& |
boolean | Boolean | Boolean& | Boolean& | Boolean& |
char | Char | Char& | Char& | Char& |
wchar | WChar | WChar& | WChar& | WChar& |
octet | Octet | Octet& | Octet& | Octet& |
enum | enum | enum& | enum& | enum& |
object reference ptr (See Note below.) | objref_ptr | objref_ptr& | objref_ptr& | objref_ptr |
struct, fixed | const struct& | struct& | struct& | struct |
struct, variable | const struct& | struct& | struct*& | struct* |
union, fixed | const union& | union& | union& | union |
union, variable | const union* | union& | union& | union |
string | const char | char*& | char*& | char* |
wstring | const WChar | WChar*& | WChar*& | WChar* |
sequence | const sequence& | sequence& | sequence*& | sequence* |
array, fixed | const array | array | array | array slice * (See Note below.) |
array, variable | const array | array | array slice *& | array slice * |
any | const any& | any& | any*& | any* |
Note:
The Object reference ptr data type includes pseudo-object references. The array slice return is an array with all the dimensions of the original array except the first dimension.A caller is responsible for providing storage for all arguments
passed as in
arguments.
Table 13-8 T_var Argument and Result Passing
Data Type | In | Inout | Out | Return |
---|---|---|---|---|
object reference var (See Note below.) | const object | objref_var& | objref_var& | objref_var |
struct_var | const struct_var& | struct_var& | struct_var& | struct_var |
union_var | const union_var& | union_var& | union_var& | union_var |
string_var | const string_var& | string_var& | string_var& | string_var |
sequence_var | const sequence_var& | sequence_var& | sequence_var& | sequence_var |
array_var | const array_var& | array_var& | array_var& | array_var |
any_var | const any_var& | any_var& | any_var& | any_var |
Note:
The object reference var data type includes pseudo-object references.The following table and table describe the caller’s
responsibility for storage associated with inout
and
out
parameters and for return results.
Table 13-9 Caller Argument Storage Responsibilities
Type | Inout Param | Out Param | Return Result |
---|---|---|---|
short | 1 | 1 | 1 |
long | 1 | 1 | 1 |
unsigned short | 1 | 1 | 1 |
unsigned long | 1 | 1 | 1 |
float | 1 | 1 | 1 |
double | 1 | 1 | 1 |
boolean | 1 | 1 | 1 |
char | 1 | 1 | 1 |
wchar | 1 | 1 | 1 |
octet | 1 | 1 | 1 |
enum | 1 | 1 | 1 |
object reference ptr | 2 | 2 | 2 |
struct, fixed | 1 | 1 | 1 |
struct, variable | 1 | 3 | 3 |
union, fixed | 1 | 1 | 1 |
union, variable | 1 | 3 | 3 |
string | 4 | 3 | 3 |
wstring | 4 | 3 | 3 |
sequence | 5 | 3 | 3 |
array, fixed | 1 | 1 | 6 |
array, variable | 1 | 6 | 6 |
any | 5 | 3 | 3 |
In particular, exception
used as a data type and a
function name.
Table 13-10 Argument Passing Cases
Case | |
---|---|
1 | Caller allocates all necessary storage, except that which may be encapsulated and managed within the parameter itself. For inout parameters, the caller provides the initial value, and the callee may change that value. For out parameters, the caller allocates the storage but need not initialize it, and the callee sets the value. Function returns are by value.
|
2 | Caller allocates storage for the object reference. For inout parameters, the caller provides an initial value; if the callee wants to reassign the inout parameter, it will first call CORBA::release on the original input value. To continue to use an object reference passed in as an inout , the caller must first duplicate the reference. The caller is responsible for the release of all out and return object references. Release of all object references embedded in other structures is performed automatically by the structures themselves.
|
3 | For out parameters, the caller allocates a pointer and passes it by reference to the callee. The callee sets the pointer to point to a valid instance of the parameter’s type. For returns, the callee returns a similar pointer. The callee is not allowed to return a NULL pointer in either case.
In both cases, the caller is responsible for releasing the returned storage. To maintain local/remote transparency, the caller must always release the returned storage, regardless of whether the callee is located in the same address space as the caller or is located in a different address space. Following the completion of a request, the caller is not allowed to modify any values in the returned storage—to do so, the caller must first copy the returned instance into a new instance, and modify the new instance. |
4 | For inout strings, the caller provides storage for both the input string and the char* pointing to it. Since the callee may deallocate the input string and reassign the char* to point to new storage to hold the output value, the caller should allocate the input string using string_alloc() . The size of the out string is, therefore, not limited by the size of the in string. The caller is responsible for deleting the storage for the out using string_free() . The callee is not allowed to return a NULL pointer for an inout, out, or return value.
|
5 | For inout sequences and anys , assignment or modification of the sequence or any may cause deallocation of owned storage before any reallocation occurs, depending upon the state of the Boolean release parameter with which the sequence or any was constructed.
|
6 | For out parameters, the caller allocates a pointer to an array slice, which has all the same dimensions of the original array except the first, and passes the pointer by reference to the callee. The callee sets the pointer to point to a valid instance of the array.
For returns, the callee returns a similar pointer. The callee is not allowed to return a NULL pointer in either case. In both cases, the caller is responsible for releasing the returned storage. To maintain local/remote transparency, the caller must always release the returned storage, regardless of whether the callee is located in the same address space as the callee or is located in a different address space. Following completion of a request, the caller is not allowed to modify any values in the returned storage—to do so, the caller must first copy the returned array instance into a new array instance, and modify the new instance. |
Parent topic: Argument Passing Considerations