Receiving Messages
Symbian OS-based phones typically provide support for several different messaging technologies - built-in applications allow users to send and receive email, SMS and MMS messages. It is possible for third-party applications to use and extend this messaging functionality in order to add new and innovative features. Some possible messaging-aware applications might include an email management application that filters and arranges received email messages a subscription service that receives a news...
Pipelining and Persistent Connections
Pipelining and persistent connections are defined as part of the HTTP 1.1 standard. Persistent connections allow multiple transactions to a server to be sent over a single socket connection. Pipelining allows one or more new transactions to be submitted to a server over a persistent connection before a previous transaction has completed. The HTTP framework supports both pipelining and persistent connections. An HTTP client may submit multiple requests to the framework. With a persistent...
Specifying the Send menu text
The default text used in the Send menu is the human readable name for the MTM as specified in the registration resource file. This is fine for initial development purposes, but a localizable string is required for the final version of the code. This is achieved by supplying a function with the flag EMtudCom-mandSendAs in the UI Data MTM resource file and ensuring that functiontext is localized. RESOURCE MTUD_FUNCTION_ARRAY r_textud_function_array MTUD_FUNCTION functiontext to Flickr command...
The asynchronous transport
The asynchronous transport ACL4 carries the majority of data in Bluetooth. By default, it is reliable although it can be configured to be unreliable if required to provide a latency-based isochronous service. There is a choice of packet types available to the ACL transport the packets can be chosen to optimize the performance of the service in different radio conditions. Generally, due to the dynamic nature of the different radio conditions it usually makes most sense for the Bluetooth hardware...
Service Registration
Recognizing that the service that we have implemented allows incoming connections, the first stage is to register details of the service with the SDP server. This then allows any remote device to see that we have the service available on the local device remember that we cannot use well-known port numbers in Bluetooth , and discover some dynamic details about the service. When creating a new service, that is not an implementation of a new Bluetooth profile, a 128-bit UUID is required. For this...
Example Connecting to the Symbian OS SDP server
Once a session is created, RSdpDatabase needs to be opened - this is the mechanism through which records can be added to, deleted from or manipulated in the database. When registering in the SDDB, an application will typically register a single service record. The service record has two fundamental attributes - the record handle, which is created automatically by the SDP server, and the service class, which is passed into the API at creation time. Here are the methods to register a new service...
Active Connection Information
RConnection provides the ability for applications to retrieve different types of information about an active connection. Applications are able to read configuration information for the connection they are currently using. This saves the application from needing to use the CommsDat interface described in section 6.3.2 to retrieve the information, as this can all be done using RConnection. The settings are read in the form '' lt table name gt lt fieldname gt and there are constants defined for...
Using the ETel ISV API
As part of the example applications, we will show two major areas for which you may wish to use the ETel ISV API. The first is making outgoing phone calls. This allows you to place outgoing calls from your application - for example if you are providing some sort of directory application, such as Yellow Pages, and wanted to allow users to place a call to a company directly from their listing. This is particularly effective in cases where the calls are made on an outgoing basis only, as no...
OBEX Server API
The OBEX server API in Symbian OS is defined by the classes CObex-Server and MObexServerNotify. An object of class CObexServer must be instantiated by the OBEX server application, and the MObex-ServerNotify interface class must be inherited from and implemented by the OBEX server application. The class that implements MObexServerNotify is very important as it responds to incoming events from remote OBEX clients, and so defines the behaviour of the OBEX service. An OBEX server application...
AV Protocols and Profiles
This section includes a brief discussion about the AV protocols in Bluetooth even though direct interfaces to the protocols are not provided in Symbian OS. However, the profiles they support can be used via high-level abstraction APIs. The audio video control transport protocol AVCTP is a message-based protocol that encapsulates media-control frames into L2CAP packets. It provides a fragmentation service to the upper layer so that the higher layer packets can be split over the potentially...
Restrictions and Considerations Access to Telephony Functionality
The Symbian MultiMode ETel APIs offer full access to the TSY and therefore the baseband, and represent a very powerful set of APIs. They offer the ability to control voice and data calls, GPRS and 3 G data connections, as well as information stored on the device or on the network. Because of the sensitivity of the information exposed, and the potential to prevent the device operating correctly, these APIs were not made available to developers before v9.1, as there was no method for policing...
Example Application Summary Screen
The summary screen application as seen in Figure 8.1 is used to illustrate the techniques discussed in this chapter, it provides the following functionality. Displays the details of the most recent email1 and SMS messages, i.e., the sender and subject text. 1 In order to keep the example code simple, we only check the first POP3 account, if present. Interprets special 'Weather Report' SMS messages and displays the appropriate text. These messages are intercepted before they reach the messaging...
Using Bluetooth sockets
Bluetooth sockets are exposed through the RSocket API - however, a specialized Bluetooth wrapper, CBluetoothSocket -exists to make using Bluetooth sockets easier. The latter is described more fully later, but this section describes the generic properties of using sockets for Bluetooth.11 11 The use of a socket-like interface for applications allows the state machines of the relevant protocol L2CAP and RFCOMM for Bluetooth, but also other protocols in Symbian OS to be hidden away from the...
Supplying Body Data
Example 11.2 shows a Post request being made. The Post method requires a body in the request. To supply this you need to provide an object which implements the MHttpDataSupplier interface. virtual TBool GetNextDataPart TPtrC8 amp aDataPart 0 virtual void ReleaseData 0 For small files you could return all of the data for the body in one response to MHTTPDataSupplier GetNextDataPart . For larger files you should return the data in parts. If supplying data in parts it is important to implement...
Finding the Example Service on Remote Devices
The example application attempts to automatically build large Bluetooth networks. To make the process automatic the device and service discovery procedures are combined into the service discovery application profile which is provided with the example application. The interesting part to look at is the code parsing SDP service records and attributes obtained from the remote device. In the SDAP example, when an SDP record matching the UUID search pattern is found, the following method is called...
Esock
ESOCK provides both the framework for, and the interface to, various lower level protocols in Symbian OS. For example, core parts of the Bluetooth stack, most of IrDA, most of the TCP IP stack, and much of the SMS stack3 exist within the ESOCK framework, and are accessed through ESOCK APIs. Figure 2.2 gives an overview of the ESOCK framework. Chapter 3 contains a lot of useful information about the public ESOCK APIs, with additional information in the technical chapters that refer to...
Configuring CommsDat
First we should mention a topic that affects you no matter which manual configuration method you use - configuring CommsDat. CommsDat is the repository for all IP-related communications settings on Symbian OS and it also contains important information about default TSYs, and, for certain TSYs, configuration information. Be warned - altering the data in CommsDat gives you a lot more freedom than using the UI configuration mechanisms, but it's also 1 Note that most WLAN connections will fail to...
Natasha Ho
Natasha joined Symbian in 1998, where she worked on the development of the Ericsson R380. Since then, she has contributed to almost every UIQ smartphone including the Motorola A920 and A1000, the Arima U300 and more recently the Sony Ericsson P800, P900, M600i, W950i and P990i. She has worked on various parts of the Symbian OS but now likes to concentrate solely on networking. Prior to Symbian, Natasha worked at Motorola designing and writing software for the GSM and GPRS cellular...
OBEX Sessions with Authentication and Directed Connections
Authentication in OBEX has been touched on above in relation to the Connect command and authentication challenge and authentication response headers, and directed connections in relation to the Target, Who and Connection ID headers. The Symbian OS OBEX implementation has support for authentication, and to a limited degree, directed connections also. In this section we will learn how to make use of these concepts in Symbian applications. Symbian OS supports OBEX authentication during the...
loctls
These ioctls may be passed to RSocket Ioctl , in order to prompt the stack to perform a variety of actions. Unless otherwise indicated, all of these ioctls require the LocalServices capability. Ioctls differ from socket options in that they are asynchronous - as a result many of these are callback notifications. Completes when a remote station discovers the local machine. The provided descriptor is filled with the TNameRecord related to the device which has discovered the local machine....
Domain Name Resolution
Domain name resolution is carried out using the RHostResolver API. This has already been discussed in Chapter 3 but is discussed specifically in the context of DNS here. DNS is used to resolve an internet domain name into an IP address via a DNS server, as defined in RFC1034 and shown in Figure 6.5. Applications do not need to know the specifics of how this works, but they should be aware of the configuration and behavior of the DNS implementation on Symbian OS. Each network interface is...
The Example DM Adapter
The example DM adapter that is included in the code accompanying this book allows a DM server to manipulate the settings of the XMPP application provided as an example for chapter 6. The information provided within this section of the chapter details some of the APIs that are implemented by the DM adapter and by the DM framework. For more information on these APIs and the other APIs available, please see the Symbian OS Library. The first task when starting a new DM adapter is to determine what...
The Bare Bones
Our simple example program can be found in the esock simple1 directory. If you look in the simplel.cpp file at the getPage function, you'll see code to retrieve the page. First, let's see the class declaration class CGetWebPage public CActive EConnectingSocket, ESendingData, EReceivingData static CGetWebPage NewL the usual pattern void GetPageL virtual void RunL we would also need to implement DoCancel in real code RSocketServ iSs needs Connect ing, but omitted for clarity in this RSocket iSock...
An Introduction to ESOCK
This chapter introduces one of the core communications frameworks of Symbian OS, ESOCK. We will show you how to use the ESOCK APIs to connect to a service, send and receive data, and how to allow remote hosts to connect to your own program. The example code presented in this chapter uses the ESOCK APIs, using the TCP protocol as an example - full details on how these APIs are used with a specific protocol e.g., Bluetooth, IP or IrDA are found in the relevant technology chapter. In this chapter...
Directed Connections
In the OBEX specification, directed connections provide a way in which requests and responses for an OBEX session can be routed to a particular OBEX server that can handle the requirements of the OBEX client in a transport-independent way. This also provides a means by which multiple directed OBEX sessions can be multiplexed over a single underlying transport connection see Figure 10.10 . Symbian OS implements a weaker form of directed connections, where the OBEX server can determine the...
Creating and Submitting a Transaction
The request and response parts of an HTTP transaction are encapsulated in an RHTTPTransaction. Here are the most interesting methods IMPORT_C void SubmitL THTTPFilterHandle aStart THTTPFilterHandle EClient IMPORT_C void aStart THTTPFilterHandle EClient IMPORT_C void Cancel THTTPFilterHandle aStart THTTPFilterHandle EClient IMPORT_C RHTTPRequest Request const IMPORT_C RHTTPResponse Response const 1 As discussed in Chapter 6, applications may wish to allow the user to configure a connection that...
IrDA
Infrared is supported on the emulator with the addition of an IR pod. As with Bluetooth, IR pods are connected via RS-232 to the emulator. The Symbian OS emulator does not support IR pods that connect via USB. Using USB-to-serial adaptors to connect serial-based IR pods is also not recommended, as the speed at which the IR pod operates is typically set by wiggling the flow control lines, and many USB-to-serial adaptors do not perform this operation faithfully - leaving Symbian OS and the IR pod...
Rfcomm 1
In Symbian OS RFCOMM can be accessed through three alternate APIs- RSocket, RComm and CBluetoothSocket. The RComm class presents a serial port abstraction to an application therefore any application using the RComm interface can use a virtual Bluetooth serial port. Ironically, if emulated serial port signals are required, it is actually better to use the RSocket class rather then RComm. This is because the Bluetooth implementation of RComm does not map the RComm calls relating to many of the...
OBEX Headers
In the OBEX protocol, most information is conveyed as headers. There are a large number of different possible header types, but all of these header types can be split broadly into two groups headers used to represent objects to be transferred these belong to the 'object model' and headers used by the OBEX protocol itself for its own purposes, such as authentication and the selection of directed services. When present in an OBEX packet, each header consists of one byte of header information HI...
Getting Started Creating a Session
Although HTTP is a stateless protocol, the framework supports the notion of a session, during which multiple HTTP transactions can take place. Figure 11.1 High-level architecture of the HTTP framework For example a web browser would use one session but is likely to have multiple HTTP transactions, some of which may take place concurrently. First, we need to open a session using the session API -RHttpSession. RHTTPSession has an overhead in both memory use and creation time, so typically you...
Message Server Session
The first messaging-related task that a client application must perform is to open a session to the message server. The messaging session allows a client application to examine the message store, create and send messages and to be notified of any messaging-related events for example a received SMS message . Example 8.1 shows the declaration of the messaging session. class CMessageSummaryEngine public CActive, public MMsvSessionObserver void HandleSessionEventL TMsvSessionEvent aEvent, TAny...
Example Setting the security requirements for an incoming connection
Individual services can themselves nominate individual devices to have different security clearance for connection to that service, although this is typically not recommended as it does not fit well into the way that UI platforms manage settings for Bluetooth devices, which are grouped together to allow the user to control all settings for a Bluetooth device from a single place. TBTServiceSecurityPerDevice makes this possible - it is simply a container for the Bluetooth address of the remote...
Sockets in the Example Code
The example code makes extensive use of CBluetoothSocket it shows how they can be connected, how to transfer data, and how to perform physical-link level role switching. One shortcoming of the CBluetoothSocket class is that if there exists a class that wishes to own two or more of them as the CBlue-toothBusEngine class does , then in the context of a MBluetooth-SocketNotifier callback from the CBluetoothSocket, the owning class will not be able to deduce which of the sockets is calling it back....
Device Management In Symbian OS
The OMA specification consists of shared components for both device management and data synchronization and therefore the Symbian OS architecture consists of separate frameworks for device management and data synchronization, and a single framework that handles the common aspects of the standard. This can be seen in Figure 12.1. The SyncML framework handles the connections to remote servers via various transport mechanisms and the encoding decoding of the data transmissions to the XML-based OMA...
Rfcomm
RFCOMM is a supplementary, but commonly used, protocol in Bluetooth. It provides serial port emulation, including various flow control mechanisms. It cannot provide error control itself, so it relies on L2CAP to provide reliability. As previously discussed, it is preferable that L2CAP uses its own error control mechanism to provide reliability, rather than requiring the ACL to stay in reliable mode, as this allows RFCOMM to coexist with time-sensitive data on the same link. RFCOMM is based on...
Cookie Handling
Cookie support is not provided by the framework. Cookies are handled like any other header field, although there are some differences. Cookie field values are stored and accessed as case-sensitive strings in the stringpool. As the SetCookie header can appear multiple times, and the format of a cookie header differs from most other header fields, accessing the data via GetField and GetParam is slightly different. TInt cookieCount headers.FieldPartsL setCookie RStringF cookieName strP.StringF...
Error Codes
Bluetooth applications should expect errors that are in both the system-wide error range of Symbian OS and a Bluetooth-specific range. The exported header bt_sock.h shows the values that are possible. The following are particularly important Page timeout, KHCIErrorBase-EPageTimedOut, -6004 This indicates that the device to which a connection has been requested is either not in range, or is not listening for connections. Some services may wish to treat this as a non-fatal error, and move on to...
Socket Options
These options may be passed to RSocket SetOpt , in order to prompt the stack to perform a variety of actions. Unless otherwise indicated, all of these calls require the LocalServices capability. KUnexpeditedDataOpt KExpeditedDataOpt Use expedited data packets to carry the data. These data packets are transferred in IrLAP UI frames, which exempts them from reliable delivery. They are also transmitted in preference to non-expedited packets, and on the receiver side will short-circuit queues. As a...
Telephony
Attaching a phone to the Symbian OS emulator is possible, as Symbian provides a TSY that uses AT commands to communicate with a phone over a serial cable or a virtual serial port of some kind. The MultiMode TSY MM.TSY is available in both UIQ and S60 SDKs. Finding a phone that supports the required range of AT commands though is a somewhat trickier prospect. Fewer and fewer recent phones support a sufficient set of AT commands to allow the MM TSY to initialise, let alone operate. The best...
Introducing RSubConnection
A subconnection in Symbian OS represents a channel as part of a network connection that has specific parameters associated with it. In the case of the 3G packet data network, it represents a secondary PDP context via the RSubConnection API shown in Figure 6.10. These behave in a similar way to RConnection but with the ability to also request QoS parameters for the connection. Each RConnection object has an implicit subconnection associated with it, which is automatically assigned the default...
MTM diagram
In theory, it is not necessary to put each component in a separate DLL. The MTM registration resource file allows the entry point for each MTM to be defined, enabling packaging of one or more MTM components into a single DLL. However, the MTMs are often split into their own DLLs for a variety of reasons The MTM client-side DLL should remain separate from the server side for platsec reasons a server-side DLL will require one set of capabilities - those of the message server process - whereas a...
CSocket Active Connections
CSocket active connections are started through the Connect call. EXPORT_C TInt CSocket Connect TUint addrFamily, TUint aSockType, TUint aProtocol, TSockAddr amp aDest err iSock.Open iSS, addrFamily, aSockType, aProtocol, iConn err iSock.Open iSS, addrFamily, aSockType, aProtocol, iSubConn err iSock.Open iSS, addrFamily, aSockType, aProtocol Now start the connection iSock.Connect aDest, iStatus This starts with some logic to open the socket in the right way depending on whether a connection or...
Stopping the Network Connection
There are a number of different ways for a network connection to be terminated. Of these, forced disconnection is the least desirable due to its potential for disrupting the operation of other applications on the device. In most cases, you should indicate that you do not need the connection any longer, then let the system arbitrate between applications and eventually terminate the connection. RConnection Stop allows an application to terminate a network connection immediately. This should be...
Remote Control
This remote-control framework, first delivered with the Bluetooth AVRCP profile in Symbian OS and sometimes known as 'Remcon', abstracts away the transport e.g. Bluetooth, IrDA and the protocol e.g. AVRCP or proprietary . Therefore applications can expect to receive events of the form 'Play', 'Stop' rather than requiring to interpret byte representations of remote-control protocols. Each of the transport protocols combinations is called a 'bearer' and the standard Symbian OS includes the...
How to use Secure Sockets in Symbian OS
Secure sockets, or sockets supporting the secure sockets layer SSL and Transaction Layer Security TLS , are supported on Symbian OS through CSecureSocket API. Secure sockets are familiar to most developers as the basis for https connections. They provide a way for the client to authenticate the server to which they are connecting, and provide an encrypted channel to prevent eavesdropping and alteration of the data transferred. In some cases, secure sockets can also be used to prove the identity...
OBEX Packets
To perform an OBEX transfer, the various headers described above have to be placed into and following transmission extracted from OBEX packets. Figure 10.2 Symbian OS-based example of use of Target, Connection ID and Who header in directed connections The OBEX specification defines formats for a number of different packet types. They can be divided into request packet types, which are sent from the client to the server and response packet types, which are sent from the server to the client. All...
Sending and Receiving Data
Figure 6.7 Networking subsystem data handling Figure 6.7 Networking subsystem data handling For TCP, a call to Write or Send will complete once the data has been queued by the TCP IP stack. The application can be notified of when the data is actually sent from the device using the KIoctlTcpNo-tifyDataSent socket loctl again, Chapter 3 discusses loctls in more detail sock.Ioctl KSolInetTcp, KIoctlTcpNotifyDataSent, stat However, as we discussed in Chapter 3, knowledge of when data has left a...
Installation of an MTM
Writers of MTMs need to inform the message server of the properties of the MTM by supplying a registration file. This is a compiled resource file placed in the resource messaging mtm folder. In versions of Symbian OS before v9, the resource file is placed in system mtm . The resource file should define the MTM's properties using the resource structures MTM_INFO_FILE, MTM_CAPABILITIES, and from v9.0, MTM_SECURITY_CAPABILITY_SET. When installing a new set of MTMs on a phone, you must take the...
Receiving Header Data
When the event EGotResponseHeaders is called it indicates that the status line and response header fields have been received and are accessible. The status code is the most important information. The headers can be retrieved with a call to RHttpResponse GetHeaderCollection . Through RHTTPHeaders individual header values can be retrieved using GetField . Here are the methods provided by RHTTPHeaders IMPORT_C TInt FieldPartsL RStringF aFieldName const IMPORT_C TInt GetField RStringF aFieldName,...
Starting the Connection
Once the connection preferences have been configured, they can be used to start the network connection. We have already discussed starting the connection without using connection parameters like so Using the connection preferences gives the application control over which IAP is selected and over the user interaction prompting etc. like this As stated earlier, if the connection fails the error is returned asynchronously via the TRequestStatus. If the connection is started successfully, this will...