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):
The minimum useful file is thus this:
<item>My item title</item>
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"
<title>My line title</title>
<note>My item note</note>
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