»

checkfriends

checkfriends — 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.

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

mode

The protocol request mode: checkfriends

user

Username. Leading and trailing whitespace is ignored, as is case.

auth_method

The authentication method used for this request. Default is 'clear', for plain-text authentication. 'cookie' or any of the challenge / response methods are also acceptable.

password

DEPRECATED. Password in plain-text. For the default authentication method, either this needs to be sent, or hpassword.

hpassword

DEPRECATED. Alternative to plain-text password. Password as an MD5 hex digest. Not perfectly secure, but defeats the most simple of network sniffers.

auth_challenge

If using challenge / response authentication, this should be the challenge that was generated for your client.

auth_response

If using challenge / response authentication, this should be the response hash you generate based on the challenge's formula.

ver

(Optional) 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

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) 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.

Return Values

success

OK on success or FAIL when there's an error. When there's an error, see errmsg for the error text. The absence of this variable should also be considered an error.

errmsg

The error message if success was FAIL, not present if OK. If the success variable isn't present, this variable most likely won't be either (in the case of a server error), and clients should just report "Server Error, try again later.".

lastupdate

The time of the most recent post that one of the user's friends has made. Don't try to infer anything from this time. It's currently of the form "yyyy-mm-dd hh:mm:ss", in PST. However, in the future, it may not even be a date... just blindly store and return this value back later, ignoring its format.

new

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. A few people requested that this return the number of new entries, but that's a lot more resource intensive, and this protocol mode is supposed to be very quick and painless. In the future we may add a "new_count" response value that says how many new items there are. 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

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.