orb2 for C++ Reference Release 3.8

Transcription

1 orb2 for C++ Reference Release 3.8

2

3 orb2 for C++ Reference Subject Reference materials for developing applications with orb2 for C++. Software Supported orb2 for C/C++ Revision History Release 3.0 September 1996 Release 3.0 March 1997 PDF version January 1998 Release 3.4 March 2001 Rebranded September 2001 Release 3.5 April 2003 Release 3.6 August 2004 Release 3.7 June 2005 Release 3.8 February 2008

4 2AB, Inc. disclaims the implied warranties of merchantability and fitness for a particular purpose and makes no express warranties except as may be stated in its written agreement with and for its customer. In no event is 2AB, Inc. liable to anyone for any indirect, special or consequential damages. The information and specifications in this document are subject to change without notice. Consult your 2AB, Inc. marketing representative for product or service availability. U.S. Government Restricted Rights. The Software Program(s) and Documentation furnished under this Agreement were developed at private expense and are provided with Restricted Rights. Any use, duplication, or disclosure by and for any agency of the U.S. Government shall be subject to the Restricted Rights applicable to commercial computer software under FAR Clause or DFAR Clause or any successor thereof. Copyright by 2AB, Inc. All Rights Reserved. Trademarks The 2AB logo is a registered trademark of 2AB, Inc. 2AB, explorer, ilock, ilock Security Services, jlock, orb2, orblock, weblock and Xcon are trademarks of 2AB, Inc. Microsoft, Windows, Windows NT, Windows 2000 and Windows XP are registered trademarks of the Microsoft Corporation. OMG, Object Management Group, OMG Interface Definition Language (IDL), Unified Modeling Language and UML are trademarks of the Object Management Group. CORBA and IIOP are registered trademarks of the Object Management Group. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. HP-UX is a registered trademarks of the Hewlett-Packard Company. Apache and Tomcat are trademarks of The Apache Software Foundation. AIX and Domino are trademarks of the International Business Machines Corporation in the United States or other countries or both. iplanet, J2EE, J2SE, Java, JavaScript, JavaServer Pages, JKD, Solaris, Sun and Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other brand or product names are trademarks or registered trademarks of their respective companies or organizations.

5

6

7 Contents Contents Figures Tables About This Document Chapter 1 Technical Support xiii Mapping IDL to C The Any Type Insertion into Any Extraction from Any Handling Untyped Values Additional Operations on the Any Class Constructors, Destructor and Assignment CORBA::Any Parameter Passing and Memory Management Array Types Array_slice Memory Allocators for Arrays Array Parameter Passing and Memory Management Basic Types Basic Types Parameter Passing and Memory Management Constants Enumeration Types Enum Parameter Passing and Memory Management User Exceptions Interface Types Interface inheritance Interface Parameter Passing and Memory Management Interface_proxy Interface_sk A_var Assignment and Conversion Operators Scoped Names Sequence Types Unbounded Sequence Bounded Sequence Sequence Parameter Passing and Memory Management String Types string Parameter Passing and Memory Management Struct Types struct Parameter Passing and Memory Management orb2 for C++ Reference orb2 Release 3.8 vii

8 Contents 1.12 System Exception Types Union Types union Parameter Passing and Memory Management Chapter 2 Class Library 2.1 CORBA::BOA CORBA::Current CORBA::Environment CORBA::Exception CORBA::Object CORBA::Object_sk CORBA::Object_var CORBA::ORB CORBA::String_var CORBA::SystemException CORBA::TCKind CORBA::TypeCode CORBA::UserException DAIS_Trader Extended Object Adapter Deprecated Classes DAIS_Ecs DAIS_Seq DAIS_Thread Chapter 3 Static Functions in CORBA Namespace 3.1 CORBA::is_nil CORBA::ORB_init CORBA::release CORBA::string_alloc CORBA::string_dup CORBA::string_free Chapter 4 Deprecated General Purpose API Functions 4.1 DAIS_AcquireMutex, DAIS_ReleaseMutex DAIS_add_relocator DAIS_do_events DAIS_exception_reloc DAIS_extract_relocator DAIS_InitMutex and DAIS_FreeMutex DAIS_init_properties DAIS_InitStaticECRec, DAIS_InitStaticSQRec, DAIS_InitStaticMutex DAIS_register_pin, DAIS_unregister_pin DAIS_register_pin_notification, DAIS_list_pin, DAIS_free DAIS_relocator_init DAIS_init_thread, DAIS_end_thread DAIS_set_timer, DAIS_clear_timer viii orb2 Release 3.8 orb2 for C++ Reference

9 Contents 4.14 DAIS_timer Chapter 5 Globals 5.1 DAIS_capsule_name DAIS_capsule_obj DAIS_hostname DAIS_manobj_obj Chapter 6 Service Interface Listing 6.1 DAIS::ExtendedObject DAIS::Capsule DAIS::ManagedObject DAIS::Management Factory LifeCycleObject NodeMgr Relocator RelocDBase Terminated Appendix A System Exceptions & _minor error codes Appendix B System Exceptions & _minor error code Groupings Index orb2 for C++ Reference orb2 Release 3.8 ix

