Amazon.com and Barnes & Nobles Web Clipping Apps
Web clipping is not just about HTML and server-side scripts. If you are experienced in developing applications for the Palm Computing Platform, you can further extend the functionality of your existing C applications to support web clipping. Using C (or C++) and a development tool such as Metrowerks Codewarrior for Palm Computing Platform, you can augment your PRCs to send and receive Internet data.
This chapter will teach you how to create new or modify existing Palm applications that make use of the wireless access features introduced in Palm OS 3.2.
This chapter assumes you have experience developing applications for the Palm Computing Platform. If you are new to programming for the Palm OS, there are a number of things you should do before continuing.
For starters, there are a number of books available for purchase that will teach you how to develop for the Palm OS, two of which are recommended below. You can purchase these books from any bookstore such as Amazon.com or Barnes & Nobles.
Amazon.com and Barnes & Nobles Web Clipping Apps |
|
E-commerce is an ideal application for web clipping. The two largest booksellers
on the web have create two apps that make ordering books (among other things) a snap with your
web clipping-enabled organizer. Now, for the ultimate shopping experience—browse in a brick
and mortar and buy online—check them out on: Palm.Net's
software archive.
|
In our experience, John Schettino's book is more suitable for the newbie developer whereas the Rhodes and McKeehan book is better suited for a developer already familiar and experienced with developing applications for platforms such as Mac OS or Windows.
You will also need the have the latest release of CodeWarrior for Palm Computing Platform. CodeWarrior is the most widely used development environment for creating software packages for the Palm Computing Platform. CodeWarrior is available for both Mac OS and Windows computers and can be purchased online through the Palm™ Store for about $369.
| Note: | All of the examples and sample code in this chapter have been developed using CodeWarrior. |
At the time of this book's writing, the latest version of CodeWarrior is Release 6. This version contains all the headers and libraries you will need to create web-clipping augmented C/C++ applications. You can learn more about CodeWarrior's capabilities by visiting the CodeWarrior web page on Palm's Development Zone.
For this book, we have created an SDK that you can use in your projects to help you quickly and effectively create Palm PRCs that take advantage of the many features of web clipping. Many of the examples and code fragments we discuss in this chapter are contained within our Web Clipping SDK.
You can find the headers and source files in the Developing Web Clippings Source Code Depot.
Okay, time to get started. Figure 6-X diagrams the process by which your Palm PRCs and web clipping applications can communicate with each other and the Internet. Up till now, our examples and discussions were limited to web clipping applications and web servers. As you can see below, however, traditional Palm PRCs can now communicate with both web clipping applications and content on the Internet. Please note that traffic still has to go through a proxy server. If you are using a Palm VII wireless organizer, your traffic will be routed through Palm.Net. If you have an OmniSky device, traffic will be routed through their wireless data provider. Finally, if you are using the Palm OS Emulator, your data will be sent through the Palm development proxy server.
 Figure 6.x: Process of communication between a web clipping app, PRC, and your web servers. |
