The storage access and allocation responsibilities for argument passing are summarized in the following two tables. For the detailed rules that must be observed when passing parameters (in , inout, out, or return value) to a CORBA object implementation, see "Argument passing considerations for C++ bindings".
As an overall requirement when allocating and deallocating argument storage, the storage allocation rules for the specific type must be followed. Specifically, for strings, sequences, and arrays or for aggregate types composed of these types, use the associated memory allocation and dealloaction functions. For string types, use the string_alloc(), string_dup(), and string_free() methods. For sequence types, use the allocbuf() and freebuf() methods. For arrays, use the T_alloc(), T_dup() and T_free() methods. The memory deallocation responsibilities of the client can be minimized by stack allocation and with the use of the _var types whenever possible. When an argument is passed or returned as a pointer type, do not pass or return a NULL pointer value.
The following table shows the storage access responsibilities for argument passing.
Data Type | Inout | Out | Return |
short | 1 | 1 | 1 |
long | 1 | 1 | 1 |
long long | 1 | 1 | 1 |
unsigned short | 1 | 1 | 1 |
unsigned long | 1 | 1 | 1 |
unsigned long 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 pointer | 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 |
valuetype | 7 | 7 | 7 |
For definitions of the numerical values in the previous table, refer to the table below.
Case | Description |
1 | The caller allocates all of the necessary storage, except the storage that can be encapsulated and managed within the parameter itself. For inout parameters, the caller allocates the storage but does need not to initialize it. 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 first calls 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 of the object references embedded in other structures is performed automatically by the structures themselves. |
3 | 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 and 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 modify the values, the caller first must copy the returned instance into a new instance and then modify it. |
4 | For inout strings, the caller provides storage for both the input string and the char* pointing to it. Because the callee can deallocate the input strings 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 | The assignment or modification of an inout sequence or the any type might cause deallocation of owned storage before any reallocation occurs. This depends upon the state of the Boolean release parameter with which the sequence or the any type 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 both cases, the caller always must 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 modify any values, the caller must first copy the returned array instance into a new array instance, and then modify the new instance. |
7 | The caller allocates storage for the valuetype instance. For inout parameters, the caller provides an initial value. If the callee wants to reassign the inout pointer to a different valuetype instance, it first calls _remove_ref on the original input valuetype. To continue to use a valuetype instance passed in as an inout after the invoked operation returns, the caller first must invoke _add_ref on the valuetype instance. The caller is responsible for invoking _remove_ref on all out and return valuetype instances. The structures themselves reduce the reference counts using_remove_ref for all valuetype instances embedded in other structures. |