APIs Covered in the Book

Now we've reviewed the type of hardware on which EPOC operates, the base facilities for constructing programs, and the event-handling system including the client-server framework.

EPOC's APIs divide into categories corresponding to those we used for types of program:

q The kernel exposes an API through the user library

q System servers expose APIs through their client interfaces

q Application engines expose APIs to the applications that use them

q Middleware components are APIs in perhaps the purest and simplest sense

q Other API types such as device drivers, sockets protocol implementations, printer drivers etc. are associated with particular system components

Here are the major components in EPOC R5:

These divide into several broad groupings:

Group	Description
Base	Provides the fundamental APIs for all of EPOC, which I've described in this chapter.
Middleware	Graphics, data, and other components to support the GUI, engines, and applications.
EIKON	The system GUI framework including the Shell application
Applications	Application software can be divided into GUI parts (which use EIKON) and engines (which don't deal with graphics). Some applications are simply thin layers over middleware components: others have substantial engines.
Communications	Industry-standard communications protocols for serial and sockets-based communication, dial-up networking, TCP/IP, and infrared.
Language systems	The Java run-time environment, and the complete OPL development and run-time environment.
EPOC Connect	Communications protocols to connect to a PC, and services such as file format conversion, data synchronization for contacts, schedule entries and e-mail, clipboard synchronization, printing to a PC-based printer.

The table below shows the main C++/C APIs that we will be covering in the book. It introduces the issue of naming conventions for EPOC APIs — which, quite frankly, are not as clean as I would like. I've used

q A friendly title, which I'll normally use in the book, unless I need to be more precise

q The DLL name: add .dll to this for the DLL name to use at runtime, and add .lib for the import library that you must specify in your .mmp file at build time.

q The top-level project name in the source tree: this is the main system used internally by Symbian to refer to APIs, and often corresponds to the DLL name — though not always, since some projects produce more than one DLL, while others produce none at all. In any case only a very few components are shipped with source in the developer SDKs.

Throughout the book I'll use sometimes one form, sometimes another. You can always tell which form I'm using, because the presentation is different for each form. For good measure, I've included a category for each API (base, middleware etc.).

I've also included the header file naming convention. You'll find the corresponding header file(s) in \epoc32\include\, with the names indicated. In the case of the EPOC C standard library, the header files are isolated into their own directory — \epoc32\include\libc\.

Title	DLL	Source	Group	Headers	Description
User library	euser	E32	Base	e32def.h, e32std.h, e32base.h, e32*.h	Utility and kernel-object APIs. See Chapter 5 for strings and descriptors, Chapter 6 for resource cleanup, Chapter 20 for active objects, Chapter 21 for the principles behind client-server framework, Chapter 22 for an example server.
File server	efsrv	F32	Base	f32file.h	File and device management. See Chapter 7.
GDI	gdi	GDI	Middleware	gdi.h	Abstract graphical device interface. See Chapter 11 for intro to drawing, Chapter 14 for other facilities with the emphasis on device independence.
Window server	ws32	WSERV	Middleware	w32std.h	Shares screen, keyboard and pointer between all applications. See Chapter 11 and Chapter 12 for details, along with coverage of CONE.
CONE	cone	CONE	Middleware	coe*.h	Control environment: works with window server to enable applications to use controls.
Stream store	estor	STORE	Middleware	s32*.h	Stream and store framework and main implementations. See Chapter 7.
C standard library	estlib	STDLIB	Middleware	libc\*.h	Provides functions found in POSIX-compliant C programming environments, mostly as thin layers over base and sockets server APIs. See Chapter 28.
Resource files	bafl	BAFL	Middleware	ba*.h	Once grandly titled 'basic application framework library', its most useful aspect is resource files, though it also contains other APIs. See Chapter 2 and Chapter 9.
Application architecture	apparc	APPARC	Middleware	apa*.h	Governs file formats and application launching. Briefly mentioned in Chapter 7 and Chapter 9.
EIKON	eikon	EIKON	EIKON	eik*.h	The system GUI. See Chapter 9 and Chapter 15 for main write-up, and information throughout the book.
Sockets server	esock	ESOCK	Comms	es_*.h	Sockets-based comms using protocols such as TCP/IP, infrared and others. See Chapter 23.
Telephony server	etel	ETEL	Comms	etel*.h	Voice, data, address book etc. on landline or mobile phones and modems. See Chapter 23.

Some of the shaded boxes in the diagram of the components of EPOC R5 are parts of the corresponding API — for example, client-server etc. are provided by the user library, and zooming is provided by the GDI. Other shaded boxes aren't C++/C APIs — for example, the emulator, or Java language system.

I'll give you a good head start on the main APIs in this book. The SDK contains much additional valuable information on both the APIs I do cover, and those I don't.

How the Applications use the APIs

I'll end this chapter with a quick tour through the EPOC R5 application suite, showing how each application uses the EPOC APIs, to whet your appetite for the chapters that follow.

If you're interested in how many servers might be running in a live EPOC system, keep your eyes open as you read through the table. Most of the servers are mentioned there explicitly.

I've generally used the source tree naming convention for APIs used.

Office Applications

Word	Naturally, Word focuses on text APIs. ETEXT and FORM provide the re-usable rich text APIs — ETEXT for content, FORM for formatted views and printing. LEXICON (a server) is used for spell checking.
Sheet	Sheet is supported by two specialist components: GRID providing a spreadsheet grid view, and CHART, which draws its chart view.
Data	Data uses DBMS to provide underlying relational data management. Although DBMS supports relational data with multiple tables, the Data application is constrained to a single table, which makes the application easier to use, and easier to design and implement.
Spell	Spell re-uses the LEXICON engine, and provides a simple GUI.
Jotter	Jotter is a modified form of the Data application, using the same EPOC components.

Personal Information Management Applications

Contacts

The contacts application uses two important re-usable components. The CNTMODEL server manages the shared contacts database. CONTACUI provides EIKON-based user interface, which any application can use to select and manipulate contacts.

Contacts are stored in a relational database, whose format is sufficiently flexible to allow for user-definable contacts attributes.

Agenda

Agenda uses the AGNMODEL server to manage shared agenda files. Agenda uses rich-text entries, managed by FORM and ETEXT. Agenda files use permanent file stores directly — not the relational database manager.

Time

TIME's underlying engine is EALWL, the alarm and world server. If you want to set an alarm, or find out city information, use EALWL.

Communications Applications

Email

For low-level communications, Email uses TCP/IP and other protocols provided by the sockets server ESOCK. Email integrates directly with the telephony server ETEL to pick up incoming SMS messages, and to send and receive faxes. Email integrates with dial-up networking and maintains a connection status display.

A server is used to control all message store operations. Multiple clients may be simultaneously active. Incoming messages may be added to the store while client applications are running.

Email uses so-called message transfer modules (MTMs) to provide flexibility in supporting new GUIs (other than EIKON), new message types (such as news) and new protocols (like IMAP).

Web

Web uses the same low-level communications technology as Email. The application architecture is used to launch non-HTML documents. A server implements a shared page and image cache.

Comms

The old-style Comms app uses an application engine including a general-purpose script interpreter. Comms uses the C32 communications server directly, without reference to the dial-up networking provided for TCP/IP and sockets protocols.

Summary

In this chapter we've surveyed the component parts of the EPOC system. W've seen:

q The impact of hardware on the design of EPOC and applications

q The four system component types — kernel, applications, servers, and engines

q Privilege, process, and DLL boundaries

q The difference between a .exe, a .dll, and .prn, .prt and .app files

q Using DLLs for EPOC applications allows multiple applications to run in one process for embedded documents

q DLL optimizations for EPOC — link by ordinal, address sharing, and lack of writable static

q Launching applications and servers using .exes

q Kernel and device driver overviews

q How EPOC handles memory

q Event handling is at the core of EPOC — using a combination of active objects and a client/server framework to allow non-preemptive multitasking

q Communications between client and server through messages and inter-thread read and write

q The main C/C++ APIs

In the next chapter, we'll look at EPOC's use of object-oriented techniques, the support that the C++ language provides, and that EPOC adds, to aid application development.