10 Contents x orb2 Release 3.8 orb2 for C++ Reference

11 Figures Figure 1.1 Interface Inheritance Relationship Figure 1.2 Interface_proxy Inheritance Figure 1.3 Interface_sk Inheritance Figure 2.1 CORBA::Exception Inheritance Figure 2.2 CORBA::Object Inheritance Figure 2.3 CORBA::Object_sk Inheritance Figure 2.4 CORBA::SystemException Inheritance Figure 2.5 CORBA::UserException Inheritance Figure 2.6 Extended Object Hierarchy Figure 4.1 Enhanced Object Reference Figure 6.1 DAIS::ExtendedObject Inheritance Tree orb2 for C++ Reference orb2 Release 3.8 xi

12 Tables Table 1.1 Function Signature Table 1.2 Fixed Types - Arrays Table 1.3 Variable Types - Arrays Table 1.4 Basic Types Mapping Table 1.5 Caller/Callee Responsibilities - Basic Types Table 1.6 Parameter Mapping to Interface Operations Table 1.7 Sequence Parameters Table 1.8 String Parameters Table 1.9 Fixed Types - Structs Table 1.10 Variable Types - Structs Table 1.11 Fixed Types - Unions Table 1.12 Variable Types - Unions Table 2.1 Parameter Descriptions Table 2.2 Shutdown Categories Table 2.3 orb2 Services Table 4.1 Property Strings Table 4.2 Parameters orb2 for C++ Reference orb2 Release 3.8 xii

13 About This Document This document describes the mapping of IDL to C++, class library facilities, exception handling, general purpose API functions, global expressions, skeleton to stub interfaces and system exception codes and groupings. Technical Support Your feedback is important to us. Please provide input to the 2AB Technical Support Staff. You can communicate comments to and request help from the Technical Support Staff via the following methods: Telephone U.S. or Canada: (Toll Free) All Other Countries: orb2 for C++ Reference orb2 Release 3.8 xiii

14 About This Document Technical Support xiv orb2 Release 3.8 orb2 for C++ Reference

15 Chapter 1 Mapping IDL to C++ This chapter describes how orb2 maps IDL to its equivalent C++ signatures. Each IDL type is described, along with its parameter passing modes, where appropriate, and details of memory management on the client and server sides of an invocation. 1.1 The Any Type The IDL type any is a universal union type whose instance can hold values of any type expressible in IDL, including the built-in types, such as long, and all user-defined types. The discriminant that identifies the type of its contained value is a TypeCode object. In orb2 for C++, these two types are mapped to the classes CORBA::Any and CORBA::TypeCode, respectively. To support dynamically-allocated Any objects, orb2 also supports a class CORBA::Any_var. Like other _var types, an instance of Any_var is responsible for destroying the contained Any object when it is updated or itself destroyed. The CORBA::Any class allows an application to insert and extract values of any type. orb2 for C++ uses C++ operator overloading to define multiple insertion (<<=) and extraction (>>=) operators, which ensure that the correct object is associated with the inserted value, and that extraction attempts only succeed if the contained value is of the expected type. Insertion and extraction are described in Section and Section 1.1.2, respectively. For user-defined IDL types, the insertion and extraction operators are defined as non-member functions, but some of the operators for built-in types are defined as member functions of CORBA::Any. In this description, they are all described as if they were non-member functions. You can use the same insertion and extraction operators with Any_var objects. orb2 accomplishes this either via conversion operators that convert the Any_var object to its contained Any object, or by redefining the operators as members of Any_var. In exceptional circumstances, it is also possible to bypass the normal insertion and extraction rules to set or get values of arbitrary type. However, this use is not recommended Insertion into Any An application can insert a value of any type into an Any object, associating it with the correct TypeCode, using the <<= operator. For IDL-defined enum types and the built-in scalar types (except any, char, boolean and octet), the general form of the insertion operator is void operator <<= (CORBA::Any&, T); where T is any of the above types. For example CORBA::Any a; CORBA::Long value; a <<= value; orb2 for C++ Reference orb2 Release

