System API Functions

As mentioned the system APIs for accessing files and network resources on the target platforms were, as expected, very different. Without a proper encapsulation of socket functionality as well as file handling any attempt to implement a mail library would fail. The functionality was first implemented on the Windows Mobile platform which influenced the overall structure of functions as well as operation behaviour. The file handling is for example fully blocking, which means a requested write or read operation will block until successful or some error occurs. The socket functions are also imple-mented in a blocking manner, which is not how the socket functions on Symbian are meant to operate. Making the socket functions blocking on Symbian was not a problem with ordinary sockets however there were a considerable amount of problems when using secure sockets. This is further discussed in subsection SSL/TLS support later on.

TfwLib constant Symbian constant WM constant Access flags

TFW FileAccessRead EFileRead GENERIC READ TFW FileAccessReadWrite EFileWrite GENERIC READ |

GENERIC WRITE Share flags

TFW FileShareRead EFileShareReadersOnly FILE SHARE READ TFW FileShareReadWrite EFileShareAny FILE SHARE READ |

FILE SHARE WRITE TFW FileShareNone EFileShareExclusive 0

Open mode

TFW FileCreateNew N/A (1) CREATE NEW

TFW FileCreateAlways N/A (2) CREATE ALWAYS TFW FileOpenExisting N/A (3) OPEN EXISTING

TFW FileOpenAlways N/A (4) OPEN ALWAYS

TFW FileTruncateExisting N/A (5) TRUNCATE EXISTING File attributes

TFW FileAttribArchive KEntryAttArchive FILE ATTRIBUTE ARCHIVE TFW FileAttribNormal KEntryAttNormal FILE ATTRIBUTE NORMAL TFW FileAttribReadOnly KEntryAttReadOnly FILE ATTRIBUTE READONLY TFW FileAttribHidden KEntryAttHidden FILE ATTRIBUTE HIDDEN TFW FileAttribSystem KEntryAttSystem FILE ATTRIBUTE SYSTEM Seek position

TFW FileSeekBegin ESeekStart FILE BEGIN

TFW FileSeekEnd ESeekEnd FILE END

TFW FileSeekCurrent ESeekCurrent FILE CURRENT

Table 5.2: TfwLib file handling constants

To enable cross-platform behaviour for the file handling not only was it necessary to encapsulate the actual functions but also merge the possible flag parameters etcetera to the functions in an appropriate way. Table 5.2 summarizes the file constants defined within TfwLib. Constants marked as N/A indicates that the platform does not have a certain flag/constant for the given option and instead the constant is given an arbitrary number shown within parentheses. The actual numbers are not important however they must be unique within the option group such as the Open mode shown in table 5.2.

Such options are still implemented in TfwLib using other methods.

5.1. TfwLib 33

TfwLib constant Symbian constant WM constant Protocol

TFW SocketSecSSL3 N/A (1) SSL PROTOCOL SSL3 TFW SocketSecTLS1 N/A (2) SSL PROTOCOL TLS1

Table 5.3: TfwLib socket constants

The implemented socket functions also required a set of flags/constants which are dis-played in table 5.3. As seen there is only support for the TCP and UDP protocol and no IPv6 address family support.

SSL/TLS support

Adding Secure Socket Layer (SSL) and Transport Layer Security (TLS) capabilities to the socket implementation on Windows Mobile was straightforward and required very little effort. However when implementing it on Symbian there were many prob-lems. The problems originate from the fact that many of the Symbian OS system functions are asynchronous functions, including the socket functions [4]. Asynchronous functions are functions which return immediately when called and the actual process-ing is done in parallel with the callprocess-ing thread. The completion of the functions are handled through callbacks. Since TfwLib was based on the Windows way of operat-ing a blockoperat-ing, or synchronous, behaviour was desirable. To allow such a behaviour in Symbian there is a possibility to wait for asynchronous functions through the function User::WaitForRequest(). By passing the status indicator of a called asynchronous function to User::WaitForRequest() execution will halt until the function returns.

This approached worked really well for ordinary socket communication however when adding secure socket support the approach broke down.

The first culprit identified which did not work together with User::WaitForRequest() was the SSL/TLS client handshake function. A probable reason for this is that the handshake requires additional responses from the client, in excess of the initial request, and since the client thread is locked waiting for the function to complete the function never returns. A classic example of a deadlock.

To fix this problem a secure socket implementation for Symbian was developed called CTfwSecSocketSym, using the socket functions the way they are supposed to, which is within an Active Object. An Active Object is used to invoke an asynchronous function and as the function returns an Active Scheduler invokes the RunL() method of the Active

R e q u e s t S e m a p h o r e

Figure 5.5: TfwLib Symbian socket implementation

Object [4] as seen in figure 5.5. The Active Scheduler consists of a loop which waits on the Request Semaphore for events and calls the appropriate Active Object’s RunL() method. By letting TfwIntSocketSym route its calls to a CTfwSecSocketSym object the locking behaviour is avoided. However since CTfwSecSocketSym is an Active Object it operates in an asynchronous manner. To enable a synchronous behaviour a Nested Active Scheduler Wait Loop was added to CTfwSecSocketSym. By starting the wait loop after an asynchronous function call is made it halts processing of the main thread however without blocking the Active Scheduler which handles the events generated from the asynchronous function call. As the asynchronous function call returns within the RunL() method the nested active scheduler is stopped and the function in CTfwSecSocketSym which was called by TfwIntSocketSym returns. Figure 5.6 illustrates this sequence of function calls using sending of data as an example.

T f w I n t S o c k e t S y m : : S e n d

Figure 5.6: Sending data using TfwLib Symbian socket implementation A perceptive reader might have noticed another component of figure 5.5 which has not been addressed, namely the CTfwSecSocketRecv object. The reason for its existence

5.1. TfwLib 35

is that when using the previously described Active Object for socket communication all went well until an attempt to query the socket for data availability was performed.

Knowing that data actually existed beforehand the first query returned the expected confirmation. However if some, but not all, data was read from the socket the next query would indicate that no more data were available despite the fact that performing an additional read from the socket clearly found more data. This issue was not visi-ble when using ordinary sockets but as soon as secure sockets were used the provisi-blem displayed itself. A possible explanation would be that the SSL implementation on the emulator fetches all available data from the socket and stores it internally for future read operations. However when querying the socket for data availability the implemen-tation forgets to check its internal buffer also. Although not tested this might not be a problem when running on a device which has another, and hopefully correct, SSL implementation. However since most development is conducted using the emulator it was necessary to come up with a solution that allowed SSL usage on the emulator as well. The solution was to construct another active object, CTfwSecSocketRecv, which sole task is to receive and buffer all incoming data. The CTfwSecSocketSym uses such an object for all its receive requests and for queries regarding available data at the socket the internal buffer of CTfwSecSocketRecv is simply checked for data.