Previous Page Table of Contents Index Next Page

Palm OS Programmer's Companion


Palm Logo 15 Standard IO Applications

The Palm OS® supports command line (UNIX style) applications for debugging and special purposes such as communications utilities. This capability is not intended for general users, but for developers. This feature is not implemented in the Palm OS, but rather by additional C modules that you must link with your application.

NOTE:  

Don't confuse this standard IO functionality with the file streaming API. They are unrelated.

There are two parts necessary for a standard IO application:

The details of creating these two different applications are described in the following sections.

Creating a Standard IO Application

To create a standard IO application, you must include the header file StdIOPalm.h. In addition to including this header, you must link the application with the module StdIOPalm.c. This module provides a PilotMain routine that extracts the command line arguments from the cmd and cmdPBP parameters and the glue code necessary for executing the appropriate callbacks supplied by the standard IO provider application.

You build the application normally, but give it a database type of sioDBType ('sdio') instead of 'appl'. In addition, it must be named "Cmd-cmdname" where cmdname is the name of the command used to execute the application. For example, the ping command would be placed in a database named "Cmd-ping".

In the Palm VII device, the Network panel, whose log window is a standard IO provider application, has two standard IO commands built-in: info and finger. The ROM has two additional ones: ping and nettrace.

When compiling for the Palm device, the entry point must be named SioMain and must accept two parameters: argc and argv. Here's the simplest possible example of a standard IO application.

#include <StdIOPalm.h>
Int16 SioMain(UInt16 argc, Char* argv[ ])
{ printf("Hello World\n");
}

Standard IO applications can use several input and output functions that mimic their similarly named UNIX counterparts. These are listed in the summary table at the end of this chapter.

Your standard IO application can accept input from stdin and write output to stdout. The stdin device corresponds to the text field in the standard IO provider application that is used for input and output. The stdout device corresponds to that same text field.

Creating a Standard IO Provider Application

In order for a standard IO application to be invoked and able to provide results, you need a standard IO provider application. This application provides the user interface support; that is, the stdin device support and the stdout window that the standard IO application reads from and writes to.

The standard IO provider sublaunches the standard IO application when the user types in a command line and Return (using Graffiti®). The provider application passes a structure pointer that contains the callbacks necessary for performing IO to the standard IO application through the cmdPBP parameter of PilotMain.

To create a standard IO provider application, you must link the application with the module StdIOProvider.c.

To handle input and output, the standard IO provider application must provide a form with a text field and a scroll bar. The standard IO provider application must do the following:
Call SioInit during application initialization. SioInit saves the object ID of the form that contains the input/output field, the field itself, and the scroll bar. Call SioHandleEvent from the form's event handler before doing application specific processing of the event. In other words, the form event handler that the application installs with FrmSetEventHandler should call SioHandleEvent before it does anything else with the event. Call SioFree during application shutdown.

The application is free to call any of the standard IO macros and functions between the SioInit and SioFree calls. If the current form is not the standard IO form when these calls are made, they will record changes to the active text and display it the next time the form becomes active.

A typical standard IO provider application will have a routine called ApplicationHandleEvent, which gets called from its main event loop after SysHandleEvent and MenuHandleEvent. An example is shown in Listing 15.1.

Listing 15.1 Standard IO Provider ApplicationHandleEvent Routine


    static Boolean ApplicationHandleEvent (EventPtr event)
    {
    FormType* frm;
    UInt16 formId;

    if (event->eType == frmLoadEvent) {
    formId = event->data.frmLoad.formID;
    frm = FrmInitForm (formId);
    FrmSetActiveForm (frm);
   
    switch (formId) {
    .....
    case myViewWithStdIO:
    FrmSetEventHandler (frm, MyViewHandleEvent);
    break;
    }
    return (true);
    }

    return (false);
    }


A typical application form event handler is shown in Listing 15.2.

Listing 15.2 Standard IO Provider Form Event Handler


    static Boolean MyViewHandleEvent (EventPtr event)
    {
    FormType* frm;
    Boolean handled = false;

    // Let StdIO handler do its thing first.
    if (SioHandleEvent(event)) return true;

    // If StdIO did not completely handle the event...
    if (event->eType == ctlSelectEvent) {
    switch (event->data.ctlSelect.controlID) {
    case myViewDoneButtonID:
    FrmGotoForm (networkFormID);
    handled = true;
    break;
    }
    }

    else if (event->eType == menuEvent)
    return MyMenuDoCommand( event->data.menu.itemID );
   
    else if (event->eType == frmUpdateEvent) {
    MyViewDraw( FrmGetActiveForm() );
    handled = true;
    }

    else if (event->eType == frmOpenEvent) {
    frm = FrmGetActiveForm();
    MyViewInit( frm );
    MyViewDraw( frm );
    handled = true;
    }

    else if (event->eType == frmCloseEvent) {
    frm = FrmGetActiveForm();
    MyViewClose(frm);
    }

    return (handled);
    }


Summary of Standard IO

Standard IO Macros and Functions
fgetc
fgets
fprintf
fputc
fputs
getchar
gets
printf
putc
putchar
puts
SioAddCommand
SioMain
sprintf
system
vfprintf
vsprintf

Standard IO Provider Functions
SioClearScreen
SioExecCommand
SioFree
SioHandleEvent
SioInit



Palm OS Programmer's Companion

  Previous Page Table of Contents Index Next Page  

This is page 84 of 85 in this book

Palm Computing Platform Development Zone
Copyright © 2000, Palm, Inc. All rights reserved.