home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PILOT / support / GCM13 / GCM13.ZIP / CONDMGR.TXT < prev    next >
Encoding:
Text File  |  1996-12-04  |  13.4 KB  |  413 lines
  1. Welcome to the Pilot Generic Conduit Manager
  2.  
  3. VERSION 11 NOTICE 
  4. ----------------
  5. The DinkyVw and PMoneyView user-interface is crude, crude. This will improve
  6. in the near future.
  7.  
  8. DO NOT DO A BOTHWAY SYNC OF PILOT MONEY! IT IS NOT SUPPORTED!
  9.  
  10. DO NOT INSTALL IF YOU ARE USING HOTSYNC 1.1
  11.  
  12.  
  13. Features
  14. --------
  15.  
  16. -provides data backup services for any Pilot app
  17.     -fixes the data backup conduit problems of HotSync 1.0
  18.     -easy selection of data-restore options
  19.     -does backup and restore for any Pilot app, even without
  20.         a corresponding PC app
  21.     -multiple backup files created
  22.     -actually speeds up the HotSync process
  23. -preconfigered setups for conduits
  24.     -DinkyPad
  25.     -cbasPad
  26.     -Pilot Money
  27. -bundled with PC viewers for DinkyPad and cbasPad
  28.  
  29.  
  30. Notice
  31. ------
  32. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS,
  33. WITHOUT WARRANTY OF ANY KIND. THROUGH THE USE OF THIS SOFTWARE
  34. YOU ACCEPT THE POSSIBLE LOSS OF DATA OR PRODUCTIVITY.
  35.  
  36.  
  37.  
  38. The Programs
  39. ------------
  40.     GenCond.dll    is the heart of the Conduit Manager system
  41.     CondMgr.exe    is a VB app to manage the installation and
  42.             removal of GenCond conduits
  43.     cbasView.exe    is a VB app to view, create or delete
  44.             entries for the cbasPad application
  45.     DinkyVw.exe    is a VB app to view, create, delete, import,
  46.             export/save or print entries for the DinkyPad
  47.             Pilot application
  48.     DinkVwA.dll    support code for the above
  49.     PMoneyView.exe    is a VB app to view Pilot Money data on your PC
  50.  
  51. The GenCond.dll requires MSVCRT40.DLL
  52.  
  53. The VB programs require VB40032.DLL. The DinkyVw.exe program requires
  54. the GenCond.dll program, and there MUST be a copy of GenCond.dll in
  55. the same directory as DinkyVw.exe.
  56.  
  57.  
  58. Installation and Usage
  59. ----------------------
  60.  
  61. THIS VERSION IS FOR HOTSYNC 1.0 ONLY! DO NOT USE THIS VERSION
  62. WITH HOTSYNC 1.1!
  63.  
  64. Simply extract all the files to a working directory. Run the
  65. CondMgr.exe program, and select the first menu item. This 
  66.     -modifieds the registry
  67.     -copies GenCond.dll to the pilot directory
  68.  
  69. Install any of the pre-configured conduits, or install a custom.
  70. On the next HotSync, your data transfers will occur.
  71.  
  72. The cbasView program usage is obvious. Just run it.
  73.  
  74. The DinkyVw program allows:
  75.     auto-select of the current sync file; other files can be
  76.         opened with the browse button
  77.     save your work
  78.     save a picture as a bitmap file
  79.     copy to the clipboard
  80.     paste from the clipboard
  81.     crude drawing on screen
  82.     print single file or the whole collection
  83.     new and delete of individual pictures
  84.  
  85.  
  86.  
  87.  
  88. How it Works
  89. ------------
  90.  
  91. The Pilot handheld computer is a wonderful device for personal productivity.
  92. It includes the ability to send a copy of all it's information to and from
  93. a PC or Macintosh.
  94.  
  95. The built-in applications have "twins" on the PC which allow you
  96. to work equally well on either platform, and move the data back
  97. and forth, in sync.
  98.  
  99. The third-part applications which have been built normally do not
  100. have "twins" on the PC, but the forward thinking designers at Palm
  101. put a mechanism in place to automatically backup the Pilot data.
  102. Programs like Pilot Money can have all their data backed-up, just in
  103. case the Pilot loses all its memory.
  104.  
  105. Unfortunately, there is a minor bug in the code (described in the 
  106. previous paragraph) and only some of the Pilot data is sent
  107. for backup.
  108.  
  109. The Generic Conduit Manager system fixes this problem in a round-about
  110. way.
  111.  
  112. When the Generic Conduit Manager is installed, it links a "generic conduit"
  113. in place, so that every hot-sync invokes the "generic conduit".
  114. This code searches the Win95 registry for Conduit Manager entries
  115. and uses the data from there to do a generic hot-sync with the Pilot.
  116.  
  117. Because only modified data is transferred, each database that you
  118. couple through the Generic Conduit actually speeds up your hot-sync.
  119. [See the note below concerning categories. Not all apps can be
  120. both-way hot-sync'd.]
  121.  
  122. The synchronization strategy:
  123.  
  124. Record
  125.     - unmodified
  126.     D deleted
  127.     M modified
  128.     N new 
  129.     x does not exist
  130.  
  131. Pilot/PC
  132. --    do nothing
  133. -M    PC->Pilot
  134. M-    Pilot->PC 
  135. xM    PC->Pilot
  136. Mx    Pilot->PC 
  137. MM    create duplicate on Pilot and PC, cross update 
  138. -D    delete on Pilot 
  139. D-    delete on PC 
  140. MD    over-ride the delete, Pilot->PC 
  141. DM    over-ride the delete, PC->Pilot 
  142. DD    delete on both
  143. xD    do nothing
  144. Dx    do nothing
  145.  
  146.  
  147. Categories
  148.  
  149. This version of the Conduit Manager/Generic Conduit does not
  150. handle categories. I will put this in if there is a demand.
  151.  
  152. In other words, if your database uses categories, your database files
  153. WILL BE CORRUPTED if you let GenCond.dll sync them. A full PC->Pilot
  154. or Pilot->PC sync will work ok, but the both-way sync will not handle
  155. the merging of categories properly. You have been warned.
  156.  
  157.  
  158.  
  159. The HotSync 1.0 Problem
  160. -----------------------
  161.  
  162. As mentioned above, the Pilot HotSync 1.0 program is a well designed,
  163. forward thinking system. It does a good job of backing up data for
  164. programs which didn't even exist when it was written.
  165.  
  166. There is a minor bug, which goes as follows: During a hot-sync, the
  167. code on the PC asks the Pilot to give it a list of all the data
  168. groups contained within the Pilot. The PC code then runs through the
  169. registry, and tries to match up each data group with an entry in the
  170. registry. Naturally, it finds Address, Todo, Datebook and Memopad,
  171. and signals each one to sync itself. Any other data type that has a
  172. conduit is run, as well. Any data group which is left over (and
  173. marked for backup) is blindly copied to the PC, for a future
  174. "restore". (This includes the Grafitti shortcuts, the Giraffe high
  175. scores, DinkyPad data, cbasPad data and PilotMoney data).
  176.  
  177. The bug is this: when the PC asks the Pilot for a list of its data
  178. groups, only the first 28 are returned. (This list includes the
  179. application code as well as the data.) If the user has a fully packed
  180. Pilot, many data groups can get left out. Since they don't make it to
  181. the PC, a) their conduit never gets called b) they never get backed
  182. up.
  183.  
  184. The GenCond.DLL system fixes this problem by working differently.
  185. Each conduit that you invoke using the ConduitManager puts an entry
  186. in the Win95 registry. During a hot-sync, the registry is scanned,
  187. and each ConduitManager conduit is invoked, which transfers the data
  188. to and from the Pilot.
  189.  
  190.  
  191.  
  192. Generic Conduit Manager for Developers
  193. --------------------------------------
  194.  
  195. The Palm/USR conduit system is designed to allow a hotsync to
  196. occur with both native and foreign data. The designers assume
  197. that foreign data is in such a format that code will have to be written
  198. to implement a hotsync. Therefore, the conduit system assumes that
  199. each conduit will be different/unique. And that the data format for
  200. each conduit will be different/unique.
  201.  
  202. The designers of the HotSync system also provide a "backup
  203. conduit" which simply transfers raw data, in bulk.
  204.  
  205. I felt that these assumptions were a bit onerous. They assume that
  206. everybody who develops a PC app will be interested and capable of
  207. writing a DLL. I didn't think this was a reasonable assumption.
  208. [Aside: To be a "real" Pilot programmer, you have to be conversent in
  209. 4 API's (Mac, Pilot, Win32 and ConduitSDK). That's 2 too many for
  210. me.]
  211.  
  212. The Conduit Manager system uses a generic conduit, which can
  213. sync any Pilot database on a record-by-record basis. In order to
  214. do this, here are my assumptions:
  215.     -the data storage format on the PC is fixed
  216.     -the data storage format on the PC uses big-endian
  217. numbers (like a Macintosh)
  218.     -the PC programmer is willing to read and write
  219. files that conform to these constraints
  220.  
  221. This means that developers on the PC can work at a simpler level.
  222. There is no need to learn the entire Conduit management system. On
  223. the other hand, we (the PC developers) have to write the code to read
  224. and write MAC style numbers, and deal with fixed format records that
  225. are created by a foreign app. If you can live with this, climb abord.
  226.  
  227.  
  228. In the coming weeks, I will bolster this package with documentation
  229. on the file formats, and sample code for the use of the GenCond.DLL
  230. and the Generic Conduit Manager.
  231.  
  232.  
  233.  
  234.  
  235. Features for programmers
  236. ------------------------
  237.  
  238. -provides a programming environment for creating sync'ing apps
  239. -enables auto-install of apps or data
  240.  
  241.  
  242.  
  243.  
  244. Future Features
  245. ---------------
  246.  
  247. The 1.1 release of the Conduit Manager will include:
  248. -operation in the HotSync 1.1 environment
  249. -auto-backup of your entire pilot, including all apps and data
  250. (but probably not "preferences")
  251.  
  252.  
  253. Contact
  254. -------
  255.  
  256. patb@corel.ca
  257.  
  258.  
  259.  
  260. Shareware Status
  261. ----------------
  262.  
  263. It's too early in the cycle, but this project will be either
  264. shareware or freeware. The decision is based on your feedback.
  265.  
  266.  
  267.  
  268.  
  269. History
  270. -------
  271.  
  272. X11 Dec 4/96    DinkyVw 2.3
  273.             -changed the about box
  274.             -fixed a benign bug in "new picture" code
  275.             -changed printing back to PaintPicture() call
  276.         ConduitManager 0.6
  277.             -added interlock for detecting HotSync 1.1
  278. X10 Dec 2/96    DinkyVw 2.2
  279.             -changed help system to .htm file 
  280. X9 Dec 2/96    ConduitManager 0.5
  281.             -fixed DDE string for DinkyVw (should be "DinkyVw")
  282.         DinkyVw 2.2
  283.             -changed external DLL from gencond.dll to dinkvwa.dll
  284.             (you no longer need to run DinkyVw from the Pilot directory)
  285. X8 Nov 28/96    ConduitManager 0.4
  286.             -fixed serious problems with the install
  287. X7 Nov 27/96    ConduitManager0.3
  288.             -added help text as an HTML file
  289.             -modified the install so that DLL
  290.             dependencies are checked (specifically,
  291.             MSVCRT40.DLL)
  292.             -modified the registry enumeration so
  293.             that numeric gaps in the keys are visible
  294.         DinkyVw2.1
  295.             -added a crude 'overview' so that you can
  296.             select a bitmap quickly from the collection
  297.  
  298. X6 Nov 26/96    -added a Pilot Money viewer
  299.         -changed the conduit manager so that the PilotMoney conduit
  300.             defaults to 'Pilot to PC'
  301. X5 Nov 25/96    -got rid of MFC dependencies; this version
  302.         only requires MSVCRT40; BTW, this code is
  303.         written in VisualC++ 4.1.
  304.         -fixed backup file management
  305.         -improved sync logic, especially for DinkyPad
  306.         -fixed slow-sync logic
  307. unnumbered Nov17/96 private release to some developers
  308.         
  309.         
  310.  
  311. ======================================================================
  312. ======================================================================
  313. ======================================================================
  314. ======================================================================
  315.  
  316.  
  317.  
  318. Tech Notes
  319. ----------
  320. (hackers only)
  321.  
  322. In order to write a generic conduit, I had to figure out how to make
  323. sure that the conduit gets called by the HotSync system. Using
  324. HotSync 1.0, that is not simple, since the HotSync.exe (actually
  325. syncmgr.dll) enumerates the databases in the Pilot, and only calls
  326. the DLL's that are required to service this list. If the app that the
  327. user has requested does not make it onto this enumeration, the DLL
  328. will not get called.
  329.  
  330. To get around this, I install a proxy in the MemoPad conduit, by
  331. inserting an ApplicationX registry entry. During the startup of the
  332. gencond.dll, I reach back into the Component3 registry entry and
  333. execute the memcond.dll first, and then run through the
  334. ConduitManager entries.
  335.  
  336. For each one, the gencond.dll uses the registry information to locate
  337. a file and reads it into memory. It then tries to sync up, record by 
  338. record and creates a new local file. If all went well, the old file
  339. is renamed and the new file written.
  340.  
  341. DDE
  342. ---
  343. If you have an application that is running, it will get a couple of
  344. DDE messages. Before the file is opened by the conduit, you will get
  345. a "application/notify" message command with the string "sync start".
  346. You have 1.5 seconds to write the file to disk before the gencond.dll
  347. will try to read it.
  348.  
  349. After the file has been written, you will get a "application/notify"
  350. message command with the string "sync finished". You can then re-read
  351. the file into the app. [All records will be marked clean, and deleted
  352. records will have been purged.] [Look at the source for cbasVw, in
  353. Form_LinkExecute.]
  354.  
  355.  
  356. Locating User Files
  357. -------------------
  358.  
  359. In order to locate the files, each time the gencond.dll is executed, 
  360. it puts an entry in the registry:
  361. HKCU/Software/Palm Computing/PilotDesktop/Preferences/LastUserDir
  362. ="name of user dir, without trailing backslash"
  363.  
  364. To locate the data files, simply concatenate a "\DirName" to
  365. this string. This should be the same DirName that the user put
  366. into the ConduitManager. Examples are "DinkyVw" or "cbasVw".
  367.  
  368.  
  369. Services
  370. --------
  371. If you wish to use it, the DinkVwA.DLL and GenCond.DLL export a simple little
  372. routine to build up multiple backup files.
  373.  
  374. /*SDOC
  375.  
  376.   Function: MakeBackupFiles
  377.  
  378.   Params:   sFileName the name of the target file
  379.       nBackups  the number of backups to keep
  380.  
  381.   Action:   The sFileName is used to locate a directory where
  382.       the output files will go.
  383.  
  384.     If the sFileName does not exist, the function exits with a 0
  385.  
  386.       The current backup files are enumerated and
  387.       the actual file called sFileName will
  388.       be renamed to a backup file.
  389.  
  390.     Files which exceed the backup limit are deleted.
  391.  
  392.   Returns: 0 if no file activity took place; usually means that
  393.             the given file does not exist
  394.     
  395.   Comment:
  396.       Style 0 backups proceed like
  397.         file.txt (original)
  398.         file.txt.1
  399.         file.txt.2
  400.         file.txt.3
  401.         ...
  402.        (note: this destroys the Win95/NT association)
  403. EDOC*/
  404.  
  405. C/C++
  406. int MakeBackupFiles(const char* sFileName, int nBackups);
  407.  
  408.  
  409. VB
  410. Declare Function MakeBackupFiles lib "gencond.dll" alias _
  411. "_MakeBackupFiles@8" (ByVal sFileName as String, _
  412. ByVal nBackups as Long) as Long
  413.