To send and receive messages to and from the Internet, you will need to add special code to your application's source code. There are a number of ways your Palm PRCs can interface with web clipping apps and the Internet, outlined below.
palm or palmcall.
Using the Creator ID of a PRC and the palmcall reference, we can treat any Palm PRC application as a server that responds to standard CGI GET requests. This affords us the ability to transfer data straight from a web clipping page to PRC applications (and vice versa) residing on the user's Palm VII handheld. For example, we can create a page which adds memos directly to the Palm's Memo Pad from within a web clipping page!
This section outlines the additions made to Palm OS 3.2.
The following constants are used to identify the Creator ID of the iMessenger and Clipper applications, as well as the file type for web clipping applications.
This is the Creator ID for the Clipper application on the Palm organizer.
This is the Creator ID for the iMessenger application on the Palm organizer.
This is the file type for web clipping applications. Note that there is a space at the end of the constant. Remember, file types and Creator ID's are four-characters in length.
The following launch codes are available when using the wireless access feature set. You can
add some of these launch codes, such as sysAppLaunchCmdURLParams, to your
PilotMain function to add web clipping support for your applications.
This launch code instructs Clipper to open the specified web clipping application. The parameter block
for this launch code is a pointer to a SysAppLaunchCmdOpenDBType:
typedef struct {
Word cardNo;
LocalID dbID;
} SysAppLaunchCmdOpenDBType;
The code below illustrates how to use this launch code:
MemPtrSetOwner(file, 0); SysUIAppSwitch(cardNo, dbID, sysAppLaunchCmdOpenDB, file);
Note the use of the function SysUIAppSwitch. You cannot cannot sublaunch Clipper using the function SysAppLaunch from within your application. Nor can you call this function while Clipper is the active application. If you do, an error will be raised from within Clipper saying its database is already open.
Because we are quitting the current application and switching to Clipper, we need to set
the owner of the pointer to the SysAppLaunchCmdOpenDBType variable to the system
We do this by calling the MemPtrSetOwner function. If you do not add this call to your
code, your program will crash.
This launch code instructs Clipper to display the requested URL. The parameter block is
a pointer to a URL-string. Clipper supports the following protocols as valid parameters to the
sysAppLaunchCmdGoToURL launch code.
The code below illustrates how to use this launch code:
MemPtrSetOwner(url, 0); SysUIAppSwitch(cardNo, dbID, sysAppLaunchCmdGoToURL, url);
As with the sysAppLaunchCmdOpenDB launch code, you need to use the SysUIAppSwitch
function instead of the SysAppLaunch function when using this launch code.
This launch code is sent from the Clipper application to a PRC on the Palm device when a
palm or palmcall link is tapped on from a result page. The parameter
block is a pointer to a URL-string. We will go into further detail on handling palm
and palmcall requests later in this chapter.
Figure 6.x: The vchrHardAntenna key code to the current application
whenever the antenna is raised. If not handled, the unit will launch the app
specified in the pop-up menu.
|
There are three new key codes that have been introduced in the Palm VII SDK. These key codes can be used to detect when the antenna has been raised or if the unit is within the coverage zone for wireless service.
| Note: |
Some web clipping-enabled organizers may not provide support for these keycodes.
For instance, when you extend the antenna of the OmniSky modem, the
vchrHardAntenna is not sent to the event queue.
|
The Palm VII organizer uses the following three key codes listed below,
vchrHardAntenna, vchrRadioCoverageOK, and vchrRadioCoverageFail.
This key code is sent whenever the antenna on the Palm VII organizer is raised. If you do not trap this event, the organizer will launch the application specified in Prefs->Buttons. Listed below is some sample code to show you where you can opt to detect the key code.
static void AppEventLoop(void)
{
Word error;
EventType event;
do {
EvtGetEvent(&event, evtWaitForever);
// Trap the Palm VII antenna switch and prevent switching applications
if(event.eType == keyDownEvent && event.data.keyDown.chr == vchrHardAntenna) {
continue;
}
if(!SysHandleEvent(&event))
if(!MenuHandleEvent(0, &event, &error))
if(!AppHandleEvent(&event))
FrmDispatchEvent(&event);
} while(event.eType != appStopEvent);
}
The Clipper and iMessenger applications both trap this key code to prevent the default system event from occuring whenever the antenna is raised. If you are writing a Palm PRC and do not wish your application from exiting whenever the antenna is raised, your code in your AppEventLoop will look similar to the above example.
This key code is sent when the organizer is within the wireless service coverage zone. Your application may want to provide some kind of user feedback when the radio coverage check has succeeded.
This key code is sent when the organizer is out of the wireless service coverage zone. Your application may want to provide some kind of user feedback when the radio coverage check has failed.
When you create a hyperlink in a web clipping application, the over-the-air icon is
automatically appended to the end of the link's text. This is not the case, however, with your Palm
PRCs. When you have, for instance, a button that will invoke a wireless transmission when tapped, you should
add either the chrOta or the chrOtaSecure character to the end of your control.
The chrOta character displays the non-secure over-the-air icon, as shown in
the figure below.
Figure 6.x: The over-the-air icon should be used whenever you are conducting a wireless transaction. |
Similar to chrOta, this character displays the secure over-the-air icon, as shown in the
figure below.
Figure 6.x: The secure over-the-air icon should be used whenever you are conducting a secure wireless transaction. |
You add valuable feedback to the user from an usability standpoint. The user will know which controls will result in an over-the-air, Internet transaction, and which ones do not. Ensure that each control that initiates a wireless transaction has an over-the-air or secure over-the-air icon next to it.
Figure 6.x: Users will know exactly what results in a wireless transaction when you master the use of the over-the-air character. |
There are a couple of ways to add the over-the-air characters to your text strings and button labels. The simplest method involves zero coding on your part whereas the second method is a little more involved on the programming side. The example that we will be using involves adding the over-the-air icon to a button.
In the Chars.h header file in the Palm VII SDK, which comes with CodeWarrior Release 6,
there is the definition for chrOta. The value given to chrOta is
0x0015, which corresponds to the ASCII value 21. For chrOtaSecure,
the value is 0x0014, or ASCII value 20 (for a complete list of ASCII characters, see
Appendix E).
#define chrOtaSecure chrDeviceControlFour // 0x0014 #define chrOta chrNegativeAcknowledge // 0x0015
With this piece of knowledge, we can easily add the over-the-air icon to buttons or text in our application. While in the Constructor for Palm OS application, add a button to one of your forms. In the button properties window, add a label to your button. Since you can't input ASCII character 21 from the keyboard, you need to click on the checkbox labeled Hex. This will convert the label's string into hexademcimal values. To add the over-the-air icon to the end of the string, type in 15, as shown below in Figure 6-x.
Figure 6.x: If you want to use the secure over-the-air icon, change the 15 to 14. |
When you uncheck the Hex checkbox, you will see a box where the over-the-air icon should be. Don't worry about it not displaying the over-the-air character. When you compile and run your application, the over-the-air icon will replace the unsightly box, as shown in the figure below.
Figure 6.x: Use the Constructor to add the over-the-air icons to text. |
Menu items can also display the over-the-air characters. The properties dialog box for menu labels do not contain a checkbox for specifying hexademical values, however. What you need to do is copy the rectangular box (i.e. the placeholder for the over-the-air character) and paste it in the label field for the menu item.
You may want to use the method outlined below when you need to dynamically change a button's value at runtime. This technique is more programming intensive than the previous technique, but is not terribly difficult. Consider the following code:
ControlPtr buttonPtr; Char buttonStr[32]; Int len; // Get a pointer to the button control buttonPtr = GetObjectPtr(MyFormButton); // Get the length of the original label len = StrLen(CtlGetLabel(buttonPtr)); // Copy the original label into buttonStr and add the over-the-air icon StrCopy(buttonStr, CtlGetLabel(buttonPtr)); buttonStr[len] = chrOta; // Terminate the new string and set the button's label buttonStr[len+1] = 0; CtlSetLabel(buttonPtr, buttonStr);
| Note: |
The function CtlSetlabel takes as an argument a null-terminated string. If you are
allocating memory on the fly, be sure you have enough space in your new
string for the chrOta character and the NULL terminator.
|
Both methods add the over-the-air icon to the end of your button, as shown in the figure below.
|
Figure 6.x: Dynamically add the over-the-air icon to your text. |
Your application may be used on devices that are not web clipping enabled. When run on such
devices, the over-the-air character may be displayed as a rectangular box. If you want to be
extra considerate of this user interface issue, you will want to add the
chrOta and chrOtaSecure characters dynamically to your controls
using method 2. To avoid displaying the rectangular box on devices that do not have web clipping,
check for the presence of the Clipper application. If Clipper exists, it's a safe bet that
web clipping, and hence the over-the-air characters, are supported. If Clipper does not exist, don't
add the over-the-air character to your strings.
Your application should check for the presence of iMessenger and/or Clipper before using any features from the wireless access feature set. Your app may be running on a Palm organizer that lacks this feature set; as such, you should handle this situation gracefully. You can use the following code to verify whether or not Clipper or iMessenger is installed on the user's device.
Err err;
DmSearchStateType searchState;
UInt cardNo;
LocalID dbID;
err = DmGetNextDatabaseByTypeCreator(true,
&searchState, sysFileTApplication, sysFileCClipper,
true, &cardNo, &dbID);
if(!err) {
// Continue with your code
}
else {
FrmAlert(NoWebClippingAlert);
// Clipper is not present
}
 Figure 6.x: This app only runs on a device supporting web clipping, such as a Palm VII or an OmniSky Palm V. |
It is a good idea to provide an alert dialog if your app is not supported on the host device. As you can see in the code above, we have added a call to FrmAlert using the alert message NoWebClippingAlert, which we define in our application's resource file. An example is show to the right in Figure 6.X.
This chapter has many examples and tutorials to teach you how to create C applications with wireless access support.