Class types

Applications on the Symbian platform use four general kinds of class. The kinds are as follows:

• value classes, or types, whose name begins with T. They do not own any external object, either directly (by pointer) or indirectly (by handle).

• heap-allocated classes, whose name begins with C. All such classes are derived from class CBase.

• resource classes, whose name begins with R. R objects are handles to a real resource which is maintained elsewhere.

• interface classes, whose name begins with M. They define abstract protocol definitions that are implemented by derived classes.

These types are closely related to the requirements of cleanup support, which is described in more detail in Cleanup requirements.

The most fundamental types are value types. These are given type, or class, names beginning with T.

• T types contain their value. They do not own any external object, either directly (by pointer) or indirectly (by handle).

• T types may be allocated either on the stack (C++ automatic variables) or as members of other classes.

The consequences of these fundamental characteristics are explored below.

Many T types are simple enough not to need a constructor. Those that do, use the constructor to initialise member data.

A copy constructor (TX(const TX&)) or assignment operator (TX& operator=(const TX&)) are rarely needed. This is because copying is always shallow, and almost always involves only a memberwise copy of the source T object to the destination. This is the default behaviour for the compiler-generated C++ copy constructor and assignment operator.

These functions may be needed if the T class is a templated class, parameterised by an integer length, which is also contained as a member of the class. Then, copying or assigning a TX<32> to a TX<40> would require more sophistication than a bitwise copy, so a copy constructor and assignment operator would have to be explicitly coded.

T types have no C++ destructor. None is needed, because no external resources need to be cleaned up when a T object goes out of scope.

T types may safely be orphaned on the stack. Orphaning implies that the memory is deallocated without calling the destructor. Because T types do not own external resources, no external resources can become inaccessible when a T object is orphaned.

T types may be passed by value, as well as by reference, in function arguments.

T types may contain other T type objects. In addition, they may contain R objects, or pointers to C objects, provided these objects are owned by another class or function, which is responsible for these objects’ cleanup. In practice, this rarely occurs.

All built-in C++ types satisfy the criteria for T classes. Built-in types are given typedef names beginning with T, e.g. TInt.

Most classes that are not T classes are C classes, which are derived, directly or indirectly, from class CBase.

CBase-derived classes have the following properties:

• they are allocated on the heap—not on the stack, and not as members of other classes

• the allocator used for this class hierarchy initialises all member data to binary zeroes

• they are passed by pointer, or reference, and so do not need an explicit copy constructor or assignment operator unless there is clear intention that a particular class support copying

• they have non-trivial construction and, because of the possibility that a leave might occur during the construction process, a two-phase construction protocol is used, in which the C++ constructor is only used for aspects of construction which cannot leave, and a ConstructL() function is used for aspects of construction which might leave

• they have a virtual destructor, which is used for standard cleanup processing

• because of the virtual destructor, it is simple to support cleanup of C objects using the cleanup stack; additionally, because C objects are allocated on the heap, they must be cleaned up if a leave occurs: this imposes a requirement for cleanup consciousness when dealing with all C classes

The requirements of C classes are documented in Two Phase Construction.

R classes are proxies for objects owned elsewhere. There are two main motivations for this:

• the real object is owned by a server in a different thread or address space, or

• the real object’s implementation must be hidden from the client

The following are key characteristics of R objects:

• they contain a handle that is used to pass on requests to other objects

• they are opened using an "open" function particular to the R class, and closed using a "close" function particular to the class. An R object must be closed once if it has been opened. Generally, the resource associated with an R object is closed automatically if the thread which opened the object terminates.

• they may be freely bitwise copied

• they have no explicit constructor, destructor, copy constructor or assignment operator

R classes use a variety of protocols to meet these needs:

• the nature of the handle may differ from R class to R class

• there is no common base class for all R classes

• the initialisation function has a variety of names: also possible are Open(), Create(), Allocate(), etc.

• the termination function has a variety of names: also possible are Close(), Destroy(), Free(), etc.

• since R classes own external resources, there is a requirement for cleanup: this is handled in various ways depending on the class

M classes define abstract protocols, or interfaces. Concrete implementations of an interface defined by an M class are provided by derived protocol provider classes.

M classes have the following restrictions:

• they should contain no member data

• they should not contain constructors or destructors, or overloaded operators such as =

M classes often contain pure virtual functions that define a fully abstract interface. Some M classes implement some or all member functions, though within the restrictions given above.

M classes are the only use of multiple inheritance in the Symbian platform. For details of this, see Multiple inheritance and interfaces.