Listen to Me
The five states give a big picture of what your media is doing, but sometimes you'll want more granularity than that. It might be nice to know when you have recorded 30 seconds of audio, or when a stream has run out of data and needs to buffer. RIM supports these use cases by offering a standard listener interface. By implementing PlayerListener, your application can register with a Player instance, as shown in Figure 2-3. PlayerListener defines a single method, playerUpdate , which will be...
Recording Audio
By now you should have a general idea of how the recording process works. You will request a Player, configure it for your desired capture, start it to begin recording, and then stop it once the recording is complete. At that point you can retrieve the recorded audio data. Before you start, though, you should ask yourself whether you care what format that data will be in. RIM offers several choices for audio encoding. Your choices are described in Table 2-3. Note that each choice has a required...
App Localized Text
MediaGrabber's simple UI can be run on a wide variety of devices without requiring changes to the code. By using the CLDC UI framework, the same code works fine on touch-screen and QWERTY devices. Throughout the book, I have been careful to test for feature support within the app, so no extra work is required to support the presence or absence of a camera or other piece of hardware. MediaGrabber does make use of APIs from version 4.5, but none from later OS versions. It seems reasonable to...
Build Script
Even if you don't have GNU make or Apache Ant installed, you can whip together a quick and dirty build script using Notepad or another basic text editing program. Use the build script in Listing 11-2 to generate a new application without requiring Eclipse to be open. You can modify the variables at the top of the script with the location of your BlackBerry component package, signing password, and so on. set FILES MediaGrabber.java ChoicesScreen.java PlayingScreen.java RecordingScreen.java...
Invoking the RIM Alternative
As discussed earlier, sometimes you may want to launch a native RIM application to handle media capture instead of using MMAPI. Some times this will be your only choice, such as if you need to take a picture on a device without software version 4.6 or take a video on a device without version 5.0. Even if your device supports your desired operation, you may prefer the interface of the native application to what you can provide on your own. Starting recording in this manner is much simpler than...
Playing Video
Video playback is similar to audio playback, with the extra wrinkle that you need to display the video somewhere. This process is very similar to the camera viewfinder we created in the last chapter. You will create the Player, obtain a VideoControl, place it somewhere on the Screen, and then start it playing. The most significant difference from video capture is the longer time it will take to start playback, especially if playing a video delivered over the network. The code that follows shows...
Playing Video Through the Browser
Video playback has been supported on BlackBerry devices for a while, but support in Java is fairly recent. If you want to play a video but can't or don't want to do so in your own app, you can pass the location of the video file to the device browser. Note that this works even if the video file is present on the local filesystem. The following sample code shows how to launch media through the browser on RIM software versions 4.0 and later. BrowserSession browserSession Browser.getDefaultSession...
Updates
If you have access to a web server, you can place the MediaGrabber JAD file and the unzipped sibling COD files on a publicly accessible directory. Then, direct MediaGrabber to open a browser to the JAD location to check for an update. You can do this using the Browser. Listing 11-3 shows the changes to ChoicesScreen that add a new menu item to perform the update. You can also create a menu item that captures information from the logger, and then sends it via email using our existing...
Receiving PINs
Receiving a PIN is also similar to the process for an email. You should add a listener to the user's email folder, which will be notified when an incoming message arrives. The listener will receive all incoming notifications, for both email and PIN messages, so if you are only interested in PIN messages, you should check the message type as shown in the example below. Use the standard email access methods to pull out the PIN message contents you are interested in. public class PINListener...
SVG Image Playback
BlackBerry devices with software version 4.6 or later include support for JSR 226, a standard approach for control and display of SVG animations. SVG images must conform to the W3C SVG Tiny 1.1 profile. SVG animations rely on classes in the javax.microedition.m2g package. If you are just playing existing animations, rather than creating or manipulating them, you will generally only need to use two classes SVGImage and SVGAnimator. SVGImage contains the data, while SVGAnimator understands how to...
Searching for Contacts
A few users might never get around to creating any contacts in their address book, while others might have hundreds or thousands. The number of contacts is limited only by the available memory on the device. How do you go about finding the contacts you want There are a variety of tools at your disposal, including both standard PIM APIs and special searches that are only available for BlackBerry devices. If you need the entire haystack and not just the needle, ContactList .items is the method...
Other Audio Options MIDI and Tones
MMAPI defines several options for playing programmatically generated audio. This approach was much more popular when devices were highly limited. As support for playing standard audio formats has improved, these alternatives have fallen out of favor because of their complexity and nonportability. However, they still may be appropriate when porting legacy software, creating sound effects for games or when working on specialized apps such as a virtual piano. If you look through RIM's...
Getting the Message
The simplest case to handle is when your app is already running, and you want to be notified of an incoming message. To do this, you will open a special kind of MessageConnection that functions as a server instead of a client. In other words, you are declaring an intention to handle messages that others send to you. The format of a server connection string resembles that of a client string, but the phone number portion is omitted, and instead you display only the port number. An example...
An Introduction 1
While the RIM crypto classes are not quite as complete as those in Bouncy Castle, they do contain a wide range of available algorithms. You can start using them immediately as you would any other RIM-specific classes. The available items are located in the net.rim.device.api.crypto package. Encryption and decryption are handled through a set of standard elements A key, implementing the Key interface, is used to initialize a cipher with the secret or public key. The major types are PublicKey,...
Determining by API
Several methods can be used to determine a device's identity or capabilities at runtime. DeviceInfo.getDeviceName reports the model number of the device, with an optional suffix describing the radio type. DeviceInfo.hasCamera reports whether a camera is physically present on the device. This does not necessarily mean that your app will have access to it. reports the maximum storage capacity of the flash filesystem. WLANInfo.getWLANState reports whether the device is connected to Wi-Fi....
A Fuller Example
The previous code shows the very bottom end of browser integration useful for a static web page with no images or links, but not much else. On the other extreme, you could create a fully functioning web browser app by fully implementing all RenderingApplication methods. Most apps will fall somewhere between these two extremes, based on what features they want to provide. In this particular case, Google would be much more useful if it showed images and allowed you to follow links. The first...
The Major Players 1
Many classes are involved in smoothly fulfilling a content handling request. Some are only used by the client, others only by the server, and some by both. However, it is helpful to have a rough understanding of what each component does so you can anticipate what other apps might do. The data for a particular request is embedded within the Invocation. An Invocation s primary responsibility is to hold information that can be used to locate an appropriate handler. The Invocation is serialized to...
Adding CHAPI Handling
MediaGrabber mainly focuses on capturing and sending media. For now, let us look at exposing the sending functions to other applications. Find the MediaGrabber.jad file, which will be located in the same directory as your .project file. Open it with your preferred text editor and insert the following lines anywhere in the file MicroEdition-Handler-1 image png image jpeg audio amr audio pcm audio mpeg, .png .jpg .jpeg .amr .pcm .mp3,w send, en MicroEdition-Handler-1-ID...
Type Example
Title for this task STRING Bring Goodies Complete details STRING on this task Bring in enough cookies for 30 people 0 for unspecified, 1 for highest, 9 for Yes lowest ToDo.CLASS_PUBLIC, ToDo.CLASS_PRIVATE, ToDo.CLASS CONFIDENTIAL Day and time to DATE sound or display a reminder alarm BlackBerryToDo.STATUS_NOT_STARTED, Yes Whether the task BOOLEAN is finished Unique identifier STRING 5678901234 Note Although PRIORITY can be provided in a range from 0 to 9, BlackBerry devices only support 3...
Eventful Data
As with contacts, there are a variety of fields at your disposal when editing or reading event data. Table 6-5 displays all the fields supported on BlackBerry. Most of these are very simple, with a single nonarray nonattribute value provided. LOCATION is a single string, which is easier than providing a structured address but also makes it more difficult to parse an event s location. The special ATTENDEES field can have multiple values, one for each attendee. ALLDAY is a special convenience...
A Simple Example
In the most stripped-down form, all that you need to display an embedded browser field is to create the BrowserContent, hand it a connection to your web site, and minimally implement the RenderingApplication interface. Listing 7-2 shows a basic class that does just this by displaying the Google home page in the middle of your own screen. By default, the browser Field will fill the entire screen since this is not what we want, we create a custom Manager that forces the browser to be only half as...
Writing a Plugin
All browser Plug-ins must extend the BrowserContentProvider class. They must declare what MIME types they can accept by implementing two methods. getSupportedMimeTypes indicates all the MIME types that this Plug-in can ever render, and controls whether the browser will consider it for a given piece of content. getAccept indicates what MIME types this Plug-in can render right now, given the current configuration of the browser. This may be a smaller returned set than getSupportedMimeTypes for...
App Selecting Recipients
BlackBerry devices have great keyboards, but it can still be cumbersome to enter a long email address. If you know a lot of people, the odds of remembering everyone s address is fairly small. The rest of the world has had access to integrated contacts for a long while, so your users should be able to do so as well. The next iteration of MediaGrabber will allow you to select your recipient directly from the address book. For fun, after you send the message, use one of the extended BlackBerry...
Programmatic Control
So far, we have been looking at user permissions from the user s perspective. As you have seen, the person who installs your app can exert a great deal of control over the app s behavior. This can lead to serious problems within your app, though. If you require an Internet connection to run, and cannot open that connection, then the app is effectively broken. In older versions of BlackBerry device software, there is no good solution to this problem. The best you can do is detect when a problem...
L
language differences. See localization legacy WAP sites, 243 libMain function, 22 libMain method, 273, 293 libraries, 21, 23 overview, 21 life cycle, invocation, 283, 285 lightweight Web, 247, 248 listeners, 234, 235 listening for requests, 309, 312 list method, 27, 137 listRoots method, FileSystemRegistry class, 352 lists, PIM, 196, 198 live media playback, 75 locale-specific strings ActionNameMap instance, 286 local filesystem finding content on, 71, 73 localhost email account, 141, 142...
Take a Memo
The BlackBerryMemoList and its contained BlackBerryMemo objects are the easiest PIMItem classes to work with. These allow you to access the user s saved memos or add memos of your own. A BlackBerryMemo contains only three fields, all of which have the STRING data type. TITLE provides the name of the memo, which will be viewable from a list perspective. NOTE is the memo s contained text. UID is the standard unique identifier. You can create, edit, search, read, and delete memo objects just as...
More Native Menu Integration
On older device software versions, you don t automatically see CHAPI items listed, but you can still add your own items. You are not restricted to CHAPI operations, either you can run any sort of arbitrary code that you like. To make something useful for both older and newer phones, add a new option to the Address Book app labeled Verify Media Shared. This will check the contact to see if it has previously received any media from the MediaGrabber app. If not, it will offer to open MediaGrabber...