16 Mapping IDL to C Insertion into Any For IDL-defined struct, union, sequence types and the built-in type any, there are two insertion operators void operator <<= (CORBA::Any&, const T&); void operator <<= (CORBA::Any&, T*); The first operator stores a copy of the supplied object in the Any, letting the application to manage the original. The second makes the Any responsible for managing the object. The calling application should not attempt to destroy it. For object references of interface type F, there are pairs of operators of the form void operator <<= (CORBA::Any&, F_ptr); void operator <<= (CORBA::Any&, F_ptr*); The first operator duplicates the supplied object reference. The second, non-copying form, takes ownership of the supplied reference. The application should not release or make any other use of the object reference after calling this operator. There are similar operators for object references of the generic type Object of the form void operator <<= (CORBA::Any&, CORBA::Object_ptr); void operator <<= (CORBA::Any&, CORBA::Object_ptr*); An application can use C++ casts to associate an object reference with a TypeCode for any of the interface types it satisfies, or the generic type Object. For example, given interface Base interface Derived : Base} we can write CORBA::Any a1; CORBA::Any a2; CORBA::Any a3; Derived_ptr obj =...; a1 <<= value; a2 <<= static_cast <Base_ptr> (value); a3 <<= static_cast <CORBA::Object_ptr> (value); After executing this code, the three Any objects each contain duplicates of the original object reference, described by the TypeCodes for interface Base, interface Derived and Object, respectively. For other types, it is not always possible for the C++ compiler to distinguish the appropriate type. This is because two or more IDL types may map to the same C++ type. This may be the case for the IDL types char, boolean and octet. In each of these cases, the application must guide the insertion using one of these operations void operator <<= (CORBA::Any&, CORBA::Any::from_char); void operator <<= (CORBA::Any&, CORBA::Any::from_boolean); void operator <<= (CORBA::Any&, CORBA::Any::from_octet); where each of the helper types, from_char, from_boolean and from_octet, has a constructor taking a value of the appropriate type. This example shows the operator for the octet type CORBA::Any a; CORBA::Octet value = 0x3A; a <<= CORBA::Any::from_octet (32); 1-2 orb2 Release 3.8 orb2 for C++ Reference

17 1.1.2 Extraction from Any Mapping IDL to C++ The operators for char and boolean are handled similarly. Both bounded and unbounded string types map to the C++ char* type. To insert an unbounded string into an Any, use the operator void operator <<= (CORBA::Any&, const char*); To insert a bounded string into any Any, use the operator void operator <<= (CORBA::Any&, CORBA::Any::from_string); where the helper type from_string has a constructor taking a string value and a maximum length. This example shows both forms CORBA::Any a1; CORBA::Any a2; const char* value = "Hello, world!"; a1 <<= value; a2 <<= CORBA::Any::from_string (value, 32); After executing this code, both Any objects contain the same text value, but in a1, it is described by a TypeCode for an unbounded string, while in a2, it is described by a TypeCode for a string of maximum length 32. An application must also use helper types to insert values of IDL-defined array types into an Any. This is because an array is mapped to a type that is indistinguishable from a pointer to an object of its element type. For an array type typedef array <T, 42> A; the compiler generates the operator void operator <<= (CORBA::Any&, const A_forany&); where the generated helper type A_forany has a constructor that takes an array and a Boolean parameter nocopy, indicating whether the supplied array should be copied or adopted. The Boolean parameter defaults to FALSE, meaning that the array should be copied. For example CORBA::Any a1; CORBA::Any a2; A_slice* value = new T[42]; a1 <<= CORBA::Any::A_forany (value); a2 <<= CORBA::Any::A_forany (value, 1); After executing this code, the Any object a1 contains a copy of the supplied array, while a2 takes ownership of the array. The application should not attempt to destroy the array directly Extraction from Any An application can attempt to extract a value of any type into an Any object, associating it with the correct TypeCode, using a >>= operator. If the value in the Any object is associated it with the correct TypeCode, the operator updates its second argument and returns TRUE. Otherwise, the operator simply returns FALSE. For IDL-defined enum types and the built-in scalar types (except any, char, boolean and octet), the general form of the extraction operator is CORBA::Boolean operator >>= (const CORBA::Any&, T&); where T is any of the above types. For example orb2 for C++ Reference orb2 Release

18 Mapping IDL to C Extraction from Any CORBA::Any a; CORBA::Long value; if (a >>= value) cout << "Value is " << value; } For IDL-defined struct, union, sequence types and the built-in type any, the operator is of the form void operator >>= (const CORBA::Any&, T*&); This operator dynamically creates a copy of the contained value and stores its address in the supplied pointer. For object references of interface type F, the operator is of the form CORBA::Boolean operator >>= (const CORBA::Any&, T_ptr&); This operator updates its second parameter with a duplicate of the contained object reference. There is a similar operator for object references of the generic type Object, of the form CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Object_ptr &); This operator only succeeds if the TypeCode is of the generic type Object. However, it is often the case that an object reference in an Any object is associated with the TypeCode that describes its most derived type, whereas the application may only need to treat it as a generic Object. To allow such a reference to be widened in this way, there is an additional extraction operator CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Any::to_object&); where the helper type to_object has a constructor taking a reference to an object of type CORBA::Object_ptr. This succeeds if the Any object contains any kind of object reference. For example, given interface Base interface Derived : Base we can write CORBA::Any a; Derived_ptr derived_obj; Base_ptr base_obj; CORBA::Object_ptr raw_obj; a >>= derived_obj; a >>= base_obj; a >>= CORBA::Any::to_object (raw_obj); assuming that the Any object contains a reference to an interface Derived object. After executing this code, the object references derived_obj and raw_obj each contain duplicates of the original object reference, but base_obj remains undefined. For other types, it is not always possible for the C++ compiler for distinguish the appropriate type (since, for example, two or more IDL types may map to the same C++ type). This may be the case for the IDL types char, boolean and octet. In each of these cases, the application must guide the object using one of these operations 1-4 orb2 Release 3.8 orb2 for C++ Reference

