About
Downloads
Register/Buy
FAQ

Manual
Features
Screenshots
Reviews/Media
User Forums
User Contributed
Developer Support
Thanks to...


About
Downloads
Register/Buy
Screenshots
User Forums
FAQ
GP32

Free Stuff
Software Support
Requests and Bugs
Home


Shadow XML Basic Specification

Shadow Desktop (and the conduit) store everything in a simple subset of XML following the rules defined here. We have have specifically designed the system to make it easy for the various components to be swapped in and out. You are free to work with Shadow Desktop XML documents provided you too follow the rules outlined here.

  • Shadow Desktop (and conduit) skip a lot of the hubub; only some encodings are understood and many fancy XML tricks are discarded. The usual still applies, of course.. spacing and newlines and such do not apply so you can be free form, but Shadow will just clobber your spacing on saves.

  • Encoding supports are currently: ISO-8859-1, UTF-8, and CP1252. The CP1252 is actually Palm's varient of CP1252 which is identical except for a couple of pass-thru characters which don't display on the handheld.

  • Default values are assumed if the fields are not included; as such, you can write very stripped XML and the desktop will likely interpret it anyway. However, when the desktop or conduit write, they tend to write out most of their fields (including the default values). Perhaps in the future, none-default values will go unwritten, so that new default values can take next iteration..

  • Note/memos are still limited to 4k, even though you can technically put as much as you like into the XML. The excess will be truncated on read/write. Shadow Desktop will limit user input.. I'd rather not limit the carrier, but just limit data entry. The size limit is subject to change as Palm OS grows and the average user unit increases in power.

  • Likewise, the filenames are limited in size to a total of 32 characters (not including the ".XML", but including the "ShadP-" at the front. (The "ShadP-" comes from the handheld side and is used there to make sure filenames are unique to Shadow, even if the user has another file with the same name (since it wouldn't have ShadP- at the front). The desktop keeps the ShadP- present so that the filename is the same on both sides, so as not to confuse the user who may be panicking during a backup restoration :)

  • Content is interpreted in the encoding defined in the encoding meta-tag. UTF-8 is assumed if no encoding is specified.

  • Content goes through some translations; for instance, some basic trouble characters are "escaped" into a weird series of characters defined one long night; they represent dynamic characters that have changed in some Palm OS versions, etc. These will soon be eliminated for standard XML entities.

  • Time's are stored in terms of Palm Epoch, instead of Unix Epoch like the standard C libraries use. Palm Epoch is Jan 1st, 1904, whereas Unix-epoch is Jan 1st, 1970. So in theory, you can add/subtract a constant that is the number of seconds between 1970 and 1904 to convert between the two. (Try 2082844800).

  • The list header is not currently stored in the XML files, and goes undefined at this time.

  • The outermost XML tag must be ShadowPlanFile. Order for attributes is irrelevant.

  • Items are listed in-order in the XML file; children items are simply nested inside of their parent item; style dictates the child item to be the last thing inside of its parent item.

The minimum Shadow XML file is the following (it assumed default values for virtually everything):

<ShadowPlanFile>
</ShadowPlanFile>
  

The minimum useful file is thus this:

<ShadowPlanFile>
  <item>My item title</item>
</ShadowPlanFile>
  

And a single item full XML file is like this:

<?xml version="1.0" encoding="iso-8859-1"?>
<ShadowPlanFile uniqueTime="0" uploadFile="1">
  <item uniqueID="0" dirtyContent="1" dirtyPosition="0" deleted="0"
     checked="no" expanded="no" expandedMemo="no" expandedLinks="no"
     priority="0" progress="0" autoNumber="0" dispColour="0" dispBold="no"
     dispOverride="-1">
    <title>My line title</title>
    <hhCreateTime>0</hhCreateTime>
    <hhTargetTime>0</hhTargetTime>
    <hhStartTime>0</hhStartTime>
    <hhFinishTime>0</hhFinishTime>
    <note>My item note</note>
  </item>
</ShadowPlanFile>

The fields contained therein break down into:

  • uniqueTime: Used simply as a unique identifier for the list; this is used to know whethor the user has deleted a file and created a new one with the same filename.. the XML version and the users new version will have a different uniqueTime, and the conduit will know to clobber its XML file rather than sync the now old and thus missing items. Note that you can use any value you like here.

  • uploadFile: A flag; if non-zero, the XML file will upload to the handheld if it does not already exist there. If it does already exist, it'll sync instead, of course, and this flag is ignored. Let us know if you need a "upload regardless of presence" flag.

  • uniqueID: The item's Palm OS uniqueID on the handheld; 0 (zero) is used for items created on the desktop and not yet assigned a uniqueID (which must be assigned by Palm OS!). The Unique ID is used for syncing. Don't lose it!

  • dirtyContent: If non-zero, you're telling the conduit that the content of this item has changed and needs to be synced. Content refers to title text, dates, and other pure item data.

  • dirtyPosition: If non-zero, you're telling the conduit the item has moved and the handheld one needs to move. Promotion, drag, push, etc, all effect this.

  • deleted: If non-zero, delete handheld copy during sync. We must keep deleted items around so the user can undelete them, but more importantly we need to know they're deleted so as to delete the handheld items, or collide and keep. For instance, if we purely remove the item, and then find an item on the handheld, is it new or was the desktop deleted?

  • checked: yes or no
  • expanded: yes or no
  • expandedMemo: yes or no
  • expandedLinks: yes or no
  • priority: 0 is -; 1-5 is.. as you expect.
  • progress: 0,10,20,...90,100 (yes, we currently round to even values for space efficiency on the handheld)
  • autoNumber: numeral_t as defined in list_db.h
  • alarmID: 32bit number; unique-id into ShadTimer database
  • localID: string; you can put what you like in there, though keep it short; Shadow will maintain it. This way you can relate external data to Shadow items by plopping in your own unique-id here
  • dispColour: palm Indexed Colour. 0==white, 255==black.
  • dispBold: yes or no
  • dispOverride: -1 for none; 0 and up for item type. (Checklist, note, tasklist, custom, flat)
  • title: Item title text.
  • note: Item note text
  • hhCreateTime: Palm-epoch date
  • hhTargetTime: Palm-epoch date
  • hhStartTime: Palm-epoch date
  • hhFinishTime: Palm-epoch date
Send email to Jeff Mitchell at support@codejedi.com