| The messages exchanged during synchronization consist of a set of Elements. The format of these Elements is probably one of the more involved aspects of SyncML. Careful reading of the Representation Protocol specification will show that each Command Element has a clearly defined format and explicit list of allowed responses. A more detailed look into the Representation Protocol reveals that it consists of several different types of Elements: The Message Container Elements The Protocol Management Elements The Command Elements The Common Use Elements The Data Description Elements
Proper combination of each of these Elements will create a well-formed SyncML Message. Note that not all Elements listed in the Representation Protocol are required to create a valid SyncML Message. The Message Container Elements The Message Container Elements are needed to encapsulate a SyncML Message. These three Elements are used to separate the header or session/message data from the command or synchronization data. The Message Container Elements are: The container for a SyncML Message i.e., it is the root element of the SyncML DTD. This only holds SyncHdr and SyncBody, so consider this similar to an envelope with the SyncHdr as the address and the SyncBody as the letter inside the envelope. Here is an example message without any real contents (only SyncHdr and SyncBody): <SyncML xmlns='SYNCML:SYNCML1.0'> <SyncHdr> <!-- header information goes here --> </SyncHdr> <SyncBody> <!-- body information goes here --> </SyncBody> </SyncML> The SyncHdr contains the information about the message, similar to the address on an envelope. The SyncHdr holds information such as where the message is intended to go (Target), where the message is from (Source), the credentials of the sender, and which version of the Representation and Synchronization Protocols the message is using. Additionally, the SyncHdr can contain Meta information about the capabilities of the device, such as the maximum message size. If no response is desired to this message, a NoResp flag can be set in the SyncHdr as well. Here is an example SyncHdr, coming from a Client: <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>SyncML/1.0</VerProto> <SessionID>1</SessionID> <MsgID>1</MsgID> <Target> <LocURI>http://www.sync.org/servlet/syncit</LocURI> </Target> <Source> <LocURI>IMEI:001004FF1234567</LocURI> </Source> </SyncHdr> Note that this SyncHdr contains a Source that refers to IMEI. See the section in this chapter on Source and Target for more information on URIs. This is the body of the SyncML Message. The SyncBody contains a subset of the Command and Protocol Management Elements. The SyncBody is where the synchronization data and command information is stored; it is the content of the envelope. This is how the first SyncBody from a Client might look during an actual synchronization: <SyncBody> <Alert> <CmdID>1</CmdID> <Data>200</Data> <!-- 200 = TWO_WAY_ALERT --> <Item> <Target><LocURI>./contacts/james_bond</LocURI></Target> <Source><LocURI>./dev-contacts</LocURI></Source> <Meta> <Anchor xmlns='syncml:metinf'> <Last>234</Last> <Next>276</Next> </Anchor> </Meta> </Item> </Alert> </SyncBody> This SyncBody contains an Alert, asking the Server to start a normal Two-way sync and indicating which datastores to synchronize. Note the use of change counters for the Sync Anchors. The Protocol Management Elements Status is the only Protocol Management Element: Status is used to indicate the result of a command. This is not the same as Results, which returns Search information or Get information. There is one Status per command (for ALL commands), and they must be in the same order as the commands in the SyncML request. If needed, a Status can be sent against the SyncHdr by using a CmdRef of '0'. Status commands should be the first set of Elements in the SyncBody. <Status> <CmdID>8</CmdID> <MsgRef>2<MsgRef> <CmdRef>9<CmdRef> <Cmd>Add</Cmd> <TargetRef>./bruce1</TargetRef> <SourceRef>IMEI:001004FF1234567</SourceRef> <Data>401</Data> </Status> This example of Status is for an Add command that failed due to lack of appropriate credentials. Note it is not possible to determine the datastore for the referred command without looking at the Status for the Sync command. The Command Elements In order to have any action happen in a session, a request must be sent. Typically, the Command Elements are those requests. These requests are a set of operations on one or more datastores. The Command Elements are used to cause an action in the recipient of the SyncML message. A Command Element almost always contains data, either qualifying the command or conveying payload. The payload is something like a contact or event or email information. The Command Elements can be logically divided into three groups: The Data Command Elements The Data Command Elements are used to change application data. An example of application data might be contact information or a set of notes. The Data Command Elements are: This command adds one or more payload items to a Datastore. If a Server sends an Add command, the implication is that the Client will send a Map command in return. However, if the Client uses the same UID as the Server, no Map will be required. <Add> <CmdID>1<CmdID> <Item> <Source><LocURI>15</LocURI></Source> <Meta> <Type xmlns='syncml:metinf'>text/x-vcard</Type> </Meta> <Data>BEGIN:VCARD VERSION:3.0 FN:Smith;Bruce N:Bruce Smith TEL;TYPE=WORK;VOICE:+1-919-555-1234 END:VCARD </Data> </Item> </Add> This command adds a single business card in the vCard format. The Meta is used to indicate the media format of the payload. The Source indicates the UID of the item on the Server. This command creates a copy of an existing item, either in the same datastore or in another datastore. Copy can only create new items of the same type it cannot make an event out of a contact, for example. <Copy> <CmdID>12345</CmdID> <Item> <Target> <LocURI>mid:msg1@host.com</LocURI> </Target> <Source> <LocURI>./mail/bruce1/folders/Project%20XYZ</LocURI> </Source> </Item> <Item> <Target> <LocURI>mid:msg2@host.com</LocURI> </Target> <Source> <LocURI>./mail/bruce1/folders/Admin</LocURI> </Source> </Item> </Copy> This Copy command makes copies of two different email messages. This is done by specifying only the IDs of the email to copy (the Source) and the location to copy them to (the Target). This command removes an item from a datastore. It is also possible to use the soft delete option with this command, but that is rarely implemented. If soft delete is used on a recipient that does not support soft delete, then the delete can still be successful, but the delete will be a hard delete. More can be found on soft deletes in the SftDel section. <Delete> <CmdID>13<CmdID> <Archive/> <Item> <Source><LocURI>15</LocURI></Source> </Item> </Delete> This command deletes a single item, but it also asks the recipient to archive the item prior to deletion. The Archive flag is an optional Element that is used to store items in something similar to a trash bin. This command will retrieve an item, typically the Device Information. SyncML Data Synchronization only requires Get to return the Device Information; SyncML Device Management (see Chapter 9) will require support for more objects. It is possible to use Get to retrieve an object, but this usage is extremely rare and may not be supported. <Get> <CmdID>3</CmdID> <Meta><Type xmlns='syncml:metinf'> application/vnd.syncml-devinf+xml</Type></Meta> <Item> <Target><LocURI>./devinf10</LocURI></Target> </Item> </Get> This example shows how to request the Device Information of the recipient. Note the use of the Meta to specify the type. Map is used by Clients to tell a Server about a datastore that has had new items created by an Add command. The Map element contains one or more MapItems, as well as the Source and Target information. <Map> <CmdID>13<CmdID> <Target> <LocURI>http://www.datasync.org/servlet/syncit</LocURI> </Target> <Source> <LocURI>IMEI:001004FF1234567</LocURI> </Source> <MapItem> <Target><LocURI>./0123456789ABCDEF</LocURI></Target> <Source><LocURI>15</LocURI></Source> </MapItem> </Map> This Map contains a single MapItem, but could contain more. However, each Map must deal with a single local and remote datastore. The MapItem only holds two pieces of information: the Client UID in the Source, and the Server UID in the Target. The Client had received the Server UID earlier in an Add command. The Client is now telling the Server the mapping between the Server and Client UIDs. See Map for an example. The MapItem can also indicate a new UID for an existing item (e.g. a Client had to reissue UIDs to items). In that case, the new UID will be in the Source, and the old UID will be in the Target. This will send an item, typically the Device Information. Note in SyncML Data Synchronization, the Put command is only required to put the Device Information. <Put> <CmdID>2</CmdID> <Meta><Type xmlns='syncml:metinf'> application/vnd.syncml-devinf+xml</Type></Meta> <Item> <Source><LocURI>./devinf10</LocURI></Source> <Data> <DevInf xmlns='syncml:devinf'> <Man>Big Factory, Ltd.</Man> <Mod>4119</Mod> <OEM>Jane's phones</OEM> <DevId>1218182THD000001-2</DevId> <DevTyp>phone</DevTyp> </DevInf> </Data> </Item> </Put> This example of the Put shows the Device Information (see Chapter 7) being sent to the recipient. Note this is a very truncated version of the Device Information. The Replace command is used to update an existing item with new information. The Replace command contains one or more payload items, each with their own UID. Here is an example Replace command: <Replace> <CmdID>4</CmdID> <Meta> <Type xmlns='syncml:metinf'>text/x-vcard</Type> </Meta> <Item> <Source><LocURI>1012</LocURI></Source> <Data>BEGIN:VCARD VERSION:3.0 FN:Mueller;Bruce N:Bruce Mueller TEL;TYPE=WORK;VOICE:+49 (7031) 16-5509 END:VCARD </Data> </Item> </Replace> The Datastore Command Elements The Datastore Command Elements are used to define actions pertaining to an entire Datastore. The Datastore Command Elements are: Alert is used to signal special "nonstandard" commands, such as notifications, synchronization requests, and text displays. The most typical use for Alert is to ask for a specific type of synchronization, such as a normal Two-way sync or a Slow sync. <Alert> <CmdID>509</CmdID> <Data>200</Data> <Item> <Target><LocURI>./contacts/james_bond</LocURI></Target> <Source><LocURI>./dev-contacts</LocURI></Source> <Meta> <Anchor xmlns='syncml:metinf'> <Last>234</Last> <Next>243</Next> </Anchor> </Meta> </Item> </Alert> This Alert is requesting a normal Two-way synchronization. It is also specifying the sync anchors, as a means of allowing the recipient to verify that a normal sync is acceptable. If the recipient does not agree with the sync anchors, the recipient will ask for a Slow sync instead. Results returns the output from a Search command or a Get command. Results stores the output in (one or more) Item. SourceRef and TargetRef are the Source and Target from the command with which Results is associated. <Results> <CmdID>42<CmdID> <Meta><Type xmlns='syncml:metinf'> application/vnd.syncml-devinf+xml</Type></Meta> <Item> <Source><LocURI>devinf10</LocURI></Source> <Data> <!-- devinfo data would go here --> </Data> </Item> </Results> Results is typically used to return the Device Information. The example above shows how Results would return the Device Information, but the actual data is excluded from the example to keep it short. Search asks for a search on a Datastore. If the Search command contains the NoResults flag, then the output from the search must be placed in temporary storage, as specified in the Target. It is necessary to be aware that Search can have more than one Source, meaning the Search command must search more than one datastore at once. This can be a powerful command, one that can easily overwhelm a product not prepared for a large Results message. Note the search grammar must be specified in the Meta, and a nonsupported search grammar will be rejected. At this time, there is no well-defined search grammar in use. <Search> <CmdID>1234</CmdID> <Cred> <Meta> <Type xmlns='syncml:metinf'>syncml:auth-md5</Type> <Format xmlns='syncml:metinf'>b64</Format> </Meta> <Data>OGNkNDI1ZTZjNjgwMTNiYWZkOWEyN2JjMjNlZDM4YzENCg==</Data> </Cred> <Source> <LocURI>http://www.sync.org/servlet/syncit/bruce1</LocURI> </Source> <Meta><Type xmlns='syncml:metinf'>application/sql</Type></Meta> <Data>SELECT * WHERE "FN" EQ "Bruce Smith"</Data> </Search> This search is slightly different from normal, as it uses SQL to locate a contact that contains the name Bruce Smith. A more typical search would use a CGI script similar to the Target Address Filtering. It also contains credentials in MD5 format, as the datastore being queried requires authentication. Sync is the command used to perform the synchronization between two datastores. It holds one or more Data Commands (e.g. Add, Delete, and Replace), specifies the local (Source) and remote (Target) datastores, specifies any credentials necessary for synchronization with the remote datastore, and can indicate the media format for the data commands. Sync must be used whenever two datastores need to be synchronized. If you just wish to store an object within another datastore, and do not wish to synchronize the entire datastore, then just use the Put command. <Sync> <CmdID>3</CmdID> <Target><LocURI>./contacts/james_bond</LocURI></Target> <Source><LocURI>./dev-contacts</LocURI></Source> <Meta> <Mem xmlns='syncml:metinf'> <FreeMem>8100</FreeMem> <!--Free memory (bytes) in Calendar database --> <FreeId>41</FreeId> <!--Number of free records in Calendar database--> </Mem> </Meta> <Replace> <CmdID>4</CmdID> <Meta> <Type xmlns='syncml:metinf'>text/x-vcard</Type> </Meta> <Item> <Source><LocURI>1012</LocURI></Source> <Data><!--The vCard data would be placed here.--></Data> </Item> </Replace> </Sync> This Sync example includes Mem information about the available memory and/or IDs. This particular example has 8100 bytes free, and 41 free IDs. The Replace that is in the Sync only has one Item, which is a vCard. The Mem hint is usually in the Sync command to help the recipient determine whether or not their new data (to be sent back) will fit into the datastore. The Process Flow Command Elements The Process Flow Command Elements are used to control the processing of the various Data Command and Datastore Command Elements. In SyncML Data Synchronization, these Command Elements are currently optional and, as a result, are not implemented very often. However, in SyncML Device Management, they are mandatory. The Process Flow Command Elements are: Atomic requires that all subcommands be executed, or none will be executed. This requires a rollback capability, similar to Database Transaction Processing. This is optional for SyncML Data Synchronization (but not for SyncML Device Management) and tends to be difficult to implement properly. As a result, it is not implemented very often. This command may be useful for applications synchronizing Relational Databases that require transactional guarantees, such as a sales application. <Atomic> <CmdID>321</CmdID> <Add> <CmdID>322</CmdID> <Item> <Target><LocURI>./devinf10/pen</LocURI></Target> <Data>Yes</Data> </Item> </Add> <Replace> <CmdID>323</CmdID> <Item> <Target><LocURI>./devinf10/version</LocURI></Target> <Data>20020401T133000Z</Data> </Item> </Replace> </Atomic> This Atomic sequence is a Device Management sequence. The "pen" setting is being set to "Yes", and the version is being set to a date in 2002. Note that if Add had failed, then the Replace would not execute, and the Atomic would fail. Also note that if the Replace failed, then the Add would be unexecuted (or rolled back in Database terms), and the Atomic would fail. Sequence requires all subcommand Elements to be executed in the sequence they appear. Again, this is optional in SyncML Data Synchronization, but required in SyncML Device Management. <Sequence> <CmdID>1234</CmdID> <Add> <CmdID>1235</CmdID> ... </Add> <Add> <CmdID>1236</CmdID> ... </Add> <Delete> <CmdID>1237</CmdID> ... </Delete> </Sequence> If the recipient of this Sequence was unable to guarantee that each command was executed in order, then all of those commands would fail, and the Sequence command would fail. Otherwise, the recipient will execute the commands in order, and return the appropriate Status from each command. Note that Atomic does not imply that each command must be done in sequence, nor does Sequence imply that all of the subcommands must succeed. These are complimentary commands. The Common Use Elements The Common Use Elements are so named because they can appear as subelements in most of the Command and SyncHdr Elements. They are used to provide a set of common functions and to help reduce the amount of special parsing code. Imagine the size of a SyncML product if it had to accommodate all these common elements if they were not specifically called out as common code elements the amount of redundant code would be staggering. The Common Use Elements are: Chal (short for Challenge) is used for authentication purposes. Chal allows products to ask for credentials in a specific format. For example, if a Client produces credentials in the Basic format and the Server prefers credentials in the MD5 format, the Server can request that the Client send the credentials in the MD5 format via the Chal Element. <Status> <MsgRef>1</MsgRef> <CmdRef>0</CmdRef> <Cmd>SyncHdr</Cmd> <TargetRef>http://www.datasync.org/servlet/syncit</TargetRef> <SourceRef>IMEI:001004FF1234567</SourceRef> <Chal> <Meta> <Type xmlns='syncml:metinf'>syncml:auth-basic</Type> <Format xmlns='syncml:metinf'>b64</Format> </Meta> </Chal> <Data>401</Data> </Status> This Status command contains a Chal asking for the credentials in Basic format. Cmd contains the ASCII name of the command (useful for debugging). <Status> <MsgRef>1</MsgRef> <CmdRef>14</CmdRef> <Cmd>Add</Cmd> <TargetRef>./mail/bruce1</TargetRef> <Data>401</Data> </Status> This Status shows that the command was an Add command. CmdID contains the ID of the command within the SyncML message. CmdID is reference in Status. A good method is to use an unsigned integer (16 bits are sufficient) for this value, starting with '1' and then incrementing the counter after each use. Note that a CmdID ('0') is reserved to indicate the SyncHdr. <Delete> <CmdID>3456</CmdID> <Item> <Target><LocURI>./11</LocURI></Target> </Item> </Delete> This Delete command has a CmdID of 3456, a value that will rarely be seen, assuming a start value of '1' and incrementing by one. CmdRef is the ID of the command being referred to in Status. <Status> <CmdID>1</CmdID> <MsgRef>2</MsgRef> <CmdRef>0</CmdRef> <Cmd>SyncHdr</Cmd> <TargetRef>http://www.syncml.org/sync-Server</TargetRef> <SourceRef>IMEI:493005100592800</SourceRef> <Data>101</Data> <!--Statuscode for Busy--> </Status> Note in this example, the CmdRef is '0'; this explicitly refers to the SyncHdr. This Status is telling the caller that the device is busy. Cred contains a set of credentials in a particular format. SyncML only requires support for either Basic or MD5. Additional authentication standards can be used, such as X.509. <Cred> <Meta> <Type xmlns='syncml:metinf'>syncml:auth-basic</Type> </Meta> <Data>QnJ1Y2UyOk9oQmVoYXZl</Data> <!-- base64 formatting of "userid:password" --> </Cred> Final is a flag indicating the end of a package. It is helpful to think of Final as a baton that is passed between the Client and the Server. Since the Client starts the session, the Client holds the Final "baton" and passes it to the Server when done with its package. Likewise, the Server will pass the Final "baton" back when done with its package. This baton passing will continue until the session is done. <SyncML xmlns='SYNCML:SYNCML1.0'> <SyncHdr>...</SyncHdr> <SyncBody> ... <Final/> </SyncBody> </SyncML> This is an abbreviated message, showing only the location of the Final flag. Final must be the last command in the SyncBody. Lang allows the product to request a particular language for a payload. <Get> <CmdID>12</CmdID> <Lang>en-US</Lang> <Item> <Target><LocURI>./telecom/pb</LocURI></Target> <Source> <LocURI>http://www.sync.com/servlet/</LocURI> </Source> <Meta> <Type xmlns='syncml:metinf'>text/x-vCard</Type> </Meta> </Item> </Get> This Get command asks for a vCard to be delivered with US English language. LocName is the human readable display name for a target or address. Note when MD5 is used, LocName contains the username as an aid in verifying the MD5 digest (since the MD5 digest is a one-way hashing algorithm). <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>SyncML/1.0</VerProto> <SessionID>1</SessionID> <MsgID>1</MsgID> <Target> <LocURI>http://www.syncml.org/sync-Server</LocURI> </Target> <Source> <LocURI>IMEI:493005100592800</LocURI> <LocName>Bruce2</LocName> <!-- userId --> </Source> <Cred> <Meta><Type xmlns='syncml:metinf'> syncml:auth-md5</Type> </Meta> <Data>NTI2OTJhMDAwNjYxODkwYmQ3NWUxN2RhN2ZmYmJlMzk=</Data> <!-- Base64 coded MD5 digest of "Bruce2:OhBehave:Nonce" --> </Cred> </SyncHdr> This SyncHdr contains credentials in MD5 form, and to aid in the verification of these credentials, the Source contains LocName with the username. LocURI contains a specific target or address. LocURI is used in several commands and can point to either the Target or Source. In any case, it is important to make sure whether the address should be referred to as an absolute or a relative URI. Absolute URIs are easy to spot, as they typically start with something like "http://" or "ftp://". Relative URIs are more like "./contact/james_bond" or "event/bruce". Note in relative URIs, "./bruce" and "bruce" are the same thing. Usage of relative URIs is encouraged whenever possible, as this will reduce the number of bytes transferred an important aspect to remember when dealing with wireless devices (which can cost on a per-byte basis). <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>1.0</VerProto> <SessionID>1</SessionID> <MsgID>1</MsgID> <Target><LocURI>http://www.syncml.host.com/</LocURI></Target> <Source><LocURI>IMEI:001004FF1234567</LocURI></Source> </SyncHdr> This shows LocURI being used in both the Target and the Source. Added in version 1.1, MoreData is used to signal to the recipient that the data being sent in the parent command is incomplete the rest of the data will come in later message(s). MoreData cannot be used if the data can fit into a message. <Add> <CmdID>15</CmdID> <Meta> <Type>text/x-vcard</Type> <Size>3000</Size> </Meta> <Item> <Source><LocURI>2</LocURI></Source> <Data>BEGIN:VCARD VERSION:2.1 FN:Bruce Smith N:Smith;Bruce TEL;WORK;VOICE:+1-919-555-1234 TEL;WORK;FAX:+1-919-555-9876 NOTE: here starts a huge note field, or icon etc... </Data> <MoreData/> </Item> </Add> The Add command contains a single Item. The Item has a single large piece of payload data. The Item element also has the MoreData element, indicating the data is not complete. The recipient would accept this Add by sending back a Status with "Chunked item accepted and buffered". MsgID is the ID of the current message useful for later reference to a command. MsgID only exists in the SyncHdr. <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>SyncML/1.0</VerProto> <SessionID>1</SessionID> <MsgID>1</MsgID> <Target><LocURI>IMEI:493005100592800</LocURI></Target> <Source> <LocURI>http://www.syncml.org/sync-Server</LocURI> </Source> </SyncHdr> The MsgID for this SyncHdr is '1', meaning it is the first message from this device in this session. MsgRef is the ID of a message containing a command that is being referred to (typically in Status, but it can also appear in Results). This is useful if you are trying to respond to a backlog of commands. It is also useful for a sanity check in the recipient. <Status> <CmdID>1</CmdID> <MsgRef>1</MsgRef> <CmdRef>0</CmdRef> <Cmd>SyncHdr</Cmd> <TargetRef>http://www.syncml.org/sync-Server</TargetRef> <SourceRef>IMEI:493005100592800</SourceRef> <Chal> <Meta> <Type xmlns='syncml:metinf'>syncml:auth-basic</Type> <Format xmlns='syncml:metinf'>b64</Format> </Meta> </Chal> <Data>407</Data> <!--Credentials missing--> </Status> The Status command is referring to the SyncHdr and is indicating that the necessary credentials were missing. The MsgRef in this Status is '1', indicating that it is the first message of the session. NoResp is a flag indicating that no response is wanted or expected for a command. This flag may also be set in the SyncHdr if no response is wanted at all in return. <SyncHdr> <VerDTD>1.0</Version> <VerProto>SyncML/1.0</VerProto> <SessionID>1</SessionID> <MsgID>2</MsgID> <Target><LocURI>IMEI:001004FF1234567</LocURI></Target> <Source> <LocURI>http://www.sync.org/servlet/syncit</LocURI> </Source> <NoResp/> </SyncHdr> This Message is being built with the expectation that no response is needed or wanted. The SyncHdr contains the NoResp flag, and for no responses to come back, any other commands, such as Replace or Sync, will also need the NoResp flag. NoResults is a flag indicating that the results from a Get or Search must be held in temporary storage as a source in a later command. It is possible that the recipient of this command may return an error if it cannot create temporary storage. An implementation should be careful about using this flag, as some recipients cannot support it. <Search> <CmdID>3</CmdID> <NoResults/> <Source><LocURI>./bruce1/emp_tabl.db</LocURI></Source> <Target><LocURI>./bruces</LocURI></Target> <Meta><Type xmlns='syncml:metinf'>application/sql</Type></Meta> <Data>SELECT * WHERE "FN" EQ "Bruce Smith"</Data> </Search> The Search command contains the flag NoResults, indicating that the results of the search must be stored in the temporary location "./bruces". Added in version 1.1, NumberOfChanges can only be used in the Sync command. NumberOfChanges is used to inform the recipient how many items will be sent from a particular datastore. The recipient may use this data to show the synchronization progress. <Sync> <CmdID>5</CmdID> <Target><LocURI>contacts</LocURI></Target> <Source><LocURI>Contact/Unfiled</LocURI></Source> <NumberOfChanges>23</NumberOfChanges> ... </Sync> This example Sync indicates that 23 changes will be coming from this particular datastore. RespURI is a URI that must be used for the response to the current message. This command allows for direction of synchronization messages to different Servers in a Server farm. This command can also be used to pass session data to a Client, and the Client must pass this information back in the form of the Target URI. <SyncHdr> ... <RespURI>http://www2.datasync.org/servlet/syncit/bruce1?sessioninfo =01456ac2354ace</RespURI> </SyncHdr> RespURI can also be used to have the Client pass back session information. In this example, the Client is being told to respond to www2.datasync.org and, in addition, pass along some session information strings. This is a useful property when dealing with Server farms, or when one wants to have session information up front. RespURI is also helpful in that the Client sets the SessionID, and the Server cannot change that, so it has to use the RespURI instead. SessionID is the ID of the current session. This is useful for determining if the message is from the current session, or if the session has restarted. The SessionID can remain the same value indefinitely, but this kind of usage greatly increases the difficulty in debugging your product and is highly discouraged. <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>SyncML/1.0</VerProto> <SessionID>42</SessionID> <MsgID>1</MsgID> ... </SyncHdr> This would be the SyncHdr from the first message in a session. The SessionID is 42 in this case. SftDel is a flag indicating that a delete is a soft delete. Typically, this command will come from the Server as a means of clearing extra space on the Client. The Client must maintain the LUID of the soft-deleted item, in case a Server wants to update that object at a later date. A Client may also send this flag, indicating to the Server that it does not want this object again, but not to delete it. <Delete> <CmdID>4</CmdID> <SftDel/> <Item> <Target><LocURI>./11</LocURI></Target> </Item> </Delete> This Delete command specifies that a soft delete needs to be done on the item with ID of '11'. Source specifies the source routing or mapping information. Source exists in many commands and indicates many different things, but it always indicates local data or routing. For example, in the Map command, it indicates the local routing information for the datastore that generated mapping. <Map> <CmdID>5</CmdID> <Target><LocURI>./contacts/sspielberg</LocURI></Target> <Source><LocURI>./tables</LocURI></Source> <MapItem> <Target><LocURI>./0123456789ABCDEF</LocURI></Target> <Source><LocURI>./12</LocURI></Source> </MapItem> </Map> This Map has Source used in two places: the Map and the MapItem. Source in Map refers to the datastore, and Source in the MapItem refers to the item in the datastore. When present, SourceRef contains the value that was in the Source in the referenced command. When used in a Status command, it specifies the source address (LocURI) of the object. When used in the Results command, it contains the associated datastore URIs. <Status> <CmdID>2</CmdID> <MsgRef>1</MsgRef> <CmdRef>5</CmdRef> <Cmd>Replace</Cmd> <SourceRef>1212</SourceRef> <Data>208</Data> <!-- Conflict, originator wins --> </Status> The Status command shown here uses the SourceRef to contain the value that was in the Source in the Replace command. Target specifies the target routing or mapping information. Target is similar to Source, but instead refers to the destination. For example, Target in SyncHdr refers to the routing information for the network device that is receiving the message. <Sync> <CmdID>3</CmdID> <Target><LocURI>./calendar/james_bond</LocURI></Target> <Source><LocURI>./dev-calendar</LocURI></Source> ... </Sync> Target in Sync refers to the datastore, and in this case, the Sync wants to operate on a secret agent's calendar. When present, TargetRef contains the value that was in the Target in the referenced command. When used in a Status command, it specifies the target address (LocURI) of the object. When used in the Results command, it contains the temporary datastore specified in the Search command. <Status> <CmdID>1</CmdID> <MsgRef>1</MsgRef> <CmdRef>0</CmdRef> <Cmd>SyncHdr</Cmd> <TargetRef>http://www.syncml.org/sync-Server</TargetRef> <SourceRef>IMEI:493005100592800</SourceRef> <Data>212</Data> <!--Authenticated for session--> </Status> This is a Status for a SyncHdr that indicates the credentials were accepted and need not be sent for the rest of the session. In this Status, the TargetRef contains the value of the Target in the previous message. VerDTD specifies the major and minor version of the SyncML Representation Protocol. This is not the same as the Synchronization Protocol, though. This is an important field to pay attention to, as different major versions are not required to be compatible. Devices supporting 1.1 should note that if they receive a message with a VerDTD of 1.0, then they should send a VerDTD of 1.0 (and use the 1.0 DTD), as that sender can only handle the version it specified. The VerDTD can be seen in this SyncHdr. <SyncHdr> <VerDTD>1.0</VerDTD> <VerProto>SyncML/1.0</VerProto> ... </SyncHdr> VerProto specifies the protocol used, as well as the major and minor version of the Synchronization Protocol. Again, it is important to pay attention to this, since the protocol could be SyncML or SyncML DM. See VerDTD for an example. The Data Description Elements The Data Description Elements are: Data contains discrete SyncML data or payload; this is where the actual data is stored. Examples are credentials, contact information, and status code. <Status> <CmdID>1</CmdID> <MsgRef>1</MsgRef><CmdRef>0</CmdRef><Cmd>SyncHdr</Cmd> <TargetRef>http://www.syncml.org/sync-Server</TargetRef> <SourceRef>IMEI:493005100592800</SourceRef> <Data>212</Data> <!--Statuscode for OK, authenticated for session--> </Status> This Status command contains Data indicating that the credentials are valid for the entire session. This works well unless there are large communication delays. Item is a container for data; it holds information about the local data (Source), information about the remote data (Target), the data itself, and any Meta information on the data. Item is used to separate the data and its identification from the command information. This example Delete command contains two Items: <Delete> <CmdID>6</CmdID> <Item> <Target><LocURI>./11</LocURI></Target> </Item> <Item> <Target><LocURI>./12</LocURI></Target> </Item> </Delete> This example Add command contains a vCard. <Add> <CmdID>1234</CmdID> <Item> <Source><LocURI>12</LocURI></Source> <Meta> <Type xmlns='syncml:metinf'>text/x-vCard</Type> </Meta> <Data>BEGIN:VCARD VERSION:2.1 FN:Smith;Bruce N:Bruce Smith TEL;TYPE=WORK;VOICE:+1-919-555-1234 END:VCARD </Data> </Item> </Add> Meta is used to specify meta-information about the parent Element. For example, Meta can be used to specify the format of the data or to indicate the size of an object. <Cred> <Meta> <Type xmlns='syncml:metinf'>syncml:auth-md5</Type> <Format xmlns='syncml:metinf'>b64</Format> </Meta> <Data>OGNkNDI1ZTZjNjgwMTNiYWZkOWEyN2JjMjNlZDM4YzENCg==</Data> </Cred> This Cred contains a Meta; the Meta contains a Type and a Format command. These Meta commands are used in processing the credentials. | 