19 1.1.2 Extraction from Any Mapping IDL to C++ CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Any::to_char); CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Any::to_boolean); CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Any::to_octet); where each of the helper types, to_char, to_boolean and to_octet, has a constructor taking a reference to an object of the appropriate type. For example, the operator for the octet type is CORBA::Any a; CORBA::Octet value; a >>= CORBA::Any::to_octet (value); The operators for char and boolean are handled similarly. Both bounded and unbounded string types map to the C++ char* type. To extract an unbounded string from an Any, use this operator CORBA::Boolean operator >>= (const CORBA::Any&, char*&); To extract a bounded string from an Any, use this operator CORBA::Boolean operator >>= ( const CORBA::Any&, CORBA::Any::to_string&); where the helper type to_string has a constructor taking a reference to a char* and a maximum length. This example shows both forms CORBA::Any a; char* unbounded = 0; char* bounded = 0; a >>= unbounded; a >>= CORBA::Any::to_string (bounded, 32); After executing this code, unbounded contains a non-null pointer if the Any object is described by a TypeCode for an unbounded string, while bounded contains a non-null pointer if the Any object is described by a TypeCode for an bounded string of maximum length 32. An application must also use helper types to extract values of IDL-defined array types from an Any. This is because an array is mapped to a type that is indistinguishable from a pointer to an object of its element type. For an array type typedef array <T, 42> A; the compiler generates the operator CORBA::Boolean operator >>= (const CORBA::Any&, A_forany&); where the generated helper type A_forany has a default constructor. For example CORBA::Any a; A_forany value; a >>= value; Assuming that the Any object contains an array of the correct type, the object value now points to that array. The array remains owned by the Any object; it is not deleted when value is deleted. orb2 for C++ Reference orb2 Release

20 Mapping IDL to C Handling Untyped Values Handling Untyped Values Under some circumstances, the type-safe insertion to CORBA::Any is not sufficient. For example, since all strings are mapped to char*, regardless of whether they are bounded or unbounded, it is not possible to create a CORBA::Any with a specific TypeCode for a bounded string through the type-safe CORBA::Any interface. This is also the case in a situation in which data types are read from a file in binary form and used to create values of type CORBA::Any. For these cases, the class provides a constructor with an explicit TypeCode and generic pointer Any(TypeCode_ptr tc, void* value, Boolean rel = CORBA_FALSE); This constructor will duplicate the given TypeCode pseudo reference. If the rel parameter is TRUE, the Any object assumes ownership of the storage pointed to by the value parameter. No assumptions should be made by an application regarding the continued lifetime of the value parameter once it has been passed this way. If the rel parameter is set to FALSE, the default case, the Any assumes that the application will manage the memory pointed at by value Additional Operations on the Any Class There are three additional unsafe operations defined on the CORBA::Any class void replace (TypeCode_ptr tc,void* value,boolean rel = FALSE); This function is intended to be used with types that cannot be used with the type-safe insertion interface and is, therefore, similar to the constructor described in Section The existing TypeCode is released and the value storage de-allocated, if necessary. The TypeCode function parameter is duplicated. If rel is TRUE, the Any object assumes ownership for the storage pointed to by the value parameter. If rel is FALSE, the Any object assumes that the caller will manage the memory occupied by the value. TypeCode_ptr type() const; This returns a TypeCode_ptr pseudo object reference to the TypeCode associated with the CORBA::Any. Like all object reference return values, the caller must release the reference when it is no longer needed. const void* value() const; This returns a pointer to the data stored in the CORBA::Any. If the CORBA::Any has no associated value, the function returns NULL. The return type may be cast to the explicit type as determined from the TypeCode Constructors, Destructor and Assignment The default constructor creates a CORBA::Any with a TypeCode of type tk_null, and no value. The copy constructor calls _duplicate() on the TypeCode_ptr of its CORBA::Any parameter and deep-copies the parameter s value. The assignment operator releases its own TypeCode_ptr and de-allocates storage for the current value, if necessary, then duplicates the TypeCode_ptr of its CORBA::Any parameter and deep-copies the parameter s value. The destructor calls release() on the TypeCode_ptr and de-allocates storage for the value if necessary. 1-6 orb2 Release 3.8 orb2 for C++ Reference

