Symbian OS Explained Effective C++ Programming for Smartphones phần 10 ppt

Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com... leave-Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com... Simpo PDF Merge and Split Un

Code Checklist

The following list is based on the internal Symbian Peer Review Checklist

Declaration of Classes

• A class should have a clear purpose, design and API

• An exported API class should have some private reserved declarationsfor future backward compatibility purposes

• The API should provide the appropriate level of encapsulation, i.e.member data hiding

• Friendship of a class should be kept to a minimum in order to preserveencapsulation

• Polymorphism should be used appropriately and correctly

• A class should not have exported inline methods

• A non-derivable class with two-phase construction should make itsconstructors and ConstructL() private

• const should be used where possible and appropriate

• Overloaded methods should be used in preference to default eters

param-• Each C class should inherit from only one other C class and haveCBaseas the eventual base class

• Each T class should have only stack-based member variables

• Each M class should have no member data

Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

• Header files should contain ”in-source” documentation of the purpose

of each class

• The inclusion of other header files should be minimized by usingforward declaration if required

• Header files should include the correct #ifndef #define

#endifdirective to prevent multiple inclusion

• The number of IMPORT_C tags should match the correspondingEXPORT_Ctags in the cpp file

Comments

• Comments should match the code

• Comments should be accurate, relevant, concise and useful

• Each class should have ”in-source” documentation of its purpose inheader file

• Each method should have ”in-source” documentation of its purpose,parameters and return values in the cpp file

Constructors

• A CBase-derived class does not need explicit initialization

• Member data of T and R classes should be explicitly initializedbefore use

• Member data should be initialized in the initializer list as opposed tothe body

• A C++ constructor should not call a method that may leave

• Two-phase construction should be used if construction can fail withanything other than KErrNoMemory

• NewL() and NewLC() methods should wrap allocation and struction where necessary

• Member pointers deleted outside the destructor should be set to NULL

or immediately re-assigned another value

• A destructor should not leave

Allocation and Deletion

• For a new expression, either use new (ELeave), or check the returnvalue against NULL if leaving is not appropriate

• For a call to User::Alloc(), either use AllocL(), or check thereturn value against NULL if leaving is not appropriate

• Objects being deleted should not be on the cleanup stack or referenced

by other objects

• C++ arrays should be de-allocated using the array deletion operator,delete [] <array>

• Objects should be de-allocated using delete <object>

• Other memory should be de-allocated using the methodUser::Free (<memory>)

Cleanup Stack and Leave Safety

• If a leaving method is called during an object’s lifetime, then theobject should either be pushed on to the cleanup stack or be held

as a member variable pointer in another class that is itself safe

leave-Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

held on the cleanup stack when a leaving method is called.

• Calls to CleanupStack::PushL() and CleanupStack::Pop()should be balanced (look out for functions that leave objects on thecleanup stack, such as NewLC())

• If possible, use the CleanupStack::Pop() and stroy() methods which take pointer parameters, because theycatch an unbalanced cleanup stack quickly

PopAndDe-• Where possible, use CleanupStack::PopAndDestroy() ratherthan Pop() followed by delete or Close()

• Local R objects should be put on the cleanup stack using ClosePushL(), usually after the object has been ”opened”

Cleanup-• Errors caught by a TRAP harness that are ignored must be clearlycommented and explained

• The code within a TRAP harness should be able to leave

• Error processing after a TRAP that ends with an unconditionalUser::Leave() with the same error code should be re-codedusing the cleanup stack

• Use the LeaveScan tool to check source code for functions that canleave but have no trailing L

Loops and Program Flow Control

• All loops should terminate for all possible inputs

• The bracing should be correct on if .else statements.

• Optimize loops by using the clearest type (do .while or while) in

• A switch statement should be used to indicate state control Eachcasestatement should contain only a small amount of code; largechunks of code should be moved into separate functions to maintainthe readability of the switch statement

CODE CHECKLIST 337

• There should be a default in every switch statement

• Flow control statements should be used rather than extra booleanvariables to manage program flow

