![]() |
The storage access and allocation responsibilities for argument passing are summarized in the two tables below. 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, the associated memory allocation and dealloaction functions must be used. For string types this means the use of string_alloc(), string_dup(), and string_free(), for sequence types this means the use of allocbuf() and freebuf() and for arrays this means the use of T_alloc(), T_dup() and T_free(). The memory deallocation responsibilities of the client can be minimized by stack allocation and the use of the _var types when that is possible. When an argument is passed or returned as a pointer type, a NULL pointer value should never be passed or returned.
Argument storage responsibilities
Data Type Inout Out Return 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 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 sequence 5 3 3 array, fixed 1 1 6 array, variable 1 6 6 any 5 3 3 For definitions of the numerical values in the above table, refer to the table below:
Argument passing cases
Case Description 1 Caller allocates all necessary storage, except that which may be encapsulated and managed within the parameter itself. For inout 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 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: in order to do so, the caller must first copy the returned instance into a new instance, then modify the new instance. 4 For inout strings, the caller provides storage for both the input string and the char* pointing to it. Because the callee may 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 For inout sequences and any's, 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 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 completion of a request, the caller is not allowed to modify any values in the returned storage: in order to do so, the caller must first copy the returned array instance into a new array instance, then modify the new instance.