21 1.1.6 CORBA::Any Parameter Passing and Memory Management Mapping IDL to C CORBA::Any Parameter Passing and Memory Management CORBA::Any types using IDL // IDL interface XYZ any func(in any arg1, inout any arg2, out any arg3); This maps to the following C++ function signature; see Table 1.1. CORBA::Any* XYZ::func (const CORBA::Any& arg1, CORBA::Any& arg2, CORBA::Any*& arg3); Table 1.1 Function Signature Type Description in inout out return The caller declares and initializes the Any and passes this to the function. The callee has only read access to that Any and its encapsulated TypeCode and value. The caller declares and initializes the Any. The callee will reallocate the Any, which involves a possible reallocation of its value element depending on the setting of the release parameter, and may change the TypeCode for the Any. If the Any is passed with release FALSE, no freeing of the initial value takes place, which may cause a potential memory leak. The caller passes an un-initialized pointer to the function. The server constructs an Any and replaces that pointer. The caller is responsible for destroying the returned Any using delete. The callee is not allowed to return a NULL pointer. Following completion of the request, the client is not allowed to modify any value in the returned storage. To do so, it must first copy the returned instance into a new instance. The caller simply declares a pointer of the CORBA::Any Type. The callee creates a new instance of that Any and returns it. The caller pointer now has a valid value and is responsible for its destruction using delete. For example // IDL struct MyStruct long l_mem; short s_mem; interface XYZ any func ( in any arg1, inout any arg2, out any arg3 ); // C++ orb2 for C++ Reference orb2 Release

22 Mapping IDL to C Array Types // caller side void Test () CORBA::Any in, inout, *out, *res; // set up the in param in <<= 54321L // set up the inout param MyStruct a_struct; a_struct.l_mem = ; a_struct.s_mem = 200; inout <<= a_struct; // now call the function res = TestObj->func( in, inout, out ); // use out and res // now tidy up delete out; delete res; } // callee side CORBA::Any* ServerImplementation::func(const CORBA::Any& in, CORBA::Any& inout, CORBA::Any*& out) CORBA::Long lval; CORBA::Short sval; Mystruct* ms; if ( in >>= sval ) cout<< "in param contains a short = " << sval << endl; } else if ( in >>>= lval ) cout<< "in param contains a long = " << lval << endl; } if ( inout >>>= ms ) cout << "inout param is a struct" << endl; cout << "l_mem = " << ms->l_mem << endl; cout << "s_mem = " << ms->s_mem << endl; } // now setup out and return, copies of in and inout params out = new CORBA::Any( inout ); return new CORBA::Any( in ); } 1.2 Array Types Arrays are mapped into regular C++ arrays and in these cases they present special problems for the type-safe CORBA::Any mapping described later. To facilitate the use of arrays with the CORBA::Any mapping, the CORBA compiler provides, for each array type, a distinct C++ type whose name consists of the array name followed by the suffix _forany. These types are made distinct to allow functions to overload them. Like the Array _var type the Array _forany type allows access to the underlying array type. Unlike Array _var types, the Array _forany type does not delete the storage of the underlying array upon its own destruction. This is because the CORBA::Any mapping retains storage ownership. 1-8 orb2 Release 3.8 orb2 for C++ Reference

23 1.2.1 Array_slice Mapping IDL to C++ The interface for the Array _forany type is identical to that of the Array _var type, but a separate definition is always produced, making it distinguishable from other types for the purpose of function overloading. Arrays are mapped to the corresponding C++ array definition allowing the definition of statically initialized data using the array If the array element is a string or object reference, the mapping uses the same type as for structure members. Assignment to an array element will release the storage associated with the old value. In function call signatures, the mapping differentiates between array types that are of fixed-length and those that are variable-length in the same way that struct is differentiated. Variable-length arrays are defined to be those arrays that have variable-length elements; for example // IDL typedef float FloatArry[10]; typedef string StrArry[10]; typedef string Str3D[1][2][3]; // C++ FloatArry f1; StrArry v1; Str3D m1; Str3D m2; f1[1] = PI; f1[0] = f1[1]; v1[1] = v1[2]; // free old storage, copy m1[0][1][2] = m2[0][1][2]; // free old storage, copy In this example, the last two assignments result in the storage being automatically released before the value from the right-hand side is copied Array_slice To provide a consistent signature mapping for arrays of varying dimensions an additional type is defined called an Array_slice. This is an array with all the dimensions of the original except the first one. A typedef is generated by the CORBA compiler to define this type. The name of the slice typedef consists of the name of the array type followed by the suffix _slice. For example // IDL typedef long LongArray[4][5]; // C++ typedef CORBA::Long LongArray[4][5]; typedef CORBA::Long LongArray_slice[5]; Memory Allocators for Arrays For dynamic allocation of arrays, you must use the following functions so that consistent internal constructor/destructor methodologies are established. These functions are provided as part of the compiler output at the same scope as the array itself. For example, for an array T orb2 for C++ Reference orb2 Release

