Welcome to the Pilot Generic Conduit Manager VERSION 11 NOTICE ---------------- The DinkyVw and PMoneyView user-interface is crude, crude. This will improve in the near future. DO NOT DO A BOTHWAY SYNC OF PILOT MONEY! IT IS NOT SUPPORTED! DO NOT INSTALL IF YOU ARE USING HOTSYNC 1.1 Features -------- -provides data backup services for any Pilot app -fixes the data backup conduit problems of HotSync 1.0 -easy selection of data-restore options -does backup and restore for any Pilot app, even without a corresponding PC app -multiple backup files created -actually speeds up the HotSync process -preconfigered setups for conduits -DinkyPad -cbasPad -Pilot Money -bundled with PC viewers for DinkyPad and cbasPad Notice ------ THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND. THROUGH THE USE OF THIS SOFTWARE YOU ACCEPT THE POSSIBLE LOSS OF DATA OR PRODUCTIVITY. The Programs ------------ GenCond.dll is the heart of the Conduit Manager system CondMgr.exe is a VB app to manage the installation and removal of GenCond conduits cbasView.exe is a VB app to view, create or delete entries for the cbasPad application DinkyVw.exe is a VB app to view, create, delete, import, export/save or print entries for the DinkyPad Pilot application DinkVwA.dll support code for the above PMoneyView.exe is a VB app to view Pilot Money data on your PC The GenCond.dll requires MSVCRT40.DLL The VB programs require VB40032.DLL. The DinkyVw.exe program requires the GenCond.dll program, and there MUST be a copy of GenCond.dll in the same directory as DinkyVw.exe. Installation and Usage ---------------------- THIS VERSION IS FOR HOTSYNC 1.0 ONLY! DO NOT USE THIS VERSION WITH HOTSYNC 1.1! Simply extract all the files to a working directory. Run the CondMgr.exe program, and select the first menu item. This -modifieds the registry -copies GenCond.dll to the pilot directory Install any of the pre-configured conduits, or install a custom. On the next HotSync, your data transfers will occur. The cbasView program usage is obvious. Just run it. The DinkyVw program allows: auto-select of the current sync file; other files can be opened with the browse button save your work save a picture as a bitmap file copy to the clipboard paste from the clipboard crude drawing on screen print single file or the whole collection new and delete of individual pictures How it Works ------------ The Pilot handheld computer is a wonderful device for personal productivity. It includes the ability to send a copy of all it's information to and from a PC or Macintosh. The built-in applications have "twins" on the PC which allow you to work equally well on either platform, and move the data back and forth, in sync. The third-part applications which have been built normally do not have "twins" on the PC, but the forward thinking designers at Palm put a mechanism in place to automatically backup the Pilot data. Programs like Pilot Money can have all their data backed-up, just in case the Pilot loses all its memory. Unfortunately, there is a minor bug in the code (described in the previous paragraph) and only some of the Pilot data is sent for backup. The Generic Conduit Manager system fixes this problem in a round-about way. When the Generic Conduit Manager is installed, it links a "generic conduit" in place, so that every hot-sync invokes the "generic conduit". This code searches the Win95 registry for Conduit Manager entries and uses the data from there to do a generic hot-sync with the Pilot. Because only modified data is transferred, each database that you couple through the Generic Conduit actually speeds up your hot-sync. [See the note below concerning categories. Not all apps can be both-way hot-sync'd.] The synchronization strategy: Record - unmodified D deleted M modified N new x does not exist Pilot/PC -- do nothing -M PC->Pilot M- Pilot->PC xM PC->Pilot Mx Pilot->PC MM create duplicate on Pilot and PC, cross update -D delete on Pilot D- delete on PC MD over-ride the delete, Pilot->PC DM over-ride the delete, PC->Pilot DD delete on both xD do nothing Dx do nothing Categories This version of the Conduit Manager/Generic Conduit does not handle categories. I will put this in if there is a demand. In other words, if your database uses categories, your database files WILL BE CORRUPTED if you let GenCond.dll sync them. A full PC->Pilot or Pilot->PC sync will work ok, but the both-way sync will not handle the merging of categories properly. You have been warned. The HotSync 1.0 Problem ----------------------- As mentioned above, the Pilot HotSync 1.0 program is a well designed, forward thinking system. It does a good job of backing up data for programs which didn't even exist when it was written. There is a minor bug, which goes as follows: During a hot-sync, the code on the PC asks the Pilot to give it a list of all the data groups contained within the Pilot. The PC code then runs through the registry, and tries to match up each data group with an entry in the registry. Naturally, it finds Address, Todo, Datebook and Memopad, and signals each one to sync itself. Any other data type that has a conduit is run, as well. Any data group which is left over (and marked for backup) is blindly copied to the PC, for a future "restore". (This includes the Grafitti shortcuts, the Giraffe high scores, DinkyPad data, cbasPad data and PilotMoney data). The bug is this: when the PC asks the Pilot for a list of its data groups, only the first 28 are returned. (This list includes the application code as well as the data.) If the user has a fully packed Pilot, many data groups can get left out. Since they don't make it to the PC, a) their conduit never gets called b) they never get backed up. The GenCond.DLL system fixes this problem by working differently. Each conduit that you invoke using the ConduitManager puts an entry in the Win95 registry. During a hot-sync, the registry is scanned, and each ConduitManager conduit is invoked, which transfers the data to and from the Pilot. Generic Conduit Manager for Developers -------------------------------------- The Palm/USR conduit system is designed to allow a hotsync to occur with both native and foreign data. The designers assume that foreign data is in such a format that code will have to be written to implement a hotsync. Therefore, the conduit system assumes that each conduit will be different/unique. And that the data format for each conduit will be different/unique. The designers of the HotSync system also provide a "backup conduit" which simply transfers raw data, in bulk. I felt that these assumptions were a bit onerous. They assume that everybody who develops a PC app will be interested and capable of writing a DLL. I didn't think this was a reasonable assumption. [Aside: To be a "real" Pilot programmer, you have to be conversent in 4 API's (Mac, Pilot, Win32 and ConduitSDK). That's 2 too many for me.] The Conduit Manager system uses a generic conduit, which can sync any Pilot database on a record-by-record basis. In order to do this, here are my assumptions: -the data storage format on the PC is fixed -the data storage format on the PC uses big-endian numbers (like a Macintosh) -the PC programmer is willing to read and write files that conform to these constraints This means that developers on the PC can work at a simpler level. There is no need to learn the entire Conduit management system. On the other hand, we (the PC developers) have to write the code to read and write MAC style numbers, and deal with fixed format records that are created by a foreign app. If you can live with this, climb abord. In the coming weeks, I will bolster this package with documentation on the file formats, and sample code for the use of the GenCond.DLL and the Generic Conduit Manager. Features for programmers ------------------------ -provides a programming environment for creating sync'ing apps -enables auto-install of apps or data Future Features --------------- The 1.1 release of the Conduit Manager will include: -operation in the HotSync 1.1 environment -auto-backup of your entire pilot, including all apps and data (but probably not "preferences") Contact ------- patb@corel.ca Shareware Status ---------------- It's too early in the cycle, but this project will be either shareware or freeware. The decision is based on your feedback. History ------- X11 Dec 4/96 DinkyVw 2.3 -changed the about box -fixed a benign bug in "new picture" code -changed printing back to PaintPicture() call ConduitManager 0.6 -added interlock for detecting HotSync 1.1 X10 Dec 2/96 DinkyVw 2.2 -changed help system to .htm file X9 Dec 2/96 ConduitManager 0.5 -fixed DDE string for DinkyVw (should be "DinkyVw") DinkyVw 2.2 -changed external DLL from gencond.dll to dinkvwa.dll (you no longer need to run DinkyVw from the Pilot directory) X8 Nov 28/96 ConduitManager 0.4 -fixed serious problems with the install X7 Nov 27/96 ConduitManager0.3 -added help text as an HTML file -modified the install so that DLL dependencies are checked (specifically, MSVCRT40.DLL) -modified the registry enumeration so that numeric gaps in the keys are visible DinkyVw2.1 -added a crude 'overview' so that you can select a bitmap quickly from the collection X6 Nov 26/96 -added a Pilot Money viewer -changed the conduit manager so that the PilotMoney conduit defaults to 'Pilot to PC' X5 Nov 25/96 -got rid of MFC dependencies; this version only requires MSVCRT40; BTW, this code is written in VisualC++ 4.1. -fixed backup file management -improved sync logic, especially for DinkyPad -fixed slow-sync logic unnumbered Nov17/96 private release to some developers ====================================================================== ====================================================================== ====================================================================== ====================================================================== Tech Notes ---------- (hackers only) In order to write a generic conduit, I had to figure out how to make sure that the conduit gets called by the HotSync system. Using HotSync 1.0, that is not simple, since the HotSync.exe (actually syncmgr.dll) enumerates the databases in the Pilot, and only calls the DLL's that are required to service this list. If the app that the user has requested does not make it onto this enumeration, the DLL will not get called. To get around this, I install a proxy in the MemoPad conduit, by inserting an ApplicationX registry entry. During the startup of the gencond.dll, I reach back into the Component3 registry entry and execute the memcond.dll first, and then run through the ConduitManager entries. For each one, the gencond.dll uses the registry information to locate a file and reads it into memory. It then tries to sync up, record by record and creates a new local file. If all went well, the old file is renamed and the new file written. DDE --- If you have an application that is running, it will get a couple of DDE messages. Before the file is opened by the conduit, you will get a "application/notify" message command with the string "sync start". You have 1.5 seconds to write the file to disk before the gencond.dll will try to read it. After the file has been written, you will get a "application/notify" message command with the string "sync finished". You can then re-read the file into the app. [All records will be marked clean, and deleted records will have been purged.] [Look at the source for cbasVw, in Form_LinkExecute.] Locating User Files ------------------- In order to locate the files, each time the gencond.dll is executed, it puts an entry in the registry: HKCU/Software/Palm Computing/PilotDesktop/Preferences/LastUserDir ="name of user dir, without trailing backslash" To locate the data files, simply concatenate a "\DirName" to this string. This should be the same DirName that the user put into the ConduitManager. Examples are "DinkyVw" or "cbasVw". Services -------- If you wish to use it, the DinkVwA.DLL and GenCond.DLL export a simple little routine to build up multiple backup files. /*SDOC Function: MakeBackupFiles Params: sFileName the name of the target file nBackups the number of backups to keep Action: The sFileName is used to locate a directory where the output files will go. If the sFileName does not exist, the function exits with a 0 The current backup files are enumerated and the actual file called sFileName will be renamed to a backup file. Files which exceed the backup limit are deleted. Returns: 0 if no file activity took place; usually means that the given file does not exist Comment: Style 0 backups proceed like file.txt (original) file.txt.1 file.txt.2 file.txt.3 ... (note: this destroys the Win95/NT association) EDOC*/ C/C++ int MakeBackupFiles(const char* sFileName, int nBackups); VB Declare Function MakeBackupFiles lib "gencond.dll" alias _ "_MakeBackupFiles@8" (ByVal sFileName as String, _ ByVal nBackups as Long) as Long