XML-RPC Protocol Method: syncitems

From Dreamwidth Notes
Revision as of 18:16, 19 September 2010 by Murklins (Talk | contribs)

Jump to: navigation, search
Needs Update: This documentation was ported over from LJ's Server Manual with minimal modification. It may not match Dreamwidth's implementation of the method, and needs to be double checked against the DW code and updated as necessary.

Returns a list (or part of a list) of all the items (journal entries, to-do items, comments) that have been created or updated on Dreamwidth since you last downloaded them. Note that the items themselves are not returned --- only the item type and the item number. After you get this you have to go fetch the items using another protocol mode. For journal entries (type "L"), use the getevents mode with a selecttype of "syncitems".

Inputs

username Scalar. Required. Username of user logging in.

auth_method Scalar. Optional. Authentication method used for this request. The default value is "clear", for plain-text authentication. "cookie" and any of the challenge-response methods are also acceptable.

password Deprecated. Scalar. Optional. Password of user logging in in plaintext. If using the "clear" authentication method, either this or "hpassword" must be present.

hpassword Deprecated. Scalar. Optional. MD5 digest of user's password. Not much more secure than password, but at least it's not in plain text.

auth_challenge Scalar. Optional. If using challenge-response authentication, this should be the challenge that was issued to you by the server.

auth_response Scalar. Optional. If using challenge-response authentication, this should be the response hash that you generate, based on the formula required for your challenge.

ver Scalar. Optional. Protocol version supported by the client; assumed to be 0 if not specified. See Protocol Versions for details on the protocol version.

lastsync Scalar. Optional. The date you last downloaded synced, in "yyyy-mm-dd hh:mm:ss" format. Note: do not make this date up from the client's local computer... send the date from this mode's response of the newest item you have saved on disk.

Example Request

POST /interface/xmlrpc HTTP/1.0
User-Agent: XMLRPC Client 1.0
Host: www.dreamwidth.org
Content-Type: text/xml
Content-Length: 495
 
<?xml version="1.0"?>
<methodCall>
  <methodName>LJ.XMLRPC.syncitems</methodName>
  <params>
    <param>
      <value><struct>
        <member>
          <name>username</name>
          <value><string>test</string></value>
        </member>
        <member>
          <name>password</name>
          <value><string>test</string></value>
        </member>
        <member>
          <name>ver</name>
          <value><int>1</int></value>
        </member>
        <member>
          <name>lastsync</name>
          <value><string>2002-07-13 00:00:00</string></value>
        </member>
      </struct></value>
    </param>
  </params>
</methodCall>

Outputs

syncitems Array of structs. Required. Each array item is a struct containing these keys:

  • item Scalar. Required. The nth item, in the form "Type-Number". Type can be one of "L" for log entries (journal entries), "C" for comments (not implemented), or many other things presumably. If your client doesn't know how to fetch an item of a certain type, just ignore them. A new version of your client could later see that it has never downloaded anything of type "C" and go back and fetch everything of that type from the beginning.
  • action Scalar. Required. Either "create" or "update". This field isn't too useful, but you may want to make your client verbose and tell the user what it's doing. For example, "Downloading entry 5 of 17: Updated".
  • time Scalar. Required. The server time (in the form "yyyy-mm-dd hh:mm:ss") that this creation or update took place. Remember in your local store the most recent for each item type ("L", "C", etc...). This is what you send in subsequent requests in lastsync.

count Scalar. Required. The number of items that are contained in this response (numbered started at 1). If sync_count is equal to sync_total, then you can stop your sync after you complete fetching every item in this response.

total Scalar. Required. The total number of items that have been updated since the time specified.

Example Response

Needs Update: This example lists "del" actions, but the spec above only lists "create" and "update" as possible values -- something needs fixing to make the example and the spec match.
HTTP/1.1 200 OK
Connection: close
Content-length: 3360
Content-Type: text/xml
Date: Tue, 16 Jul 2002 22:39:30 GMT
Server: Apache/1.3.4 (Unix)
 
<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value><struct>
        <member>
          <name>total</name>
          <value><int>11</int></value>
        </member>
        <member>
          <name>count</name>
          <value><int>11</int></value>
        </member>
        <member>
          <name>syncitems</name>
          <value><array><data>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1947</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-13 00:06:26</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>del</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1954</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-13 00:09:05</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>del</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1958</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-13 02:01:07</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1948</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-13 08:27:56</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>update</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1960</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 02:52:18</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1961</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 03:07:55</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1962</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 03:08:14</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1963</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 03:13:26</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1964</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 03:17:03</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>create</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1959</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-14 14:25:07</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>update</string></value>
              </member>
            </struct></value>
            <value><struct>
              <member>
                <name>item</name>
                <value><string>L-1965</string></value>
              </member>
              <member>
                <name>time</name>
                <value><string>2002-07-16 04:36:15</string></value>
              </member>
              <member>
                <name>action</name>
                <value><string>update</string></value>
              </member>
            </struct></value>
          </data></array></value>
        </member>
      </struct></value>
    </param>
  </params>
</methodResponse>