• Bitmasks should be used properly (& to read, | to set, ∼ to reset)

• Unexpected events and inputs should be handled gracefully, i.e useerror returns, leaves or panics appropriately

• Hard-coded ”magic” values should not be used

• Logging statements should be informative and in useful places

• Code should be efficient, e.g do not copy things unnecessarily, donot create too many temporaries, do not use inefficient algorithms

• Casts should be in C++ style such as static_cast, pret_castor const_cast rather than in C style

reinter-• A cast should only be used where absolutely necessary and should bethe correct type for the expression

Descriptors

• Descriptor character size should be correct, i.e 8 bits for binary dataand ASCII-like text; 16 bits for explicitly Unicode text; no suffix fornormal text

• _L should not be used for literal data: use _LIT instead (except fortest code, etc.)

• Assignment to TPtr or TPtrC does not redirect the pointer; Set()

is required for that purpose

• HBufC::Des() and TBufC::Des() are not required to use theobject as an unwritable descriptor

Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

ment: these classes define assignment operators.

• Use AppendNum() or Num() to format a number instead ofTDes::AppendFormat()or Format()

• Use Append() instead of TDes::AppendFormat() or Format()

con-• Descriptors passed to asynchronous operations should persist untilthe operation completes, e.g do not use a stack-allocated descriptor

Containers

• The least-derived type of container should be used in declarations

• The initial size and granularity of the container should be appropriate

• All owned objects in the container should be destroyed (or ownershippassed) before the container is destroyed

• The appropriate container for the purpose should be used

• Thin templates should be used for any templated code

active object Responsible for issuing requests to

asynchronous service providers andhandling those requests on completion

Derives from CActive

8, 9

active scheduler Responsible for scheduling events to the

active objects in an event-handling program

8, 9

asynchronous service provider

A system, component or class, whichprovides a service asynchronously, typically

to an active object Asynchronous requestsare indicated by function calls with aTRequestStatusreference parameter

8, 9

backward compatibility

Updating a component in such a way thatclient code which used the original versioncan continue to work with the updated

version See also forward compatibility.

18

binary compatibility

Modifying a library in such a way that codewhich linked against the previous versioncan continue to run with the new versionwithout needing recompilation

18

C function In the context of Symbian OS, this refers to a

function with a trailing C in its name, e.g

NewLC() If successful, this type of functionleaves one or more objects on the cleanupstack when it returns

3Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

chunk A unit of memory allocation, where a linear

region of RAM is mapped into contiguouslogical addresses

13

clanger The Clangers are a race of highly-civilized,

small, bright pink, long-nosed,mouse-shaped persons who stand upright

on big flappy feet (seewww.clangers.co.uk

for more information)

throughout

cleanup stack Takes responsibility for cleaning up the

objects pushed onto it if a leaveoccurs

3

client interface function

A member function in a client-side session(or subsession) class that sends a specificmessage request to a server, identified by anopcode

11, 12

context switch A switch in execution between one thread

or process and another This involves savingthe context of the currently executing thread

or process (i.e its address space mappings)and restoring the context of the newlyexecuting thread or process

10, 11, 12

descriptor A string, so-called because it is

self-describing All descriptor classes derivefrom TDesC, which describes an area ofmemory used as either a string or binarydata

4, 5

descriptorize To marshal a flat data object, typically a

struct or T class, into a descriptor forinter-thread data transfer

6, 11, 12

DLL (dynamic link library)

Dynamic link libraries contain functionsthat are linked and stored separately fromthe programs that use them

13

DLL export table An area in the DLL which lists the DLL

addresses of exported items On Symbian

OS, these items are indexed byordinal

13

E32 Collective term for the base components of

Symbian OS

ECOM A generic framework in Symbian OS from

v7.0 for use with plug-in modules

14

GLOSSARY 341

emulator An implementation of Symbian OS hosted

on a PC running Microsoft Windows

Compare with target hardware.

13

entry point A function called when a DLL is loaded or

attached by a thread or process In Symbian