24 Mapping IDL to C Array Parameter Passing and Memory Management // C++ T_slice* T_alloc(); void T_free( T_slice* ); T_slice* T_dup( T_slice*); The T_alloc() function dynamically allocates an array, or returns a NULL pointer if it cannot perform the allocation. The T_dup function dynamically allocates a new array with the same size as its array argument, copies each element of the argument array into the new array and returns a pointer to it. If allocation fails, a null pointer is returned. The T_free function deallocates an array that was allocated with T_alloc or T_dup. Passing a null pointer to T_free is acceptable and results in no action being performed Array Parameter Passing and Memory Management This IDL provides an example of the passing of array parameters in an Interface operation // IDL interface XYZ typedef short Fixed[2][2]; typedef string Vary[2][2]; Fixed func1( in Fixed a1, inout Fixed a2, out Fixed a1); Vary func2( in Vary v1, inout Vary v2, out Vary v3 ); It maps to the following C++ signatures typedef CORBA::Short Fixed_slice[2]; typedef CORBA::String_var Vary_slice[2]; XYZ::Fixed_slice* XYZ::func1( const XYZ::Fixed a1, XYZ::Fixed a2, XYZ::Fixed a3 ); XYZ::Vary_slice* XYZ::func2( const XYZ::Vary v1, XYZ::Vary v2, XYZ::Vary_slice*& a3 ); Note There are significant differences in the parameter passing modes for return and out types between the Fixed and Variable types. See Table 1.2 and Table 1.3. Table 1.2 Fixed Types - Arrays Type Description The caller sets all the array elements and passes the array to the function. in inout Note For Visual C++ on Windows NT, the in parameter must be cast to a pointer to the first const element. See the comment in example code for example of type declaration. The callee may access array elements but may not modify them in any way. The caller sets all the array elements and passes the array to the function. The callee may modify any or all array elements, replacing them with new values orb2 Release 3.8 orb2 for C++ Reference

25 1.2.3 Array Parameter Passing and Memory Management Mapping IDL to C++ Table 1.2 Fixed Types - Arrays (Continued) Type Description out return The caller declares an array of this type and may or may not initialize it before passing it to the function. The callee sets all the array elements to valid values. The caller declares an array slice pointer variable and assigns it to the result of the function call: The callee returns a valid instance of the array The callee is not allowed to return a null pointer The caller is responsible for releasing the returned storage using T_free() Upon 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 (using T_dup()) the returned array instance into a new instance, then modify the new instance. Table 1.3 Variable Types - Arrays Type Description The caller sets all the array elements and passes the array to the function. in Note For Visual C++ on Windows NT, the in parameter must be cast to a pointer to the first const element. See the comment in example code for example of type declaration. The callee may access array elements but may not modify them in any way. inout out The caller sets all the array elements and passes the array to the function. The callee may modify any or all array elements, replacing them with new values. The caller declares an array slice pointer of this type and may or may not initialize it before passing it to the function by reference. The callee sets the pointer to point to a valid instance of the array: The callee is not allowed to return a null pointer The caller is responsible for releasing the returned storage using T_free() Upon 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 (using T_dup()) the returned array instance into a new array instance, then modify the new instance orb2 for C++ Reference orb2 Release

26 Mapping IDL to C Array Parameter Passing and Memory Management Table 1.3 Variable Types - Arrays (Continued) return Type Description The caller declares an array slice pointer variable and assigns it to the result of the function call The callee returns a valid instance of the array The callee is not allowed to return a null pointer The caller is responsible for releasing the returned storage using T_free() Upon 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 (using T_dup()) the returned array instance into a new instance, then modify the new instance. For example // IDL interface Test typedef string bar[2][2]; bar func( in bar a1, inout bar a2, out bar a3 ); // caller side Test::bar in; Test::bar inout; Test::bar_slice* out; Test::bar_slice* res; // Note use of cast for String_var in[0][0] = (const char*)"in param 00"; in[0][1] = (const char*)"in param 01"; in[1][0] = (const char*)"in param 10"; in[1][1] = (const char*)"in param 11"; inout[0][0] = (const char*)"inout param 00"; inout[0][1] = (const char*)"inout param 01"; inout[1][0] = (const char*)"inout param 10"; inout[1][1] = (const char*)"inout param 11"; // Note for Visual C++ on NT the in parameter must be cast to a // pointer to the first const element. For array bar the type // bar_nt_cast is declared as follows: // typedef const CORBA::String_var(*bar_nt_const)[2] res = obj->func( in, inout, out ); // Now uses values in res and out print_array( out ); print_array( res ); // clean up bar_free( out ); bar_free( res ); // callee side Test::bar_slice* Test::func( const Test::bar in, Test::bar inout, Test::bar_slice*& out ) Test::bar_slice* res = bar_alloc(); out = bar_alloc(); 1-12 orb2 Release 3.8 orb2 for C++ Reference

