login

login — Log in to the server, while announcing your client version. The server returns with whether the password is good or not, the user's name, an optional message to be displayed to the user, and the list of the user's friend groups. (friend groups can also be retrieved using the getfriendgroups mode)

Mode Description

Log in to the server, while announcing your client version. The server returns with whether the password is good or not, the user's name, an optional message to be displayed to the user, and the list of the user's friend groups. (friend groups can also be retrieved using the getfriendgroups mode)

Arguments

mode

The protocol request mode: login

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 27, Protocol Versions for details on the protocol version.

clientversion

(Optional) Although optional, this should be a string of the form Platform-ProductName/ClientVersionMajor.Minor.Rev, like Win32-MFC/1.2.7 or GTK2-LogJam: 4.5.3. Note in this case that "GTK2" is not a platform, but rather a toolkit, since the toolkit is multi-platform (Linux, FreeBSD, Solaris, Windows...). You make a judgment what is best to send, but if it is of this form, we give you cool statistics about your users.

getmoods

If your client supports moods, send this key with a value of the highest mood ID you have cached/stored on the user's computer. For example, if you logged in last time with and got mood IDs 1, 2, 4, and 5, then send "5" as the value of "getmoods". The server will return every new mood that has an internal MoodID greater than 5. If you've never downloaded moods before, send "0". If you don't care about getting any moods at all (if your client doesn't support them), then don't send this key at all.

getmenus

Send something for this key if you want to get a list/tree of web jump menus to show in your client.

getpickws

If your client supports picture keywords and you want to receive that list, send something for this key, like "1", and you'll receive the list of picture keywords the user has defined.

getpickwurls

If your client supports picture keywords and can also display the pictures somehow, send something for this key, like "1", and you'll receive the list of picture keyword URLs that correspond to the picture keywords as well as the URL for the default picture. You must send getpickws for this option to even matter.

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 is not present, this variable most likely will not be either (in the case of a server error), and clients should just report "Server Error, try again later.".

name

The user's full name. Often, clients use this to change the top-level window's title bar text to say something like "LiveJournal - User name". You can just ignore this if you'd like.

message

A message that should be displayed in a dialog box (or to the screen in a console application). The message is rarely present but when used notifies the user of software updates they've requested to hear about, problems with their account (if mail is bouncing to them, we'd like them to give us a current e-mail address), etc. For example, on LiveJournal.com a newly-created account will return a message telling the user the e-mail address used for their account has not yet been validated.

frgrp_num_name

The name of the friend group with number num.

frgrp_num_sortorder

The sort-order of the friend group with number num. An integer value between 0 and 255.

frgrp_num_public

If this key is returned and its value is "1", then group num is a public group. (that is, other users can see the name of the group and who is in it)

frgrp_maxnum

The largest friend group number that was returned. This is not the number of friend groups returned, it is simply the upper bound. In other words, there may be holes as you iterate from 1 to frgrp_maxnum, so don't assume the presence of any key/value pairs returned. If this value is 0, however, you can safely assume there are no friend groups, as the minimum allowed friend group number is 1.

access_count

If this user has access to post in shared journals (e.g., news account), then this key is returned saying how many journals (besides the user's own) he/she has access to. Then, a key is returned for each journal.

access_n

The nth shared journal this user has access to post to. These are returned in alphabetical order.

mood_count

The number of new moods that are being returned.

mood_n_id

The server mood ID for mood n, where n is between 1 and mood_count.

mood_n_name

The mood text for mood n, where n is between 1 and mood_count.

menu_menunum_count

Each menu or submenu returns the number of items in it. Menunum "0" is the root menu and that's where you should start your recursive construction of the menus.

menu_menunum_itemnum_text

The text of the itemnumth menu item (1-based index) in the menunumth menu (0-based index.. kinda. it's not really an array.) If the text is a single hyphen "-", then show a menu separator bar instead of any text.

menu_menunum_itemnum_url

The URL to jump to for the itemnumth menu item (1-based index) in the menunumth menu. This may be absent, in which case this is a menu item which opens a sub-menu.

menu_menunum_itemnum_sub

For menus that don't have associated URLs, this key contains the menunum of the associated sub menu. Call your menu creation function recursively and start making that menu.

pickw_count

The number of picture keywords about to be returned. Picture keywords are used to identify which userpic (100x100 icon) to use for that particular post. For instance, the user may have "Angry", "Happy", and "Sleepy" picture keywords which map to certain pictures. The client should also do a case-insensitive compare on this list when a mood is selected or entered, and auto-select the current picture keyword. That way it seems that selecting a mood also sets their corresponding picture.

pickw_n

The nth picture keyword, where n is between 1 and pickw_count. If a user selects one of these, send it as postevent/editevent meta-data with the key "picture_keyword" (which of course you have to prefix with "prop_" when sending)

pickwurl_count

The number of picture URLs being returned, if you sent the 'getpickwurls' key. This number will always be the same as pickw_count.

pickwurl_n

The URL of the nth picture. It corresponds with the nth picture keyword returned in the other list. Note that the content behind these URLs can never change, so if your client downloads these to display, just cache them locally and never hit the servers again to re-download them or to even check if they've been modified.

defaultpicurl

The URL of the default picture (if you sent the 'getpickwurls' key). Note that the content behind this URL can never change, so you can cache it locally; also note that the default picture might have no keyword associated with it.

fastserver

LiveJournal sites may have priority servers for paying customers. If this key is both present and set to value "1", then the client has permission to set the "ljfastserver" cookie in subsequent requests. The HTTP request header to send is "Cookie: ljfastserver=1". If you send this header without getting permission from the login mode, your requests will fail. That is, you'll trick the load balancer into directing your request towards the priority servers, but the server you end up hitting won't be happy that you're trying to scam faster access and will deny your request.