Finding your way around

The Symbian OS Library is a large documentation set. To help you find what you need, this page provides an introduction to its contents. Not all sections of the documentation are relevant to all types of user of the OS, so this introduction is divided into a few groups as follows:

• OS structure and APIs describes the sections that provide the core description of the operating system and how to work with it, including the Symbian OS reference and Symbian OS guide.

• Newcomers to Symbian OS describes the sections that provide an introduction to Symbian OS for those working with it for the first time

• Maintenance and upgrading describes the sections intended for those moving between releases of Symbian OS

The core information about the services that Symbian OS offers, and how to use them, is found in three sections:

• Symbian OS reference provides an item by item description of the classes and other types that make up the APIs

• Symbian OS guide describes the architecture and functionality of the OS, and provides guides on using their APIs

• Symbian OS Tools And Utilities describes the tools for developing and building programs

To make development easier, further sections provide supplementary information:

• Examples describe example programs that illustrate how to use the APIs

• FAQ Knowledgebase provides answers to frequently asked developer questions, together with other useful tips

• Symbian OS Glossary defines terms and key concepts

Symbian OS is a large system, containing hundreds of classes and thousands of member functions. Like most complex systems, it is easiest to approach by dividing it into large areas, and gradually narrowing your focus down to the areas that are most important to your tasks. This Symbian OS guide and Symbian OS reference use large divisions called subsystems. For example, the Application Engines subsystem contains all the APIs that can be used to manipulate data for the standard applications such as Contacts. Subsystems are in turn composed of components which provide libraries and header files that programs can use. One way to explore the OS is to first get familiar with the subsystems, and then drill down into the components.

Alternatively, if you know the name of the API that you are interested in, the easiest way to get to its reference page is to use the Index tab in the HTML Help version of the documentation, which lists all the APIs alphabetically. Alternatively, click on Index in the title bar of any page to go to lists of the APIs divided into categories, such as classes, functions, and constants. See Using the indexes for more information.

The following sections describe the guide, reference, and other sections in more detail.

The reference contains three sections:

• C++ component reference describes the C++ types that provide operating system services to programs. This is described in more detail below.

• Resources reference: Symbian OS defines its own resource language used to define user interface structures, localisable text, and other static data. Some parts of the OS provide resource definitions that can be used by other programs. These are described in this reference section.

• System panic reference documents the panics that system components can produce. A panic is an error code raised by a component in response to a programming error, such as passing an illegal parameter value. This reference section describes the meaning of these error codes.

The C++ component reference lists the operating system's components, grouped together by subsystem. Within each section, a reference page for each API item is provided, organised alphabetically. The following shows the beginning of a typical reference page, in this case for the class RDir.

As you can see the reference page for RDir is divided into sections:

• Location: the header file, located in the kit's epoc32\include directory, which declares the class. Your project should include this header to use the class.

• Link against: the library containing the class. Your project should link to this library to use the class.

• Description: describes the purpose and use of the class

• Derivation: names and briefly describes any base classes for the class

• Members: an alphabetical list of class members. The members declared in the class itself are given first, then the members provided by any base classes.

A reference page then describes each class member in turn. The members are grouped into the following sections:

• Construction and destruction: this section describes the class constructors, factory functions, and destructors.

• Member functions

• Member classes and structs

• Member enumerations

• Member type definitions

• Member data

The reference pages show only the APIs that are intended for use, so, for example, private data members and internal functions not exported by libraries are not shown.

In most cases, APIs are stable and intended for use in released phones. However, if this is not the case, then the documentation provides interface status information. This is one of the following categories:

prototype Interface is experimental. May be used in development kits and tools, and in prototype phones for development and evaluation purposes, but not in phones released to end-users. deprecated Interface is deprecated and is available for backward compatibility reasons only. Interface may in future be withdrawn. removed Interface is no longer supported. test Interface is reserved for reference/test components and must not be included in a licensee device.

There is one other type of Symbian OS-specific information that you will see on reference pages, which is platform security capability information. In order to protect devices against malicious programs, some sensitive system functions require the calling program to have permission, expressed as a capability setting, to use them. The documentation for such functions has a Capability section that tells you what is required. For example:

Capability: Drm

indicates that the calling program must have the capability called Drm. For more information, see the Platform security section.

The capabilities for some functions are conditional on the argument values passed to them. If this is case, the capability is described as Dependent, and is usually followed by a description of the condition.

The Symbian OS guide provides introductory documents to the system as a whole, followed by subsystem-by-subsystem guides to the components in the OS.

The documentation for a subsystem contains how-to guides, which have titles of the form "Using component-name". These guides usually provide a brief overview of the classes in the API that the component offers, and show the key ways to use these classes.

Symbian OS software development requires you to be familiar with a number of tools and development practices. The C++ development processes provides a quick walkthrough of the essentials, from defining a software project, to working with the emulator to develop, debug, and test software on a Windows PC, to the final steps of building and deploying on target hardware.

The Symbian OS Tools And Utilities provides the full detail on the Symbian OS tools. For many the most frequently used sections will be the Build tools guide and Build tools reference, which explain the project files required for Symbian OS programming, and how to build for the various native and emulated targets. It also explains the other tools which support your development, including the resource file format and compiler, bitmap files, installation package files, and help files.

The FAQ Knowledgebase contains answers written by Symbian's developer and partner support groups to common questions and problems. The FAQ Knowledgebase is also available on the Symbian Developer Network.

FAQs are listed in date order from most recent to oldest. Note older FAQs may not apply to the current version of the OS. You can see for what version of the OS the FAQ was created from its Platform sub-heading.

The Examples section gives instructions for building and using the large set of C++ examples that accompany the Symbian OS Library. Projects include examples demonstrating the use of fundamental Symbian OS classes, essential techniques and idioms that can be employed in developing Symbian OS applications, and many examples showing how to use particular Symbian OS C++ APIs.

Note that in licensee customised versions of the Symbian OS Library, the generic Symbian OS examples may be replaced by phone specific examples.

Example code is provided for illustrative and demonstration purposes, and should not be assumed to be useable as product code.

There are some sections aimed at those developing on Symbian OS for the first time.

Application Development Tutorial is a walkthrough of the key knowledge that you'll need to begin development. It uses a full featured example program on the UIQ platform.

In the Symbian OS guide, useful topics are Essential idioms, which describes the distinctive programming idioms and conventions for Symbian OS, and About Symbian OS development, which describes the the Symbian OS development environment and the development lifecycle.

The Symbian OS library provides two useful resources for the experienced developer who wants to know what is changing in the OS, in order to maintain or extend existing programs.

The What's new section describes the changes in the documentation set since the last release. The API item reference documentation changes lists the added, deleted, and changed APIs.