»

checkfriends

checkfriends — Checks to see if your friends list has been updated since a specified time.

Mode Description

Mode that clients can use to poll the server to see if their friends list has been updated. This request is extremely quick, and is the preferred way for users to see when their friends list is updated, rather than pounding on reload in their browser, which is stressful on the serves.

Arguments

  1. [struct](required)

    Containing keys:

    • username(required):

      • [scalar](required) Username of user logging in.

    • auth_method(optional):

      • [scalar](required) 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(optional):

      • [scalar](required) DEPRECATED. Password of user logging in in plaintext. If using the "clear" authentication method, either this or "hpassword" must be present.

    • hpassword(optional):

      • [scalar](required) DEPRECATED. MD5 digest of user's password. Not much more secure than password, but at least it's not in plain text.

    • auth_challenge(optional):

      • [scalar](required) If using challenge / response authentication, this should be the challenge that was issued to you by the server.

    • auth_response(optional):

      • [scalar](required) If using challenge / response authentication, this should be the response hash that you generate, based on the formula required for your challenge.

    • ver(optional):

      • [scalar](required) Protocol version supported by the client; assumed to be 0 if not specified. See Chapter 11: Protocol Versions for details on the protocol version

    • lastupdate(required):

      • [scalar](required) The time that this mode request returned last time you called it. If this is the first time you've ever called it (since your client has been running), leave this blank. It's strongly recommended that you do not remember this value across invocations of your client, as it's very likely your friends will update since the client was running so the notification is pointless... the user probably read his/her friends page already before starting the client.

    • mask(optional):

      • [scalar](required) The friend group(s) in which the client is checking for new entries, represented as a 32-bit unsigned int. Turn on any combination of bits 1-30 to check for entries by friends in the respective friend groups. Turn on bit 0, or leave the mask off entirely, to check for entries by any friends.

Example 3. Sample call to LJ.XMLRPC.checkfriends

POST /interface/xmlrpc HTTP/1.0
User-Agent: XMLRPC Client 1.0
Host: www.livejournal.com
Content-Type: text/xml
Content-Length: 481

<?xml version="1.0"?>
<methodCall>
<methodName>LJ.XMLRPC.checkfriends</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>lastupdate</name>
<value><string></string></value>
</member>
</struct></value>

</param>
</params>
</methodCall>

Return Values

  1. [struct](required)

    Containing keys:

    • new(required):

      • [scalar](required) This is what you should use to determine if there are new entries. Its value is "1" if there is new stuff, or "0" if there isn't. Note that once this values becomes "1" and you alert the user, stop polling! It'd be pointless to have the client hitting the server all night while the user slept. Once the user acknowleges the notifcation (double-clicks the system tray or panel applet or whatnot), then resume your polling.

    • interval(required):

      • [scalar](required) How many seconds you must wait before polling the server again. If your client disobeys, this protocol will just return error messages saying "slow down, bad client!" instead of giving you the data you were trying to cheat to obtain. Note that this also means your client should have an option to disable polling for updates, since some users run multiple operating systems with multiple LiveJournal clients, and both would be fighting each other.

    • count(required):

      • [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(required):

      • [scalar](required) The total number of items that have been updated since the time specified.

Example 4. Sample return value for LJ.XMLRPC.checkfriends

HTTP/1.1 200 OK
Connection: close
Content-length: 358
Content-Type: text/xml
Date: Tue, 16 Jul 2002 22:49:07 GMT
Server: Apache/1.3.4 (Unix)

<?xml version="1.0"?>
<methodResponse>
<params>
<param>

<value><struct>
<member><name>lastupdate</name>
<value><string>2002-07-16 14:22:16</string></value>
</member>
<member><name>new</name>

<value><int>0</int></value>
</member>
<member><name>interval</name>
<value><int>90</int></value>

</member>
</struct></value>
</param>
</params>
</methodResponse>