27 1.2.3 Array Parameter Passing and Memory Management Mapping IDL to C++ } // Read only on in display_array( in ); out[0][0] = (const char*)"out 00"; out[0][1] = (const char*)"out 01"; out[1][0] = (const char*)"out 10"; out[1][1] = (const char*)"out 11"; res[0][0] = (const char*)"res 00"; res[0][1] = (const char*)"res 01"; res[1][0] = (const char*)"res 10"; res[1][1] = (const char*)"res 11"; return res; To facilitate the management of pointers to array types, the mapping also provides an additional class for each array type. This type, named by adding the suffix _var to the original type name, automatically deletes the pointer when an instance is destroyed. This follows the usual pattern for _var classes, except that it overloads operator[] instead of operator-> and the constructor and assignment operator take a pointer to an array_slice as a parameter rather than the normal T* // T_base is the element type // contained in the array typedef T_base T[i][j][k]; typedef T_base T_slice[j][k]; class T_var : public _var T_slice* _ptr; public : T_var() _ptr = NULL; } T_var(T_slice* p ) _ptr = p; } T_var( const T_var& v ); T-var() if (_ptr!= NULL ) delete _ptr; } T_var& operator=(t_slice* p) if(_ptr!= p) if( _ptr!= NULL ) T_free ( _ptr ); _ptr = p; } return *this; } T_var& operator=(const T_var& v) if( this!= &v ) if( _ptr!= NULL ) T_free( _ptr ); _ptr = T_dup(v._ptr); } return *this; } T_slice& operator[](ulong index); const T_slice& operator[]( ULong index ) const; // conversion operators operator T_slice *(); operator const T_slice* const(); // T_var class for array orb2 for C++ Reference orb2 Release

28 Mapping IDL to C Basic Types Each read-write attribute maps to a pair of overloaded C++ functions (both with the same name) one to set the attribute s value and one to get the attribute s value The set function takes a parameter with the same type as the attribute, while the get function takes no parameters and returns the same type as the attribute An attribute marked read-only maps to only one C++ function of the get variety Parameters and return types for attribute functions obey the same parameter passing rules as for regular operations For example // IDL interface XYZ attribute long distance; // C++ class XYZ CORBA::Long distance() const; // get the attribute void distance(corba::long); // in an invocation XYZ_ptr obj = //... get one somehow CORBA::Long x; x = obj->distance(); x = x +1; obj->distance(x); 1.3 Basic Types IDL Basic Types map to C++ as shown in Table 1.4. // set the attribute Note The mapping of the IDL boolean type defines only the values 1(TRUE) and 0(FALSE); other values produce undefined behavior. As a convenience for the user the orb2 ORB defines CORBA_TRUE and CORBA_FALSE with such values that may be used in such circumstances. Table 1.4 Basic Types Mapping IDL C++ Equivalent short long unsigned short unsigned long float double char CORBA::Short CORBA::Long CORBA::UShort CORBA::ULong CORBA::Float CORBA::Double CORBA::Char 1-14 orb2 Release 3.8 orb2 for C++ Reference

29 1.3.1 Basic Types Parameter Passing and Memory Management Mapping IDL to C++ Table 1.4 Basic Types Mapping (Continued) IDL C++ Equivalent boolean octet CORBA::Boolean CORBA::Octet Each IDL Basic Type is mapped to a typedef in the CORBA module. This is because some types, such as short or long, may have different representations on different platforms, the CORBA definitions will reflect the appropriate representation. Except for boolean, char and octet, the mappings for the Basic Types are distinguishable for the purposes of overloading. That is, you can safely write overloaded C++ functions on CORBA::Short, CORBA::UShort, CORBA::Long, CORBA::ULong, CORBA::Float and CORBA::Double Basic Types Parameter Passing and Memory Management To elaborate on the mapping of Basic Types as parameters to Interface operations, the following IDL example shows where the Basic Type short is used. The other Basic Types follow the same semantics. // IDL interface XYZ short func ( in short arg1, inout short arg2, out short arg3 ); This generates the following C++ signature. The caller/callee responsibilities are listed in Table 1.5. class XYZ CORBA::Short func ( CORBA::Short arg1, CORBA::Short& arg2, CORBA::Short& arg3 ); Table 1.5 Caller/Callee Responsibilities - Basic Types Type in inout out return Description The caller passes a parameter value to the function directly. The callee may use this value. The caller sets a value and passes this to the function by reference. The callee may use this value before replacing it with a new value. The caller declares a variable of this type and may or may not initialize it before passing it to the function. The callee will overwrite this with a valid value. The caller declares a variable of this type and assigns it to the result of the function call. The callee establishes a value for the parameter and returns its value. orb2 for C++ Reference orb2 Release

30 Mapping IDL to C Constants For example // caller side CORBA::Short in; CORBA::Short inout; CORBA::Short out; CORBA::Short result; in = 24; inout = 32; result = XYZ_objref->func( in, inout, out ); // use result, out and inout value cout << "result = " << result << "inout = " << inout << "out = " << out << endl; // callee side CORBA::Short XYZ::func( CORBA::Short in, CORBA::Short& inout, CORBA::Short& out ) inout += in + 20; out = 54; return ( in + out ); } 1.4 Constants IDL constants are mapped directly to a C++ constant definition that may or may not define storage, depending on the scope of the declaration. The orb2 CORBA compiler will make the necessary adjustments as follows Constants defined at global scope will also be statically initialized Constants defined at module or interface scope will be declared at that scope, but will be initialized once only in the corresponding m_< interface file name>.cpp generated file For example, this IDL //IDL File Xyz.idl const string name = "name constant"; interface XYZ const float pi = 3.142; will map to //C++ static const CORBA::Char* name = "name constant"; class XYZ public: static CORBA::Float pi; Additionally, in the stub generated file, m_xyz.cpp, it will map to const CORBA::Float XYZ::pi = 3.142; 1-16 orb2 Release 3.8 orb2 for C++ Reference

