<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-2458916B-55B2-5E08-A825-4EBDB3503E67"><title>Class types</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Symbian platform uses four general kinds of class, and uses naming conventions to indicate to which kind a class belongs. </p> <p>The kinds are: </p> <ul><li id="GUID-D8338E4A-1EF1-5EFC-88EB-4709663F9A00"><p>value classes, or types, whose name begins with <codeph>T</codeph>. They do not own any external object, either directly (by pointer) or indirectly (by handle). </p> </li> <li id="GUID-04DA916C-7E54-519E-BDAA-70FD40464051"><p>heap-allocated classes, whose name begins with <codeph>C</codeph>. All such classes are derived from class <codeph>CBase</codeph>. </p> </li> <li id="GUID-ACB1D77E-7256-50D1-AFDB-2E9C70EC1662"><p>resource classes, whose name begins with <codeph>R</codeph>. <codeph>R</codeph> objects are handles to a real resource which is maintained elsewhere. </p> </li> <li id="GUID-B97DC80C-5261-5774-A6FF-531595770631"><p>interface classes, whose name begins with <codeph>M</codeph>. They define abstract protocol definitions that are implemented by derived classes. </p> </li> </ul> <p>These types are closely related to the requirements of cleanup support, which is described in more detail in <xref href="GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita">Cleanup requirements</xref>. </p> <section id="GUID-A2117C25-ED3E-59E9-AAFA-B057837130B7"><title>Value types: T classes</title> <p>The most fundamental types are value types. These are given type, or class, names beginning with <codeph>T</codeph>. </p> <ul><li id="GUID-6D34C2A2-FEA1-5E9F-9CBD-0E85DDB764B9"><p> <codeph>T</codeph> types contain their value. They do not own any external object, either directly (by pointer) or indirectly (by handle). </p> </li> <li id="GUID-A7A8D552-929D-50D1-83F0-19D92852C144"><p> <codeph>T</codeph> types may be allocated either on the stack (C++ automatic variables) or as members of other classes. </p> </li> </ul> <p>The consequences of these fundamental characteristics are explored below. </p> <p><b>Constructor</b> </p> <p>Many <codeph>T</codeph> types are simple enough not to need a constructor. Those that do, use the constructor to initialise member data. </p> <p><b>Copy constructor and assignment operator</b> </p> <p>A copy constructor (<codeph>TX(const TX&amp;)</codeph>) or assignment operator (<codeph>TX&amp; operator=(const TX&amp;)</codeph>) are rarely needed. This is because copying is always shallow, and almost always involves only a memberwise copy of the source <codeph>T</codeph> object to the destination. This is the default behaviour for the compiler-generated C++ copy constructor and assignment operator. </p> <p>These functions may be needed if the <codeph>T</codeph> 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 <codeph>TX&lt;32&gt;</codeph> to a <codeph>TX&lt;40&gt;</codeph> would require more sophistication than a bitwise copy, so a copy constructor and assignment operator would have to be explicitly coded. </p> <p><b>Destructor</b> </p> <p> <codeph>T</codeph> types have no C++ destructor. None is needed, because no external resources need to be cleaned up when a <codeph>T</codeph> object goes out of scope. </p> <p><b>Orphaning</b> </p> <p> <codeph>T</codeph> types may safely be orphaned on the stack. Orphaning implies that the memory is deallocated without calling the destructor. Because <codeph>T</codeph> types do not own external resources, no external resources can become inaccessible when a <codeph>T</codeph> object is orphaned. </p> <p><b>Function arguments</b> </p> <p> <codeph>T</codeph> types may be passed by value, as well as by reference, in function arguments. </p> <p><b>Data members</b> </p> <p> <codeph>T</codeph> types may contain other <codeph>T</codeph> type objects. In addition, they may contain <codeph>R</codeph> objects, or pointers to <codeph>C</codeph> objects, provided these objects are owned by another class or function, which is responsible for these objects’ cleanup. In practice, this rarely occurs. </p> <p><b>Built-in C++ types</b> </p> <p>All built-in C++ types satisfy the criteria for <codeph>T</codeph> classes. Built-in types are given <codeph>typedef</codeph> names beginning with <codeph>T</codeph>, e.g. <codeph>TInt</codeph>. </p> </section> <section id="GUID-D959B368-F735-5885-9D1F-1FB9B6B52810"><title>Standard class hierarchy: C classes and class CBase</title> <p>Most classes that are not <codeph>T</codeph> classes are <codeph>C</codeph> classes, which are derived, directly or indirectly, from class <codeph>CBase</codeph>. </p> <p> <codeph>CBase</codeph> -derived classes have the following properties: </p> <ul><li id="GUID-6C85FF48-ED87-577C-8F6E-A3DF2F2BF2C1"><p>they are allocated on the heap not on the stack, and not as members of other classes </p> </li> <li id="GUID-C38F15C6-BB1F-594B-880E-E91F6B2B5F6B"><p>the allocator used for this class hierarchy initialises all member data to binary zeroes </p> </li> <li id="GUID-6D320CFE-5146-5729-81BC-177A1D72AD8D"><p>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 </p> </li> <li id="GUID-92936C23-C4A4-5526-85B5-72B16EDD8D85"><p>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 <codeph>ConstructL()</codeph> function is used for aspects of construction which might leave </p> </li> <li id="GUID-8AB4B4B3-2BD6-5468-800A-FEC53CA269CC"><p>they have a virtual destructor, which is used for standard cleanup processing </p> </li> <li id="GUID-ED392BD1-22F4-5724-B2EE-A4CCEFD15E2F"><p>because of the virtual destructor, it is simple to support cleanup of <codeph>C</codeph> objects using the cleanup stack; additionally, because <codeph>C</codeph> objects are allocated on the heap, they <i>must</i> be cleaned up if a leave occurs: this imposes a requirement for cleanup consciousness when dealing with all <codeph>C</codeph> classes </p> </li> </ul> <p>The requirements of <codeph>C</codeph> classes are documented in <xref href="GUID-5EBA3C03-2E4E-5DBA-BB5B-0D40DAB3C39B.dita">Two Phase Construction</xref>. </p> </section> <section id="GUID-313E6618-D75E-56DE-952C-C8F78116360A"><title>Resource types: R classes</title> <p> <codeph>R</codeph> classes are proxies for objects owned elsewhere. There are two main motivations for this: </p> <ul><li id="GUID-2D062038-0D0C-5621-B8C4-F048DA2494A8"><p>the real object is owned by a server in a different thread or address space, or </p> </li> <li id="GUID-9FD2364F-E438-58D1-A149-CCE40B0FD925"><p>the real object’s implementation must be hidden from the client </p> </li> </ul> <p>The following are key characteristics of <codeph>R</codeph> objects: </p> <ul><li id="GUID-4F15304D-68BB-5D44-8368-739A94E0FE79"><p>they contain a handle that is used to pass on requests to other objects </p> </li> <li id="GUID-5EA19A65-928E-5182-8420-34DF63CC9AAC"><p>they are opened using an "open" function particular to the <codeph>R</codeph> class, and closed using a "close" function particular to the class. An <codeph>R</codeph> object must be closed once if it has been opened. Generally, the resource associated with an <codeph>R</codeph> object is closed automatically if the thread which opened the object terminates. </p> </li> <li id="GUID-C44F1410-5B08-5BE4-95F3-BCB83A25F847"><p>they may be freely bitwise copied </p> </li> <li id="GUID-52691656-81E8-5649-A9CA-86DE175D45AD"><p>they have no explicit constructor, destructor, copy constructor or assignment operator </p> </li> </ul> <p> <codeph>R</codeph> classes use a variety of protocols to meet these needs: </p> <ul><li id="GUID-EF4E2F44-15BB-5F47-B3BB-B5BC1C1336A1"><p>the nature of the handle may differ from <codeph>R</codeph> class to <codeph>R</codeph> class </p> </li> <li id="GUID-1C83B717-29EE-5AFA-9051-DF75BA12A425"><p>there is no common base class for all <codeph>R</codeph> classes </p> </li> <li id="GUID-9B8AA46E-0441-5F75-A7E6-63A8C1A7967E"><p>the initialisation function has a variety of names: also possible are <codeph>Open()</codeph>, <codeph>Create()</codeph>, <codeph>Allocate()</codeph>, etc. </p> </li> <li id="GUID-098D9747-C0BD-5866-B43F-B930100D1D46"><p>the termination function has a variety of names: also possible are <codeph>Close()</codeph>, <codeph>Destroy()</codeph>, <codeph>Free()</codeph>, etc. </p> </li> <li id="GUID-60F5ED1D-9D66-5BB2-B232-97AAD4B0DB07"><p>since <codeph>R</codeph> classes own external resources, there is a requirement for cleanup: this is handled in various ways depending on the class </p> </li> </ul> </section> <section><title>Inteface types: M classes</title> <p> <codeph>M</codeph> classes define abstract protocols, or interfaces. Concrete implementations of an interface defined by an <codeph>M</codeph> class are provided by derived protocol provider classes. </p> <p> <codeph>M</codeph> classes have the following restrictions: </p> <ul><li id="GUID-01C1BC0A-3C9F-5D28-8601-817B7180022B"><p>they should contain no member data </p> </li> <li id="GUID-DB75508B-E563-5D16-9687-2759E212BC5B"><p>they should not contain constructors or destructors, or overloaded operators such as <codeph>=</codeph>  </p> </li> </ul> <p> <codeph>M</codeph> classes often contain pure virtual functions that define a fully abstract interface. Some <codeph>M</codeph> classes implement some or all member functions, though within the restrictions given above. </p> <p> <codeph>M</codeph> classes are the only use of multiple inheritance on the Symbian platform. For details of this, see <xref href="GUID-9E0DCB19-5775-5E23-B758-163D747A71C9.dita">Multiple inheritance and interfaces</xref>. </p> </section> </conbody></concept>