C H A P T E R 7 - Porting the JavaCall API

C H A P T E R 7

Porting the JavaCall API

The JavaCall API is a set of C functions that perform the dirty work of the nearly the entire Java Wireless Client software stack. A complete JavaCall API implementation provides the foundation upon which an MSA stack can be placed.

Structure and Naming

JavaCall API functions are grouped by purpose into modules. Each module is represented by one or more header files which define the functions in the module.

The JavaCall API contains two types of functions:

javacall_ functions perform some work in the native OS, usually on behalf of a MIDlet application. When you port to your own device, you must implement the body of these functions.

javanotify_ functions are called by the native OS when important things happen, like key presses, incoming messages, or other events. When you port to your own device, you must write code that will call these functions at the appropriate times.

A module contains some mix of javacall_ functions and javanotify_ functions.

For example, javacall-com/interface/jsr120_wma/javacall_sms.h defines a handful of functions related to sending and receiving text messages. It includes a javacall_send() function that sends a text message and a javanotify_incoming_sms() function that is called when a message is received.

Your job is to implement the javacall_send() function to use the underlying OS services to send a text message. In addition, you must write OS code that calls javanotify_incoming_sms() when a message is received from the network.

The JavaCall API functions are also classified as mandatory or optional. Mandatory functions must be implemented for the software to work. Optional functions have default implementations, but you might be able to provide better performance or functionality by implementing them.

The Java Wireless Client software documentation includes the JavaCall API Reference, which is an extremely useful way to view detailed information about the JavaCall API.

Understanding the Event Module

The JavaCall API's Event module deserves special mention. Unlike many of the other modules, it does not directly implement some higher-level application API functionality.

Instead, the Events module is used for communication between your native, OS-level implementation and the Java platform. In its simplest form, it is a message queue for exchanging messages between native threads and the Java platform thread.

One thread is dedicated to the Java platform. The virtual machine runs in this thread, and your implementation of the JavaCall API will make native OS calls to do the works of applications running in the Java platform.

At the same time, one or more native threads will find out about important events like key presses, incoming messages, requests to pause or resume the Java platform, and so on. The code running in native threads needs a way to notify the Java platform about these important events. As you learned in the last section, you write the native code that calls the javanotify_ functions as needed.

Internally, the JavaCall API uses the Event module to communicate notifications from the native thread to the Java platform thread. Part of your job is to port the Event module so that when your native code calls javanotify_ functions, the Java platform thread receives the corresponding notifications.

For example, when an application sends a text message, eventually the Java platform calls javacall_sms_send(). Your implementation of javacall_sms_send() uses OS or device functions to queue a message for sending. The OS sends the message, probably in its own thread. When the sending is finished, your native code calls javanotify_sms_send_completed(). The JavaCall API takes care of using the Event module to pass a message back to the Java platform thread.