Series x Secure Sockets
Series 60 2.x adds some new classes to handle secure sockets. The main one is CSecureSocket, which is instantiated from an RSocket handle to represent a secure socket. Its API is derived from the new mixin interface MSecureSocket. The main shortcoming from Series 60 1 .x that is addressed by the new API is the lack of notification when the secure handshake completes. In Series 60 2.x, the handshake is initiated explicitly by means of an asynchronous function, and the corresponding Active Object...
ECom DLL
The previous subsection described the requirements of an ECom interface. This subsection details the work required to add an ECom plug-in into the framework. An ECom implementation is simply a collection of one or more implementations for one or more interfaces. Physically, it is made up of a pair of files. The first is the all-important DLL, which contains the actual code. The second is a compiled resource file, which is a map linking user interfaces to their implementations. It also provides...
CommDB
Information relating to communications settings lAPs, ISPs, GPRS, modems, locations, charge cards, proxies and WAP is held in a Symbian OS database. A series of relational tables store the data, with the database being managed by the communications database server, CommDB. Applications can access and modify the settings through CommDB, with the underlying DBMS ensuring the integrity of the database. Users can use the Settings application to view and manipulate the details stored. Note that the...
Always Exit Gracefully
Your application needs to exit gracefully. Exiting can be initiated explicitly by users, or automatically by the system. Under these circumstances, an EEikCmdExit instruction will be received by HandleCommandl_ . This is a last opportunity to save application data and to release system resources that are no longer required. Note that applications must shutdown quickly once they receive this command there is no time to present options to the user. It is also possible that the entire system may...
The Control Stack
The control framework provides a control stack used for routing key events. Each control has a priority that determines its position on the stack. A control's position on the stack determines the order in which it will be offered key events. The control with the highest priority is placed at the top of the stack, with controls arranged in decreasing order of priority. The relative placement of controls with equal priorities is determined by the order in which they were added, with the most...
Using the SendAs API
The Send-As API offers a far simpler Interface than the Client MTM API that you saw In the previous section, but It Is also far less powerful. It allows you to create a message, add simple details to It, such as recipients, body text and attachments, and save it to the Drafts folder. Ironically, given its name, Send-As does not have an API for sending the messages it creates This is seen as one of its major limitations. The Send-As API is provided through the class CSendAs. This owns a whole...
SendAs API
The Client MTM API is extremely powerful and flexible, but it is also quite complex. Many applications require only a limited subset of this functionality, most commonly just the ability to create and send a new message. The Send-As API provides a simple class CSendAs that offers precisely this capability. The obvious advantage over the Client MTM API is its simplicity, but this is also its disadvantage Send-As is not as powerful or flexible as the Client MTM API, and it can only be used to...
Descriptors as Arguments and Return Types
Descriptors are often passed into functions and returned by them. It is common to use references to the base classes tdes for modifiable descriptors and TDesC for nonmodifiable descriptors. This allows the greatest flexibility in implementation, as your API is not limited to one concrete type. Here are some common examples Setter function for the element's symbol. param aSymbol The element's new symbol. void SetSymbol const TDesC amp aSymbol Note that const TDesC amp is used to pass in a...
if taskExists
It Is possible to send a message to a running application using TApaTask SendMessage TUid aUid, const TDesC8 amp aParams . The parameter aUid should be KUidApaMessageSwitchOpenFileValue to open the file passed in aParams, or KUidApaMessageSwitchCreateFileValue to create a new file. The message sent is handled by CEikAppUi ProcessMessageL TUid aUid, const TDesC8 amp aParams . In the browser application, ProcessMessageL has been implemented to ignore any value passed to aUid and launch the link...
Sorting 1
The sorting of a CArray consists of just two steps Construct an instance of the appropriate key, specifying the field offset, the sort type and forchar arrays the text length. Invoke Sort on the array, passing in the key. These steps will be explained by examining CEIementCArray SortByAtomicNumberl_ from the example application. Here is the implementation void TKeyArrayPtr key _FOFF CChemicalElement, AtomicNumber , ECmpTInt Notice that, unlike the CEIementRArray implementation, this method is...
Console Applications
Often during the development of system components, communications modules, application engines and other self-contained functional units you may want a simple test application. Such test harnesses allow you to run and exercise your code as it develops. GUI applications are often not the best option for this purpose they can be too heavyweight just for testing, particularly so for regression testing reproducible functional testing . Console applications are often a better option, and they have...
Handling List Events
In order to perform an action on a selected item in the list, you will need to generate and handle list events. In SimpleList, the user can choose to open a selected game. The list will generate events only if you offer key presses to it. You do this by overriding OfferKey EventL in the container such that it passes key events to the list. TKeyResponse CSimpleListContainer OfferKeyEventL const TKeyEvent amp aKeyEvent, TEventCode aType To handle list events you need to Implement the...
Bluetooth Profiles
A number of different profiles are defined by the Bluetooth specification, and each Series 60 device supports a subset of these. The exact set of profiles supported is determined by the handset manufacturer there is no single set of Series 60-supported profiles. However, commonly implemented profiles include Object Push Profile Allows a Bluetooth device to send and receive OBEX objects, such as vCard and vCal items. File Transfer Profile Depending on the profile implementation on the device,...
void ConstructLconst TRect aRect
void SizeChanged Tint CountComponentControls const CCoeControl ComponentControl Tlnt alndex const void Draw const TRect amp aRect const CEikLabel Label example label The first thing to notice is that the Container class derives from CCoeControl this is the base class for all controls. The Hello World text is displayed in the form of a label Label, the label itself being a control. CHelloWorldContainer implements four methods from CCoeControl all of them are called by the framework. SizeChanged...
Platform UIDs
Platform UIDs are an essential part of the definition of a Symbian Installation System .sis package file .pkg they must be included before a Series 60 application is readied for external distribution. Table 2-5 provides a list of current Platform UIDs you can use in your .pkg file to specify the target Series 60 Platforms that are compatible with your application Table 2-5. Platform UIDs for Series 60 Platform Versions and Devices Table 2-5. Platform UIDs for Series 60 Platform Versions and...
LogClientGetStringdirectionStr RLOGDIRIN
Once the filter has been created, it can be employed to generate a view of the events in the log engine using CLogViewEvent SetFilterL const CLogFilter amp aFilter, TRequestStatus amp aStatus . Note that this function is asynchronous, as creating the view can take some time. If there are no events in the view, the function returns EFalse, if there are events, the asynchronous request is issued and the function returns ETRue. TBool eventslnView LogView- gt SetFilterL iLogFilter, Status if there...
ExternalizeL
Symbian OS convention requires that any object that can be externalized to a stream should provide a publicly accessible ExternalizeL function, declared like this void Externalizel_ RWriteStream amp aStream const Earlier you saw an extract from CChemicalElement Externalizel_ . Here is the full function void aStream const aStream iName aStream Symbol iAtomicNumber RelativeAtomicMass Radioactive Type Such functions are obvious for simple classes like CChemicalElement that do not own other complex...
RFs API
The File Server is accessed via a handle of type RFs, and each RFs connected to the File Server demands a certain level of server-side and system resource, so their number should therefore be kept to a minimum. The Control Environment CONE , which forms part of the application framework for Ul applications, provides a permanent handle to the File Server to help reduce the number of connected File Server Sessions needed. To access it, invoke FsSession on the CoeEnv member of your View class. The...
Tones
The CMdaAudioToneUtility class plays audio tones. Tones can be sine waves, or Dual Tone Multi Frequency DTMF telephony signals tone-dialing touch-tones . As with recording, an observer is used for notifications and callbacks in this case MMdaAudioToneObserver. For notification purposes, MMdaAudioToneObserver provides two pure virtual methods MatoPrepareComplete , to inform the client that the tone player is configured properly to play, and MatoPlayComplete , which is called once the tone has...
OutOfMemory Testing
The test harness code shown so far is not actually taken from a real example. It is designed purely to show how the API works. However, the Testing example shows how a real out-of-memory OOM test harness can be created. The code shown below Is not the complete source, but It should be enough to demonstrate the principles. This brings together what you have learned so far about RTest and the heap checking and failure macros. The basic mechanism for OOM testing is using_UHEAP_SETFAIL to create...
How to Use DialogBased Architecture
The example, SimpleDIg, demonstrates how to create a simple application where the main application view is a dialog. Again, this application can be used to create a skeleton application, if required. The dialog is defined in the resource file SimpleDIg.TSS RESOURCE DIALOG r_simple_dialog flags EEikDialogFlagNoDrag EEikDialogFlagNoTitleBar EEikDialogFlagFillAppClientRect EEikDialogFlagCbaButtons EEikDialogFlagModeless buttons R_AVKON_SOFTKEYS_OPTIONS_BACK id ESimpleDlgCldGameName type...
RunL
The RunL of this particular Active Object is fairly complex, because it performs a number of tasks It decides what the next iteration should do load data or waste time . It checks the status of the last iteration and reports this to the observer. It processes any data loaded. The RunL of any general Active Object will probably want to do at least one of the jobs suggested above some may want to do all three. Here are the first few lines of RunL void CCsvFileLoader RunL Fill the read buffer if...
Graphics Devices and Graphics Contexts
A graphics device represents what is being drawn to for example, the screen, a bitmap in memory, or even a printer. Attributes of graphics devices include the size of the device area and the number of colors supported by that device. In order to be able to perform drawing operations they must have an associated graphics context and consequently a CreateGraphiCSContextO function. The abstract class CGraphiCSDevice provides an interface for all graphics devices, while C Bitmap Device is an...
MultiBitmaps and Bmconv the Bitmap Converter
Bitmaps provide the pixel patterns used by pictures, icons and masks, sprites and brush styles for filling areas of the display. To optimize bitmap performance, Symbian OS uses files containing multiple bitmaps in its own highly compressed format. A tool is provided bmconv.exe with the Series 60 SDK that takes one or more Windows bitmap .bmp files as input and generates a single Symbian OS multi-bitmap file .mbm , optimized for efficient runtime loading. To see the bmconv syntax and options...
Offering Key Events
Key events are passed to a control by a call to its OfferKeyEventL method. Again, this is a virtual method in CCoeControl which you need to override in your own control to provide appropriate behavior. A control can decide whether or not it wants to process a key event. If it does process the event, it should return the value EKeyWasConsumed otherwise it should return EKeyWasNotConsumed. The event will be passed to each control on the stack in turn until one of the controls returns...
Discovery
The class used to discover other devices is RHostResolver. This is also used with TCP IP sockets to resolve host names such as www.emccsoft.com into numerical IP addresses. This is a quite different process from discovering IR or Bluetooth devices, but it performs a similar role in the process of establishing a socket, and the RHostResolver class ensures a consistent set of APIs across all socket types. An RHostResolver object is opened in a similar way to an RSocket with an Open method which...
RConnection
The RConnection API, exported by ESOCK, offers full support for multlhomlng and overcomes the security and billing problems mentioned earlier. Essentially the RConnection API can be used to provide the following functionality Starting and stopping interfaces with or without overriding the preferences specified in CommDb. Monitoring progress during start-up of an interface. Indicating when interfaces start and stop. Enumerating active connections. Retrieving statistics on traffic sent and...
Finding Memory Leaks
Memory leaks occur when allocated memory is orphaned. There are two basic types of memory leak Static leaks are repeatable under the same conditions each time. They are caused by mismatched allocation and deallocation, and so always occur in the same place. Dynamic leaks, however, are nonrepeatable typically being caused by an error or race condition. These are trickier to find, as they will not occur on every run, or will appear to occur in different places. Either type of leak will cause an...
Dynamic Menus
Menus are dynamic the number of items displayed in them can vary throughout their lifetime. If the number of menu items in a menu is too great to fit on one screen, the framework automatically provides scroll adjusters so that you can scroll through them. You can control the number of menu items in a menu by hiding and revealing them programmatically. This is useful in order to prevent users from accessing commands at inappropriate times you would want to hide a Check Spelling menu option in a...
Writing a Dialog Class
You need to write a class that can construct and execute the dialog, initialize the data in the controls, handle the data received from them, and determine how the dialog is dismissed. Other functionality can be added to the dialog class, such as methods for validating and saving the dialog data. It is also possible within this class to initialize the dialog with values at runtime, rather than statically defining them in resource. This allows you to use the same resource for different uses of...
Explicit Connections
If you want to use RConnection to create an explicit interface connection for your TCP IP sockets, the general procedure is Connect to the Symbian OS Socket Server. Open an RConnection on the Socket Server. Create IAP preferences using TCommDbConnPref this is optional . Start the outgoing connection with preference overrides if required, using RConnection Start . Optionally open a host resolver associated with the connection for DNS look-ups using RHostResolver Open . Open a socket associated...
Saving and Validating Dialog Data
For a dialog to be able to update application data, it will need a reference to the data. In the SimpleDIg application, RunDlgLD takes a reference to a descriptor, which the dialog then modifies using the value in its editor control. The reference is stored as member data by the dialog during construction. A common place to validate and update the data is in the OkToExitL method. This function will be called by the framework when any soft key other than Cancel is pressed. You can force the...
CameraServerSetlmageQualityRCameraServEQualityHigh
A high-quality image is 32 times the size of a low-quality image, and this might be an issue, especially if numerous images are being stored. The speed with which pictures are taken depends on the image quality and TfP the lighting conditions, with low-quality images being significantly quicker to take than high-quality images. To implement a viewfinder, create a timed loop to take and display pictures using the low-quality image mode. This will give less image flicker than the high-quality...
Designing an Application Ul
The three common application architecture design approaches used for application Uls are Traditional Symbian OS Control-Based Architecture Avkon View-Switching Architecture This subsection explores these three application architectures, giving example code to show how to implement each option and to clarify the benefits and drawbacks of each approach. Before exploring these different architectures, you need to be clear on the terminology used in this chapter A view is a conceptual term meaning...
Resource File Syntax
The syntax of resource files is similar to that of C , but not identical. Because the C preprocessor is used as the initial step in processing resource files, you can use both C and C style comments in resource files, as well as preprocessor statements such as include, define, if, else and endif. All white space appearing in the resource file is ignored, unless it is within a string. The following first few lines of a resource file show preprocessor statements in use copyright EMCC Software Ltd...
Using HBufC
HBufC descriptors, despite not conforming to standard naming conventions, are allocated on the heap they are not derived from CBase and so have the unique starting letter, H for heap . Heap desciprtors are generally used in preference to all other descriptors in the following situations If the size of the descriptor is not known at compile time, or its size is not bounded by a small maximum value. If the size of the descriptor is known to be large. For example, in the CChemicalElement class in...
Bluetooth Socket Communication
Provided that the device and service discovery phase was successful, you now have an address and port number identifying a service on a remote device. This information can be used to open a socket session with that device. Note that the general steps involved in opening a socket in Series 60 are covered in detail in the Sockets section earlier in this chapter you should read through that section to familiarize yourself with it before continuing with this section. The generic steps that have...
CMsvEntry
This is perhaps the most commonly misunderstood class in the messaging architecture. Perhaps because of its name which looks misleadingly like TMsvEntry , it is often assumed that an instance of this class contains all the data belonging to an individual entry such as its headers, body text, and such like . This is not the case, as you will see as soon as you look at its API. CMsvEntry isnof an in-memory representation of an entry likewise, calling CMsvEntry NewL does not create a new entry in...
WAP Architecture
The hierarchy of the stack can be seen in Figure 10-2. Note that the bearer layer is not specified as part of the WAP standard the existence of suitable bearer, such as GSM, SMS, or GPRS, and appropriate APIs are assumed. WDP is an unreliable transport protocol, analogous to UDP, which is essentially responsible for moving data between the sender and receiver and back again. As the base of the WAP stack it provides an interface to the different bearers. The WTLS protocol provides a mechanism...
Machine Word Alignment
Series 60 devices use 32-bit ARM chips with RISC architecture for cost and power efficiency. This means that all memory words must be aligned to 32-bit machine word boundaries. Dereferencing a pointer whose address is not a multiple of 4 will result in an access violation. 32-bit or larger struct and class members will be 32-bit aligned by the compiler, with appropriate padding, sosizeof may return a larger value on target than on the emulator. For example, the following structure would have a...
Reviewers and Technical Advisors
Our review and advisory team consisted of Nokia and Siemens subject matter experts and many independent reviewers, with relevant technical background, engaged by Addison-Wesley. This team grounded our manuscript with a real-world balance. We are indebted to them all for the time, care and expertise they put into this project. Ari Aumala, Petri Backstrom, Richard Bloor, Gerard Bruen, David Carson, Anurag Chandra, Tuomas Eerola, Juergen Fey, Riku Granat, Juha Hietasarka, Pekka Jokela, Juuso...
Other Hints and Tips
File System When using files, minimize the number of opening, reading and writing instructions. Write larger data blocks in one go. Persisting one large block of data is much more efficient than multiple writes of smaller blocks of data. As mentioned in the previous subsection, check the free disk space available using the methods provided in SysUtil. System Watchdogs There are subsystems within Series 60 that may request that your application exit at any time for example, the 00M Out-Of-Memory...
Text and Font Measurements
In order to draw text with precision on the screen, you must have an appreciation of the character metrics and their roles and relationships with each other. These are highlighted in Figure 11-6 and Table 11-6. Figure 11-6. Illustration of font metrics and their relationship to a font. Figure 11-6. Illustration of font metrics and their relationship to a font. This knowledge has practical applications, as there is an overloaded version of the CGraphiCSContext DrawText function illustrated in...
Submitting the Request and Receiving the Response
Once the request headers have been set, the request can be submitted. This is achieved by calling the RHTTPTransaction SubmitL method Submit the request Transaction. SubmitLQ RHTTPTransaction SubmitL is an asynchronous function, but you do not need to explicitly create an active object in order to handle it. This is performed by the HTTP stack for you. During the course of the request transaction, progress notification events are sent to the MHFRunL method of the MHTTPTransactionCallback object...
Making a POST Request
Another common kind of HTTP request is the POST request. This differs from the GET request mainly in that the request itself contains a body as well as headers. It is most commonly used for transmitting data entered in an HTML form to some kind of program on the server, such as a CGI script or Java servlet, which then returns a dynamically generated response. The HTTPExample application makes a POST request to a CGI script, passing the user's name as a parameter. The script returns the text...
OptionsSack 1
Initially a handle on the system graphics context is obtained. A graphics context performs various drawing functions, and later in the function it will be used to draw lines between two points on the screen using the DrawLine method void CBasicDrawingContainer Draw const TRect amp aRect const Get graphics context and clear it The TPoint class is used to represent coordinate points on the screen, while TSize represents a graphical object's width and height Set up points and increment value for...
Displaying an Image in the Context Pane Using Resources
RESOURCE CONTEXT_PANE r_my_context_pane bmpfile Alternatively, you can also set the context icon in the resource file by specifying aCONTEXT_PANE works in the same way as the TITLE_PANE resource. The bmpfile field identifies an .mbm file from obtain the image. The bmpid field specifies the index of the bitmap to use from the .mbm file, and the field specifies the index of the mask to use, if needed The SDK documentation contains further details of all the API methods available in the...
Chapter Multimedia Graphics and Audio 1
Using the advanced multimedia facilities of Series 60 to enable sound and graphics in your application The multimedia architecture of Series 60 has been designed and optimized for mobile devices. While system resources may at times be constrained, the multimedia features available to developers are far from so, having a rich feature set more akin to a desktop computing environment. With relative ease the different components can be used for numerous tasks, ranging from drawing simple shape...
Displaying Tabs in the Navigation Pane Using Resources
The NavigationPane example shows you how to display tabs in the navigation pane using a resource file, as shown in the following code snippets taken from NavigationPane.rss. First, the status_pane field is defined in the application resource RESOURCE EIK_APP_INFO status_pane r_navigationpane_status_pane Then the status pane itself is defined RESOURCE STATUS_PANE_APP_MODEL r_navigationpane_status_pane panes id EEikStatusPaneUidNavi type EAknCtNaviPane resource r_navigationpane_navi_tabgroup...
RWriteStream
RWriteStream is the base class for externalizing data to a stream. Before it can be used, it is necessary to connect the stream to some form of data sink. This depends upon the type of stream to be used, so RFileWriteStream will be considered for externalizing to a file. The code snippet below shows how to create an RFileWriteStream. This function assumes that the file KTxtTestFileName does not already exist. If it does an error value of KErrAlreadyExistS is returned by Create , use...