doc/idl/language-bindings/c++/specification

   1 General
   2 =======
   3
   4 Each IDL namespace (as opposed to an interface, struct, etc. namespace)
   5 is mapped to a C++ header file and a directory.  The name of the
   6 directory is the name of the namespace; the name of the file is the
   7 namespace name, followed by ".h".  The header file and the directory
   8 are both part of the same directory; the former does not go in the
   9 latter.  The directory contains sub-IDL-namespaces; if there are no
  10 such namespaces, the implementation is permitted, but not required, to
  11 create an empty directory.
  12
  13 Each sub-IDL-namespace's header file is #included from its parent
  14 header file, so that #including the top-level header file shall be
  15 sufficient to access any descendent namespace.
  16
  17 Each header file shall contain protection against being #included
  18 multiple times.  This protection may not interfere with that of any
  19 other namespace.
  20
  21 All identifiers and preprocessor symbols beginning with _IDL_CPP_ are
  22 reserved for use by the language binding.
  23
  24 Types
  25 =====
  26
  27 IDL types are mapped to C++ types as follows:
  28
  29   IDL Type                C++ Type
  30   ========                ========
  31
  32   bool                    uint8_t
  33   octet                   uint8_t
  34   short                   int16_t
  35   ushort                  uint16_t
  36   int                     int32_t
  37   uint                    uint32_t
  38   long                    int64_t
  39   ulong                   uint64_t
  40   fshort                  float
  41   flong                   double
  42   char                    uint8_t (UTF8)
  43
  44 FIXME: currently char simply acts as octet; should it refer to an
  45 actual character, and thus be uint32_t?  If so, then unless the
  46 language supports UTF8 natively, an array of char would still be an
  47 array of octets, which could be confusing...  Alternatively, get rid
  48 of char as a basic type, and use a typedef of octet to indicate that
  49 this particular octet is UTF8.
  50
  51 Namespaces
  52 ==========
  53
  54 IDL namespaces are mapped directly to C++ namespaces.  Symbols
  55 declared inside a struct or interface which are not methods or
  56 non-const data members will go into a parallel namespace, which is
  57 the type-namespace name with "_ns" appended.
  58
  59 Enumerations
  60 ============
  61
  62 As the size of a native C++ enum type is not guaranteed, and since
  63 they are not type-safe or namespace-safe, IDL enums are mapped to C++
  64 structs.  Each enumeration value is declared inside the struct as an
  65 anonymous enum value, and there is a _val entry which is an unsigned
  66 integer of the smallest type that can hold the IDL enum size.
  67
  68 Bitfields
  69 =========
  70
  71 An IDL bitfield is mapped to a C++ struct using field width
  72 specifiers on the members.  Integral members are mapped directly to
  73 C++ unsigned integers of the smallest type that can hold the IDL
  74 bitfield size, with a field size specifier.
  75
  76 When a bitfield is used as the type of a bitfield entry, it cannot be
  77 directly mapped, as C++ does not allow non-integral types to have
  78 field size specifiers.  Instead, get and set methods are provided to
  79 pack and unpack the data, and the contents of the bitfield type are
  80 directly inlined in the enclosing bitfield.  If the field name is foo
  81 and the type is Foo, then the methods will be "Foo get_foo() and
  82 set_foo(Foo foo)".  If a field name begins with "set_" or "get_", it
  83 will be preceded with an underscore for the field itself (but not for
  84 the set or get methods).  Thus, a field called set_foo in IDL would
  85 become _set_foo, but a get method (if required) would be get_set_foo,
  86 not get__set_foo.  The underscore prefix happens regardless of
  87 whether the field requires get and set methods.
  88
  89 With an embedded bitfield, the inlined fields have the sub-bitfield
  90 name prefixed to the field name.  Thus, if a bitfield Foo with fields
  91 a and b is included in a bitfield Bar as fields c and d, then Bar will have
  92 fields c_IDLNS_a, c_IDLNS_b, d_IDLNS_a, and d_IDLNS_b, and methods
  93 set_c(Foo), Foo get_c(), set_d(Foo), and Foo get_d().  The IDLNS is
  94 ugly, but there's no way I know of to use a C++ namespace mechanism
  95 without introducing unwanted padding (even __attribute__((packed))
  96 will byte-align a substruct).
  97
  98 Likewise, embedded enumerations cannot use the actual enumeration
  99 struct as a C++ bitfield member; they are treated as a simple
 100 integers instead.  Get and set methods are not needed, as enums will
 101 convert to integers, but they may be added in the future to provide a
 102 type-safe alternative to direct assignment.
 103
 104 Objects
 105 =======
 106
 107 A reference to an object has the name of the type, with no pointer or
 108 reference marker.  If uninitialized, they default to NULL.  Methods
 109 are called in the same way as on a C++ class, using the dot, not the
 110 arrow.  To increment an object's reference count, call the retain()
 111 method.  To decrement it, call the release() method.  Weak references
 112 and autorelease pools will be added later.
 113
 114 Classes
 115 =======
 116
 117 The implementor of a class must #include the generated .h file for
 118 the class in a public: portion of the class definition.  The class's
 119 constructor must call init_iface() before any object references to
 120 the object are used.  The generated footer.cc file must be included
 121 in exactly one non-header file.  It is recommended that this be the
 122 file in which the methods are defined, so that they can be inlined by
 123 the stubs; however, the only requirement is that it have access to
 124 the class definition and any interface headers the implemented
 125 interfaces reference.