Using the Content Handler API

Invoking applications

The application that invokes the content handler is the one that specifies the action to be taken and provides additional arguments that the actual content handling application can use. The interaction can be compared to a client-server model where the invoker acts the role of a client and the handler acts the role of a server.

As a client, the application makes requests to display or act on some content. The request is made by supplying parameters that identify the content by URI, the content type, or the ID of the content handler, and possibly an action to perform.

The main classes that invoking applications use are Registry and Invocation. The handler is invoked by calling the Registry.invoke method to start the request. This method returns a boolean value that indicates whether the invoking application must be closed before the content handling application is launched. The application can register a listener with Registry.setListener to be notified when the response is available.

Content handler applications

The MIDlet that is registered with the Java Application Manager (JAM, the Series 40 equivalent of Application Management Software) to process defined types of content is called the content handler. When the invoking application requests the content that is registered for the content handler, an instance of the content handler is created. The attributes of this instance are determined when the MIDlet is registered as a content handler. Content handlers can not be registered to replace native applications.

MIDlets can be registered with the JAM as content handlers either with static or dynamic registration. Generally, static registration is preferable.

Invoking content handler applications running in the background

Background running content handler applications do not get automatically brought to the foreground when they are invoked. Background running content handler applications can handle invocations by implementing and registering a RequestListener using ContentHandlerServer.setListener. When an invocation occurs, the background running content handler application can select to handle the invocation in the background, or request it to come to the foreground.

Static registration

In static registration, the content handling attributes are stated in the MIDlet's JAD file. When using static registration, you must add the MIDlet into the javax.microedition.content.ContentHandler security domain using the MIDlet-Permissions JAD attribute.

A MIDlet using static registration is registered automatically when it is installed on a device and stays registered until uninstalled.

The actual content handling registration in a JAD file is done with the following attributes:

• MicroEdition-Handler-#

  An attribute that registers the content handlers from the MIDlet Suite. The JAD file can contain multiple MicroEdition-Handler attributes. The attribute has four arguments:

  • Classname of the MIDlet that is responsible for handling the content

  • Supported MIME-types

  • Operations

  • Suffix of the supported files

  The resulting JAD attribute can look, for example, like this: MicroEdition-Handler-1: com.nokia.midp.example.jsr211.PNGHandler, image/png, open, x.png

• MicroEdition-Handler-#-ID

  An attribute that specifies an unique ID for this handler. The content handler ID is set during MIDlet installation and is returned with the method ContentHandler.getID. If you do not declare the ID in the JAD file, the underlying implementation creates it.

Dynamic registration

In dynamic registration, classname, content types, suffixes, actions, and other attributes are initialized and passed to the Registry.register() method. They can be unregistered with the Registry.unregister() method. Dynamic content handlers are also unregistered when the MIDlet is uninstalled.

The following is an example of a dynamically registered content handler, which opens any .png image files:

   try {
     // Registry.register (classname, content type, suffix, action);
     ContentHandler handler =
     Registry.register("com.nokia.midp.example.jsr211.PNGHandler", "image/png", ".png", ContentHandler.ACTION_OPEN);
   } catch (ContentHandlerException ex) {
     // Handle exception
   }