TealDoc Launch Commands Updated 7/6/2004 TealDoc supports two launch commands which can be used to start the app externally and automatically open a specified document. These are similar to the commands it can issue to launch other applications and databases from link buttons: ======================================================================= ======================================================================= 1) NEW TEALDOC 6 STANDARD CALLING CONVENTIONS TealDoc 6.33 and TealPoint apps moving forward use a convenient calling convention that supports launching the program and instructing it to automatically open files from both RAM and external SD cards. ======================================================================= 2) MACHINE LAUNCH INFO STRUCT The following structure is used in the process: typedef struct { long launch_mode; // 'OPEN', 'FIND', or 'SEEK' void *reserved1; void *reserved2; void *reserved3; void *reserved4; // File to open (For all launch modes) long open_device; // Device where file exists; 0=RAM 1=first card, etc char open_path[256]; // Null-terminated path to file if not RAM char open_name[80]; // Name of the file to open // Option app to return to (For all launch modes) long call_return; // Optional CreatorID of app to return to after doc is closed // For 'SEEK' long seek_offset; // Byte offset to seek into file when opened long seek_count; // Count of characters to highlight (if nonzero) // Optional Record/Field to open (For all launch modes) short dbase_record; // Not used by TealDoc long dbase_field; // Not used by TealDoc // For 'FIND' char find_text[1]; // Optional text to search for } MACHINE_LAUNCH_INFO; ======================================================================= 3) CALLING METHOD To initiate a call, allocate a block of memory and fill it with a PalmOS GoToParamsType structure followed by a MACHINE_LAUNCH_INFO structure tacked onto the end. Set the "matchPos" field in the GoToParamsType structure to 2 (to differentiate it from older TealPoint calling conventions) and fill "matchCustom" with the starting address of the MACHINE_LAUNCH_INFO struct. ======================================================================= 4) SAMPLE CODE //-------------------------------------------------------------------------- // // StartDoc() // // The following example function will launch TealDoc, instructing it to // open a file and optionally look for text and/or return to the calling // app. // // Examples: // // To open a file named "MyBook" in RAM: // // StartDoc( 'OPEN', 0, "", "MyBook", NULL, 0L ); // // To open a file named "MyBook.PDB" on an SD card: // // StartDoc( 'OPEN', 1, "Palm/Launcher", "MyBook.PDB", NULL, 0L ); // // To open a file and return (to app with creatorID 'AbCd') when done // // StartDoc( 'OPEN', 0, "", "MyBook", NULL, 'AbCd' ); // // To open a file and search for the text "Freddie" // // StartDoc( 'FIND', 0, "", "MyBook", "Freddie", 0L ); // //-------------------------------------------------------------------------- void StartDoc( long command, short device, char *path, char *name, char *search_text, long return_app ) { MACHINE_LAUNCH_INFO *mli; GoToParamsType *gotoparams; UInt prog_card; LocalID prog_id; DmSearchStateType sst; // Find TealDoc if ( DmGetNextDatabaseByTypeCreator( true, &sst, (ULong)'appl', (ULong)'TlDc', true, &prog_card, &prog_id ) == 0 ) { // Allocate working struct if (gotoparams = MemPtrNew(sizeof(GoToParamsType) + sizeof(MACHINE_LAUNCH_INFO) + ((search_text && search_text[0])?StrLen(search_text)+1:0) )) { MemPtrSetOwner( gotoparams, 0 ); // Set GoTo Struct MemSet( gotoparams, sizeof(GoToParamsType), 0 ); gotoparams->matchPos = 2; gotoparams->matchCustom = (long)&gotoparams[1]; // Set MLI struct mli = (void *)&gotoparams[1]; MemSet( mli, sizeof(MACHINE_LAUNCH_INFO), 0 ); mli->launch_mode = command; mli->open_device = device; if (path) StrCopy( mli->open_path, path ); StrCopy( mli->open_name, name ); mli->call_return = return_app; if (search_text && search_text[0]) StrCopy( mli->find_text, search_text ); SysUIAppSwitch( prog_card, prog_id, sysAppLaunchCmdGoTo, (void *)gotoparams ); } } } ======================================================================= ======================================================================= 5) Old Legacy calling conventions Older versions of TealDoc used a more cumbersome calling convention. This method will still be maintained in TealDoc for backwards compatibility, but will not be supported by newer TealPoint apps. ======================================================================= sysAppLaunchCmdGoTo This mechanism uses the standard system command intended to launch a program in response to a global find, but may also be used to launch TealDoc with a given document. Parameters are passed in a standard GoToParamsType structure with the following parameters: dbCardNo - card of the document to open dbID - LocalID of the document to open matchPos - seek mode as follows if matchPos is 1 : matchCustom - pointer to a string in document to seek to if matchPos is 0 : matchCustom - Byte offset into the file in which to seek * OR * CreatorID of an app to return to when the doc is closed matchFieldNum - Count of chars to highlight from the offset or 0 ADDENDUM FOR 4.60: To launch a document found on an external storage card (SD, CF, etc), set dbCardNo to -1 and dbID to the index of the file to launch. To specify the file by name, allocate additional space to the end of the buffer containing the GoToParamsType structure and tack the full path to the file (e.g. "\documents\mydoc.pdb") to the end of the structure. -------------------------------------------------------------------------- sysAppLaunchCmdOpenDB The openDB command, added in Palm OS 3.x, is similar, but can only seek to the top of the document and uses the SysAppLaunchCmdOpenDBType structure cardNo - memory card of the document to open dbID - LocalID of the document to open Note: Use the PalmOS function SysUIAppSwitch() to launch the program. The structures you pass to TealDoc must be allocated in RAM whose owner field has been set to 0 or they will be freed when your application exits. ADDENDUM FOR 4.60: To launch a document found on an external storage card (SD, CF, etc), set dbCardNo to -1 and dbID to the index of the file to launch. To specify the file by name, allocate additional space to the end of the buffer containing the GoToParamsType structure and tack the full path to the file (e.g. "\documents\mydoc.pdb") to the end of the structure. -------------------------------------------------------------------------- Sample Code: // // The following example will launch TealDoc, instructing it to open a file // and seek to a specified byte offset // void StartDoc( UInt doc_card, LocalID doc_id, int mode, long location ) { GoToParamsType *gotoparams; UInt prog_card; LocalID prog_id; DmSearchStateType sst; if ( DmGetNextDatabaseByTypeCreator( true, &sst, (ULong)'appl', (ULong)'TlDc', true, &prog_card, &prog_id ) == 0 ) { if (gotoparams=MemPtrNew(sizeof(GoToParamsType))) { MemPtrSetOwner( gotoparams, 0 ); MemSet( gotoparams, sizeof(*gotoparams), 0 ); gotoparams->dbCardNo = doc_card; gotoparams->dbID = doc_id; gotoparams->recordNum = mode; gotoparams->matchCustom = (void *)location; SysUIAppSwitch( prog_card, prog_id, sysAppLaunchCmdGoTo, (void *)gotoparams ); } } }