This chapter provides an overview of wireless Internet access with the Palm OS® and describes the programmatic interfaces to the Web Clipping Application Viewer and email applications.
NOTE: You cannot use the features described in this chapter with a version of the Palm OS earlier than version 3.2.
WARNING! The Web Clipping Application Viewer is only present on a limited set of handhelds produced by Palm, Inc. Applications can programmatically detect the presence of the Web Clipping Application Viewer; see "System Version Checking" for details.
This chapter begins with a brief discussion of Internet access on Palm Powered™ handhelds and then provides a brief overview of how web clipping applications work in the following sections:
For more information about web clipping applications, displaying HTML pages on Palm Powered handhelds, and the Palm.Net system, see the Web Clipping Developer's Guide.
This chapter also describes how to programmatically access the Web Clipping Application Viewer (the Viewer) and IMessenger applications in the following sections:
- Using the Viewer to Display Information
- Sending Email Messages
- Using Wireless Capabilities in Your Applications
For more information about programmatic access to the Internet, see Chapter 79, "Internet Library," in the Palm OS Programmer's API Reference.
Internet Access on Palm Powered Handhelds
Starting with version 3.2, the Palm OS added support for wireless Internet access and messaging. Version 3.5 of the Palm OS extended those capabilities, and along with the Mobile Internet Kit, extended wireless access capabilities to other Palm Powered handhelds. Version 4.0 extends the wireless communications features even further, adding numerous additional messaging, telephony, and web access capabilities.
Two of the fundamental communications capabilities that Palm OS users can take advantage of are:
Users can access these capabilities with the built-in wireless antenna on the Palm VII™ family of devices, or with a PPP connection that uses a wireline or a wireless modem and cell phone on other Palm Powered handhelds.
Overview of Web Clipping Architecture
PalmSource, Inc. invented web clippings to make it possible for users to easily access information on the Internet with a small screen and low connection bandwidth. Web clipping technology allows users to extract and receive specific information from a web page, much like clipping a specific article out of a newspaper.
Numerous web sites are now enabled for web clipping, which means that the site's content is available in web clipping format. In the typical scenario, a web clipping application running on a Palm Powered handheld sends a query to the web site. The web site responds to the query by sending a clipping back to the handheld, and the web clipping application displays the returned clipping.
You create web clipping applications by compiling standard HTML 3.2 pages with Palm's Web Clipping Application Builder tool, which generates a .pqa that operates like a mini-web site and can execute on Palm Powered handhelds. These .pqa files are actually databases that are run by the Viewer, which communicates with the Internet.
The Viewer sends requests for information to the Internet via a Palm Proxy server, which converts the compressed format used by the Viewer into standard format and relays the request to the destination server. The server sends information back to the proxy server in standard format, and the proxy server converts the information into compressed format and relays it to the user's device, on which the Viewer displays it.
NOTE: The Palm OS automatically launches the Viewer when the user taps on a web clipping application icon in the Applications Launcher. The Viewer is not visible to users as an application in the Launcher.
For a more complete description of how web clipping works, including a discussion of the Palm Proxy Servers, see the Web Clipping Developer's Guide.
About Web Clipping Applications
A web clipping application might contain hyperlinks or an HTML form that displays information and allows the sending or requesting of information. The information can be stored locally, on the handheld device, or remotely, on a web site that can be accessed on the Internet. A web clipping application can also be a self-contained web site.
Figure 9.1 shows a typical web clipping application. This application contains a number of links; when the user taps on any of these links, the HTTP(S) request is sent to the Internet, and the web site sends back a web clipping page that is displayed on the handheld screen.
Figure 9.1 Typical web clipping application
For complete information about creating and building web clipping applications, including reference information about the HTML language features and extensions you can use in these applications, see the Web Clipping Developer's Guide.
Using the Viewer to Display Information
The Viewer program is a Palm OS program that displays web clipping applications, interacts with the Palm Proxy Server, and displays web clippings sent back from the Internet. You can also use the Viewer to display HTML content that you have created by launching the Viewer from your Palm OS applications.
Before using the features described in this section, you should verify that the wireless access features are available in the system on which your application is running. For more information, see "System Version Checking".
To launch the Viewer and display a web clipping page, use the launch code sysAppLaunchCmdOpenDB. Pass the database ID and card number for the .pqa that you want to display.
To launch the Viewer and display a specific URL, use the launch code sysAppLaunchCmdGoToURL. Pass a pointer to the URL string as a parameter to this launch code. Listing 9.1 shows an example.
NOTE: The Viewer was previously known as the Clipper; thus you see "Clipper" used in various constant names.
Listing 9.1 Launching Viewer with a URL
Err GoToURL(Char* origurl) { // parameter is ptr to URL string Err err; Char* url; DmSearchStateType searchState; UInt16* cardNo; LocalID* dbID; // make a copy of the URL, since the OS will free // the parameter once Viewer quits url = MemPtrNew(StrLen(origurl)+1); if (!url) return sysErrNoFreeRAM; StrCopy(url, origurl); MemPtrSetOwner(url, 0); // find Viewer and launch it err = DmGetNextDatabaseByTypeCreator (true, &searchState, sysFileTApplication, sysFileCClipper, true, &cardNo, &dbID); if (err) { // Viewer is not present FrmAlert(NoClipperAlert); MemPtrFree(url); } else err = SysUIAppSwitch(cardNo,dbID,sysAppLaunchCmdGoToURL,url); return err; // ErrNone (0) means no error }
IMPORTANT: When programmatically launching an application that connects to the Internet, remember that many Palm users pay for their wireless transmissions on a per-byte basis, and that web sites that are not designed to be Palm-friendly can result in increased airtime charges. For more information about Palm-friendly web pages, see the Web Clipping Developer's Guide.
Sending Email Messages
You can send email messages from your Palm OS applications in three different ways:
- Use the standard
mailtoURL in the Viewer. - Use the
sysAppLaunchCmdAddRecordlaunch code to launch the email program with its editor open. - Use the
sysAppLaunchCmdAddRecordlaunch code to silently add the email item to the outbox.
Each of these message-sending methods is described in this section.
Before using the features described in this section, you should verify that the wireless access are available in the system on which your application is running. For more information, see "System Version Checking".
Registering an Email Application
The standard, default email application on the Palm OS is either the Palm iMessenger program (for the Palm VII device family) or MultiMail (for other Palm Powered handhelds). Starting with version 4.0 of the Palm OS, you can register additional email handling applications by calling the Exchange Manager from within a Palm OS application:
ExgRegisterDatatype( CRID, // ID of registering app exgReg // URL scheme registry "mailto", // the scheme to associate "Email URL", // description 0 ); // any flags
When you register a new email-handling application, the Exchange Manager makes that application the default handler for email messages.
For more information about the Palm Exchange Manager, see Chapter 62, "Exchange Manager," and the Palm OS Programmer's API Reference book.
Sending Mail from the Viewer
You can send an email message with the Viewer just like you do in standard HTML pages, by using the mailto: tag. For example:
<a href="mailto:us@company.com">Email us</a>
When the Viewer encounters the mailto tag, it calls the Exchange Manager to handle sending the email message. The Exchange Manager calls the default email application.
Launching the Email Application for Editing
Use the sysAppLaunchCmdAddRecord launch code to launch the iMessenger email program with its editor open (optionally filling in some of the fields via the passed parameter block). This allows the user to edit the email message. To make the email program display the message in its editor, set the edit field in the parameter block to true.
NOTE: The
sysAppLaunchCmdAddRecord method of launching an email program is only guaranteed to work with the iMessenger email program.
Adding an Email to the Outbox
Use the sysAppLaunchCmdAddRecord launch code to silently add an item (the email message) to the default email program's outbox database. You must pass all the needed information in the parameter block. To prevent the email program from displaying the message in its editor, set the edit field in the parameter block to false.
When launched via the sysAppLaunchCmdAddRecord launch code, the email application returns an error code, or errNone if there was no error.
To send a launch code to the default email application, you need obtain its database ID. You can use DmGetNextDatabaseByTypeCreator and pass the constant sysFileCMessaging for the creator parameter.
Note that adding an item to the email outbox does not actually send the message over the radio. It simply stores the message in the outbox until the user later opens the email application and chooses to send queued messages. This always gives the user control over when the radio is used.
Using Wireless Capabilities in Your Applications
This section provides information about system-level features that you may need to use with your Palm OS applications that access wireless communications capabilities. The following topics are covered:
System Version Checking
Before using any special features of the operating system for wireless communications, you must ensure that your application is running on a device that supports the wireless internet access features of the Palm OS.
NOTE: In some Palm Powered handhelds, the web clipping components are not built into the operating system, but are installed as separate components.
You can check that this feature set is implemented by checking for the existence of the Viewer and iMessenger™ applications. Here's an example of how to check for the Viewer:
DmSearchStateType searchState; UInt cardNo; LocalID dbID; err = DmGetNextDatabaseByTypeCreator(true, &searchState, sysFileTApplication, sysFileCClipper, true, &cardNo, &dbID);
If Viewer is not present, the DmGetNextDatabaseByTypeCreator function returns an error. To check for iMessenger, you can use the creator type sysFileCMessaging.
For more information on checking system compatibility, see Appendix B, "Compatibility Guide."
Wireless keyDownEvent Key Codes
Versions 3.2 and later of the Palm OS provide special keyDownEvent virtual key codes to support the wireless capabilities of the Palm VII family of devices. These include:
-
vchrHardAntenna, which signals that the user has raised the antenna, activating the radio -
vchrRadioCoverageOK, which signals that the unit is within radio coverage following a coverage check -
vchrRadioCoverageFail, which signals that the unit is outside radio coverage following a coverage check, and thus cannot communicate with the Palm.Net system
Virtual key codes are passed in the chr field of a keyDownEvent data block, with the commandKeyMask bit set in the modifiers field, as described in the section "keyDownEvent" of the Palm OS Programmer's API Reference.
Normally, you ignore these events in your application event handler, and let the system event handler handle them. For example, the vchrHardAntenna event causes the system to invoke the Launcher and switch to the Palm.Net category. If you want to do something different in your application, you must trap and handle the event in your application event handler.
Alternatively, if you want your application to have control over the antenna (avoiding having the system switch to the Launcher on a vchrHardAntenna event), you can open the Internet library when your application starts, by calling INetLibOpen. You need to open the Internet library with the default or wireless configuration. When your application exits, you must close the Internet library by calling INetLibClose. For more information about using the Internet library, see Chapter 7, "Network Communication."
Including Over-the-Air Characters
One of the overriding user interface design goals of the Palm wireless communications system is to always give the user control when making a wireless transaction, partly because of the costs associated with doing so.
You can use the Palm over-the-air characters in your user interface buttons to help the user recognize a wireless transaction. Palm provides two different characters: one for standard transactions, and another for secure transactions, as shown in Figure 9.2.
Figure 9.2 Over the Air Characters
If your application includes a button that causes data to be transmitted when tapped, end the button text with the "Over-the-air" character (chrOta). This alerts the user that tapping the button will cause data transmission and incur possible airtime charges.
If your application includes a button that causes data to be transmitted securely when tapped, end the button text with the "Over-the-air-secure" character (chrOtaSecure). This alerts the user that tapping the button will cause secure data transmission and incur possible airtime charges.
Note that the Viewer application automatically adds these special characters when rendering remote hyperlinks or buttons. You only need to explicitly add these characters if you are building an application that doesn't use this capability of the Viewer.