OS, the function E32Dll() is usuallycoded as the entry point

13

EPOC, EPOC32 Earlier names for Symbian OS Rumors that

this stood for ‘Electronic Piece of Cheese’

are unconfirmed

exec call A call to the kernel via a software interrupt

(see this useful paper by John Pagonis formore detailswww.symbian.com/developer/

techlib/papers/userland/userland.pdf)

10

F32 Collective term for the components making

up the Symbian OS file server

FEP (Front-End Processor)

Allows the input of characters by a user, forexample, by handwriting recognition orvoice, and converts the input transparentlyinto text

13

file server The server thread that mediates all file

system operations All application programsthat use files are clients of this thread

11

flat buffer A dynamic buffer using flat storage, i.e a

single segment of memory (see also

segmented buffer).

7

forward compatibility

Updating a component in such a way thatcode which works with the new version alsoworks with the original version See also

backward compatibility.

18

framework A component that allows its functionality to

be extended by plug-in modules, sometimesknown as framework extensions Theframework loads the extensions as required

at runtime

13, 14

framework extension

Provides plug-in functionality to aframework, typically by implementinginterfaces defined by that framework OnSymbian OS, a framework extension isimplemented as a polymorphic DLL

14Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

freeze The process of fixing the association

between name and ordinal, for functionsexported from a DLL It is a colloquialreference to a def file (see moduledefinition file)

13

import library (.lib)

A static library that an application programuses at link time to resolve references tosymbols defined in a corresponding DLL

Information from this library concerning thelocation of export functions in the DLL isincluded in the application’s executablefile

13

IPC (Inter-Process Communication)

Used by clients to communicate without-of-process servers on Symbian OS

11, 12

just-in-time (JIT) Just-in-time debugging is used to attach a

debugger to a process at the point at which

it is about to terminate

15

kernel The core of the operating system It manages

memory, loads processes and libraries andschedules threads for execution

10

L function A function with a trailing L in its name, e.g

NewL(), which indicates that it may leave

2

leave Symbian OS exception handling A function

leaves when User::Leave()is called Itcauses a return to the current trap harness

2

mixin An interface class for ”mixing in” with

primary base classes, and the only form ofmultiple inheritance encouraged onSymbian OS

1

module definition file (.def)

A file that specifies an ordinal value for eachnamed function or data item to be exportedfrom a DLL It is used to insert ordinalinformation into the DLL export table,allowing exports to be accessed by ordinalfrom clients of the DLL

13, 18

null thread The lowest-priority thread in the system,

belonging to the kernel It only runs whenthere is no higher priority thread to run andusually puts the phone into power-savingmode

10

GLOSSARY 343

OOM (out-of-memory)

An error caused when the available RAMhas been exhausted, preventing further heapallocation

throughout

panic A run-time exception on Symbian OS that

terminates the current thread Panics tend to

be caused when assertion statementsfail

A DLL that provides plug-in functionality toanother program by implementing a definedinterface These are typically known asplug-ins and are loaded dynamically byanother program (usually a framework)using RLibrary::Load() Compare with

shared library.

13, 14

process The unit of memory protection on Symbian

OS One user process may not accessanother’s memory A process may containone or more threads

10

recognizer A plug-in that examines data from a file and

returns its data (MIME) type, if recognized

13

request semaphore

A semaphore associated with a thread,which is used to indicate the completion of

an asynchronous request

8, 9

request status An object that indicates the completion

status of a request, represented byTRequestStatus

8, 9

ROM Read-Only Memory This is permanent

memory that can be read but not (easily)written to It holds code and data that mustpersist when the phone is switched off OnSymbian OS, it is usually identified as the Z:

drive

13

SDK Software Development Kit

segmented buffer

A dynamic buffer using segmented storage,which consists of a doubly-linked list ofsegments Segments are added when thebuffer needs to expand and removed when

it is compressed See also flat buffer.

7Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

server call A call to the kernel in which the kernel

server thread runs on behalf of the userprogram See this useful paper by JohnPagonis for more information

