Creating iKnapsack-enabled Web Browsers

Last updated: September 30, 1999

This document will detail how you can convert your existing web browser to support iKnapsack™. As you will see, it only takes the addition of a few lines of code to turn your web browser into one that supports iKnapsack.

Overview

iKnapsack makes use of some features from the Palm VII™ connected organizer. In web clipping applications, there are two additional URLs that are valid in form submissions and anchor tags:

palm
palmcall

palm and palmcall which allow for web clipping pages to send data to other applications on the handheld. Your web browser should support these URLs. The next two sections details how to handle requests for palm and palmcall.

palm

Calls to palm will call SysUIAppSwitch to the application with the specified Creator ID. The entire URL-string is sent as the parameter block to the application.

Adding palm support to your web browser

Consider the following two functionally equivalent examples:

	<A HREF="palm:iSAK.appl">Open iKnapsack</A>

or

	<FORM METHOD="get" ACTION="palm:iSAK.appl">
		<INPUT TYPE="submit" VALUE="Open iKnapsack">
	</FORM>

To make your browser iKnapsack-enabled, you should perform the following action when these links are tapped:

	// url: Pointer to the URL-string "palm:iSAK.appl"
	// creator: 'iSAK' Creator ID for iKnapsack that was specified in the palm request above
	
	UInt			cardNo;
	LocalID			dbID;
	DmSearchStateType	searchState;
	Err			err;
	
	// Find the application with the specified Creator ID
	err = DmGetNextDatabaseByTypeCreator(true, &searchState, sysFileTApplication, creator, true, &cardNo, &dbID);
	if(!err) {
		// Lock the pointer to the URL-string
		MemPtrSetOwner(url, 0);
		
		// Launch the application with the parameter block set to the URL-string
		err = SysUIAppSwitch(cardNo, dbID, sysAppLaunchCmdNormalLaunch, url);
	} else {
		// Application could not be found
	}

In palm the called application will process the data and not return to your web browser. Your browser exits due to the call to SysUIAppSwitch.

palmcall

Calls to palmcall will use SysAppLaunch to sublaunch the application with the specified Creator ID. The entire URL-string is sent as the parameter block to the application.

Adding palmcall support to your web browser

Consider the following two functionally equivalent examples:

	<A HREF="palmcall:iSAK.appl?iPLG=iMEM&text=Hello World!">Add Memo</A>

or

	<FORM METHOD="get" ACTION="palmcall:iSAK.appl">
		<INPUT TYPE="hidden" NAME="iPLG" VALUE="iMEM">
		<INPUT TYPE="hidden" NAME="text" VALUE="Hello World">
		<INPUT TYPE="submit" VALUE="Add Memo">
	</FORM>

To make your browser iKnapsack-enabled, you should perform the following action when these links are tapped:

	// url: Pointer to the URL-string "palmcall:iSAK.appl?iPLG=iMEM&text=Hello World!"
	// creator: 'iSAK' Creator ID for iKnapsack that was specified in the palm request above
	
	// This is the launch code that you send to the application with the specified Creator ID
	#ifndef sysAppLaunchCmdURLParams
	#define sysAppLaunchCmdURLParams	50
	#endif
	
	UInt			cardNo;
	LocalID			dbID;
	DmSearchStateType	searchState;
	DWord			result = 0;
	Err			err;
	
	// Find the application with the specified Creator ID
	err = DmGetNextDatabaseByTypeCreator(true, &searchState, sysFileTApplication, creator, true, &cardNo, &dbID);
	if(!err) {
		// Lock the pointer to the URL-string
		MemPtrSetOwner(url, 0);
		
		// Sublaunch the application with the parameter block set to the URL-string
		err = SysAppLaunch(cardNo, dbID, 0, sysAppLaunchCmdURLParams, url, &result);
	} else {
		// Application could not be found
	}

In palmcall the called application will process the data and return to your web browser.

StringToCreatorID

This helper function is useful for taking the Creator ID string from a palm or palmcall request and converting it into a format readable to the Palm OS.

/***********************************************************************
 *
 * FUNCTION:    StringToCreatorID
 *
 * DESCRIPTION: Converts a string into a Creator ID
 *
 * PARAMETERS:  str - the four character creator id string to convert
 *
 * RETURNED:    Creator ID or 0 on error
 *
 ***********************************************************************/
 
static ULong StringToCreatorID(CharPtr str)
{
	int		i;
	ULong	creator = 0;
	
	if(StrLen(str) >= 4) {
		for(i = 0; i < 4; i++)
			creator = ((ULong) creator << 8) + (ULong) str[i];
			
		return creator;
	}
	else return 0;
}