Writing iKnapsack Plug-ins

by Adam Tow and Foundation Systems
Last updated: September 30, 1999

This document details how to write an iKnapsack Plug-in. The process of developing a plug-in is broken down into four steps:

Download The Starter iKnapsack Plug-in Project
Tour Of An iKnapsack Plug-in
Processing Data In Your Plug-in
Building Your Plug-in

Step 1: Download the Starter iKnapsack Plug-in Project

The first step in learning how to write iKnapsack Plug-ins is to download the Starter iKnapsack Plug-in project. This is a project compiled in CodeWarrior for Palm Computing Platform, Release 5.

Starter iKnapsack Plug-in Project (Stuffit 5.1)
Starter iKnapsack Plug-in Project (Stuffit 5.1/Binhex)

The project contains the following files:

Starter Plug-in.mcp: Metrowerks CodeWarrior project file
Starter Plug-in.c: Main source code for the plug-in
Starter Plug-in.rsrc: Constructor for Palm OS resource file
Starter Plug-in_res.h: Header file for "Starter Plug-in.rsrc" file
FS_iKnapsack_Plugin_API.h: Constants and definitions for iKnapsack Plug-ins
Starter Plug-in.prc: The Starter Plug-in that you can install on your handheld

Step 2: Tour Of An iKnapsack Plug-in

An iKnapsack Plug-in is a PalmOS Code Resource instead of the more common PalmOS Application.

The 68K Target Pane in the Starter Plug-in Settings Dialog Box of CodeWarrior

The primary advantage to this is that your plug-in does not appear in the Launcher and is generally smaller than a typical Palm OS application.

Creator ID

A Creator ID is a four-character code that uniquely identifies your product to the Palm OS. Each plug-in has a unique Creator ID which is used by web sites and Palm applications to instruct the iKnapsack application as to which iKnapsack Plug-in to use. For instance, the Creator ID's for the plug-ins that come with iKnapsack include:

iADR: Add Address
iDAT: Add Date
iEXP: Add Expense
iMEM: Add Memo
iTOD: Add To Do
iURL: Open URL

When creating your own plug-ins, you must assign them a Creator ID and register that ID with Palm Computing at: http://oasis.palm.com/devzone/creatorid/. You can search for existing Creator ID's on that site as well.

PlugInMain

In the "Starter Plug-in.c" file, there is a function called PlugInMain. This is the main routine for your iKnapsack Plug-in and is called whenever there is a request to process data with your plug-in.


	Err PluginMain(PluginParamBlockPtr PluginParamsP)

Parameters

PlugInMain receives one parameter, a pointer to a PluginParamBlockType structure:

	typedef struct {
		CharPtr url;
		VoidPtr	other;
		Int	mode;
		DWord	d1;
		DWord   d2;
	} PluginParamBlockType;

Each parameter in the PluginParamBlockType structure is explained in greater detail below.

url
This is the data stream sent from a web page or a Palm application to your plug-in. Your plug-in function operates on this data.

other
This parameter is filled when a Palm application calls your plug-in and can be used to store application-specific information. If your plug-in is called from a web page, this parameter is unused.

mode
This is an integer telling your plug-in what mode it should run in. If the value for mode is 0, your plug-in should process the data in the url parameter of the PluginParamBlockType structure. If the value is 1, your plug-in should display its configuration panel or alert the user if it does not have one.

d1 and d2
These variables are currently unused and are reserved for future use.

Return Type

PlugInMain should return 0 if there was no error or non-zero if there was an error. If you handled an error in your plug-in and alerted the user, you should return 0. Otherwise, iKnapsack will display the alert on the right to the user.

This error is displayed by iKnapsack whenever you return a non-zero value from PlugInMain

PlugInMain Example

Here is a the PlugInMain routine from our Starter iKnapsack Plug-in project.


/***********************************************************************
 *
 * FUNCTION:    PluginMain
 *
 * DESCRIPTION: Your function that handles a Plug-in call from
 *              iKnapsack.
 *
 * PARAMETERS:  The parameters of PluginParamsP:
 *
 *              url   - the url-string containing data
 *              other - developer-specific information
 *              mode  - 0 = Run 
 *                      1 = Config
 *                      anything else = Developer Specific
 *
 * RETURNED: 0 - Success or Error Handled by Plugin
 *           non-zero - iKnapsack will report the error to the user
 *
 *
 ***********************************************************************/
 
Err PluginMain(PluginParamBlockPtr PluginParamsP)
{
	Err err = 0;
	
	switch(PluginParamsP->mode) {
		case kPluginModeRun:	// Mode = 0
			
			// Your code to handle the plug-in request
			// Data is stored in PluginParamsP->url
			
			break;
		
		case kPluginModeConfig:	// Mode = 1
			
			// Your code to handle the plug-in config request
			// If you Plugin does not have a configuration panel,
			// alert the user.
			
			FrmAlert(NoConfigAlert);
					
			break;
			
		default: break;
	}	
	return err;
}

Information Form

View your information dialog by selecting your plug-in and tapping Info. The form which appears has the ID 5000 and is created in Constructor for Palm OS.

Display parameter and usage information in the Help string for your information dialog

Every iKnapsack Plug-in must have an information screen which is displayed when the user selects Info on your iKnapsack in the Plug-ins form. This form has an ID of 5000 and is invoked by FrmDoDialog so it must contain a button that will exit the dialog.

It is a good idea to associate a Help String with your Information Dialog. You can place parameter and usage information in this resource.

3. Processing Data In Your Plug-in

The next to last step in creating your iKnapsack Plug-in is the funnest, and the most difficult: Processing the data! It's easy to get data to your Plug-in, but converting it into something your code can deal with can be a hassle. Fortunately, we have many of the pieces coded for you.

Use the routines in the FS_Web.c and FS_Web.h source files to assist you in parsing parameters, converting between the Palm OS and Internet Date and Time formats and more.

More information on parsing data is forthcoming.

4. Building Your Plug-in

Your Plug-in is finished! Now, build the project and install it onto your device or the Palm OS Emulator. Note that you won't be able to debug your project since it is a Code Resource. You may want to build your project as an application and then later convert it into a Plug-in.