www.symbian.com/developer/techlib/

papers/userland/userland.pdf

11, 12

session The channel of communication between a

client and a server

11, 12

shared library A library that is loaded by the DLL loader

when an executable that links to it is

loaded Compare with polymorphic

DLL.

13

static library Other executable code may link to this

library to resolve references to exportedfunctions Builds with a lib

extension

13

target hardware A phone handset running Symbian OS

(compare with emulator)

10, 13

thin template An idiom used to minimize code bloat from

the use of standard C++ templates

19

thread-local storage (TLS)

A machine word of memory that may beused to anchor information in the context of

a DLL or a thread Used instead of writablestatic data, which is not supported forSymbian OS DLLs

13

TRAP , TRAPD Trap harness macros within which

leaving code may be executed and anyleaves ”caught” Can be likened to acombination of try and catch in standardC++

2

two-phase construction

An idiom used on Symbian OS to ensurethat an object can be initialized safely usingleaving code

4

UID (unique identifier)

A unique 32-bit number used in acompound identifier to identify an object,file type, etc When users refer to ”UID”

they often mean UID3, the identifier for aparticular program

13

UID type A set of three UIDs that, in combination,

identify a Symbian OS object

13

GLOSSARY 345

UID1 The first UID in a compound identifier (UID

type) It identifies the general type of aSymbian OS object and can be thought of as

a system-level identifier; for exampleexecutables, DLLs and file stores are alldistinguished by UID1

13

UID2 The second UID in a compound identifier

(UID type) It is used to distinguish within atype (e.g between types of DLL) and can bethought of as an interface identifier Forexample, static interface and polymorphicinterface DLLs are distinguished by UID2

13

UID3 The third UID in a compound identifier

(UID type) It identifies a particular subtypeand can be thought of as a project identifier(for example, UID3 may be shared by allobjects belonging to a given program,including library DLLs, framework DLLs,and all documents)

13

Unicode A 16-bit character set that is used to assign

unique character codes for a wide range oflanguages

5, 6Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

Bibliography and Online Resources

Books on Symbian OS

Richard Harrison (2003)

Symbian OS C++ for Mobile Phones

Publisher: John Wiley and Sons LtdISBN: 0470856114

Richard Harrison (2004)

Symbian OS C++ for Mobile Phones Vol 2

Publisher: John Wiley and Sons LtdISBN 0470871083

Martin Tasker, Jonathan Allin, Jonathan Dixon, Mark Shackman, TimRichardson and John Forrest (2000)

Professional Symbian Programming: Mobile Solutions on the EPOC Platform

Publisher: Wrox PressISBN: 186100303XLeigh Edwards and Richard Barker (2004)

Developing Series 60 Applications: A Guide for Symbian OS C++ Developers

Publisher: Addison WesleyISBN: 0321227220

J Jipping (2002)

Symbian OS Communications Programming

Publisher: John Wiley and Sons LtdISBN: 0470849487

Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com

Martin Fowler (1999)

Refactoring: Improving the Design of Existing Code

Publisher: Addison WesleyISBN: 0201485672Martin Fowler and Kendall Scott (2003)

UML Distilled: A Brief Guide to the Standard Object Modeling

Publisher: Addison WesleyISBN: 0321193687Stanley Lippman (1996)

Inside the C++ Object Model

Publisher: Addison WesleyISBN: 0201834545Scott Meyers (1997)

Effective C++: 50 Specific Ways to Improve Your Programs and Designs,

2ndEdition

Publisher: Addison WesleyISBN: 0201924889Scott Meyers (1996)

More Effective C++: 35 New Ways to Improve Your Programs and Designs

Publisher: Addison WesleyISBN: 020163371XBjarne Stroustrup (2000)

The C++ Programming Language, Special Edition

Publisher: Addison WesleyISBN: 0201700735Herb Sutter (1999)

Exceptional C++

Publisher: Addison WesleyISBN: 0201615622

Symbian OS on the Internet

Symbian Press Website