31 1.5 Enumeration Types Mapping IDL to C Enumeration Types An IDL enum maps to a corresponding C++ type definition. In orb2, an additional dummy constant is added to force the C++ compiler to use 32 bits for the values declared to be of the enumerated type: //IDL enum Color RED, BLUE, GREEN // C++ enum Color RED, BLUE, GREEN, _color_force_32bit = 0x7fffffff Enum Parameter Passing and Memory Management This is the same as for Basic Types. 1.6 User Exceptions Each IDL user exception is mapped to a C++ class that derives from the standard CORBA::UserException class described in Section The generated class contains a public data member for each IDL member. Unless an IDL member is of type string or some interface type, the corresponding C++ data member has the normal C++ type corresponding to the IDL types. For members of type string, the C++ data member has type CORBA::String_var and for members of some interface type A, the C++ data member has type A_var. These rules ensure that the generated class is self-managing, that is, that deleting some instance of the class will automatically free all data owned by the instance. In this respect, user exceptions are very similar to variable-length structs (see Section 1.11). The generated class also contains a default constructor a copy constructor if the IDL exception has any members, an initializing constructor with one parameter for each exception member an assignment operator a destructor a member function _get_id that returns the exception s repository identifier as a constant string (see Section 2.4), a static member function _narrow that takes a pointer to any CORBA::Exception instance. If the supplied pointer is non-null and references an object whose actual type is the current class, this function returns a pointer of that type to the referenced object. Otherwise, it returns the null pointer (see also Section 2.13). For example // IDL exception BadType string reason; long value; // C++ class BadType : public CORBA::UserException public: CORBA::String_var reason; orb2 for C++ Reference orb2 Release

32 Mapping IDL to C Interface Types CORBA::Long value; BadType(): CORBA::UserException() } BadType (const BadType&); BadType ( const char* _reason, CORBA::Long _value ); ~BadType() } BadType& operator= (const BadType&); virtual const char* _get_id() const; static BadType* _narrow (CORBA::Exception* ex); IDL user exceptions are thrown and caught using the standard C++ exception mechanism. For example, given // IDL interface A void my_op(); a server implementation might include // C++ void A_Impl::my_op() if (problem_detected()) throw BadType ("problem detected!", 999); } normal_code(); and a client implementation might include // C++ A_ptr a_ptr = get_a(); try a->my_op();; } catch (BadType& bad_type) cerr << "BadType: " << bad_type.reason << ", " << bad_type.value << endl; } 1.7 Interface Types An Interface is mapped to a C++ class that contains the public definitions of types, constants, operations and exceptions defined in the Interface. All such classes are derived from a common base class CORBA::Object. See Section 2.5. The class generated by the stub compiler is made abstract and, therefore A program cannot create or hold an instance of an Interface class or derive from an Interface class directly. The Interface class may be represented by an object reference type which has the same characteristics as an Interface class pointer. Initial creation of object references is the responsibility of the implementation class. You may obtain copies of references from a variety of sources, but most frequently from the DAIS_Trader 1-18 orb2 Release 3.8 orb2 for C++ Reference

33 1.7.1 Interface inheritance Mapping IDL to C++ Figure 1.1 shows the complete inheritance relationship for an Interface. CORBA::Object Interface CORBA::Object_sk Interface_proxy Interface_sk Implementation of Interface Interface inheritance Figure 1.1 Interface Inheritance Relationship The derived classes Interface_proxy and Interface_sk represent the actual accessor classes on the client and server side respectively. See Section and Section In the abstract base Interface class, the following IDL // IDL interface Person Person func( in Person arg1 ); maps to the class declaration class Person:public virtual CORBA::Object public : static Person_ptr _duplicate( Person_ptr obj ); static Person_ptr _narrow( CORBA::Object_ptr ); static Person_ptr _nil(); static Person_ptr _import(char*, char*, char*); virtual _timeout(corba::longval)} virtual CORBA::Boolean poll_voucher(voucher* v); // The user defined operation virtual Person_ptr func(person_ptr arg1) = 0; protected: Person(); virtual ~Person(); private: Person(const Person& ); void operator=(const Person& ); An object reference to that Interface would be of type Person_ptr and programs that obtain valid instances of such a pointer may invoke any of the predefined operations on that Interface. For example // declare objref for Interface Person Person_ptr obj1; Person_ptr obj2; orb2 for C++ Reference orb2 Release