login — validate user's password and get base information needed for client to function
Login 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, the list of the user's friend groups, and other things.
[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
clientversion(optional):
[scalar](required) Although optional, this should be a string of the form Platform-ProductName/ClientVersionMajor.Minor.Rev, like Win32-MFC/1.2.7 or Gtk-LoserJabber/1.0.4. Note in this case that "Gtk" is not a platform, but rather a toolkit, since the toolkit is multi-platform (Linux, FreeBSD, Solaris, Windows...). You make the judge what is best to send, but if it's of this form, we'll give you cool statistics about your users.
getmoods(optional):
[scalar](required) 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(optional):
[scalar](required) Send something for this key if you want to get a list/tree of web jump menus to show in your client.
getpickws(optional):
[scalar](required) If your client supports picture keywords and you want to receive that list, send something for this key, like "1", and you'll receieve the list of picture keywords the user has defined.
getpickwurls(optional):
[scalar](required) If your client supports picture keywords and can also display the pictures somehow, send something for this key, like "1", and you'll receieve 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.
Example 25. Sample call to LJ.XMLRPC.login
POST /interface/xmlrpc HTTP/1.0 User-Agent: XMLRPC Client 1.0 Host: www.livejournal.com Content-Type: text/xml Content-Length: 396 <?xml version="1.0"?> <methodCall> <methodName>LJ.XMLRPC.login</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> </struct></value> </param> </params> </methodCall>
[struct](required)
Containing keys:
fullname(required):
[scalar](required) 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(optional):
[scalar](required) 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 email address), etc. To test this if you're developing a client, use the user account test with the password test and a message will always be returned.
friendgrounds(required):
[array](required) Containing items:
[struct](optional; multiple allowed)
Containing keys:
id(required):
[scalar](required) The bit number for this friend group, from 1-30.
name(required):
[scalar](required) The name of this friend group.
sortorder(required):
[scalar](required) The sort integer for this friend group, from 0-255.
public(required):
[scalar](required) Either '0' or '1' for if this friend group is public.
usejournals(optional): List of shared/news/community journals that the user has permission to post in.
[array](required) Containing items:
[scalar](optional; multiple allowed) Username of community journal.
moods(optional): If you sent the 'getmoods' key in your request, this is returned. The contents are the new moods that have been added on the server since you last requested the list. Your client should cache the mood list on the client's computer to avoid requesting the whole list everytime.
[array](required) Containing items:
[struct](optional; multiple allowed)
Containing keys:
id(required):
[scalar](required) The integer moodid.
name(required):
[scalar](required) The mood name.
parent(required):
[scalar](required) The mood's parent (base) moodid.
pickws(optional): This is requrned if you set "getpickws" in your request. 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.
[array](required) Containing items:
[scalar](optional; multiple allowed) The picture keyword.
pickwurls(optional): The URLs of the user pictures. They correspond with the list of picture keywords returned. 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.
[array](required) Containing items:
[scalar](optional; multiple allowed) The picture URL.
defaultpicurl(optional):
[scalar](required) 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(optional):
[scalar](required) 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.
userid(required):
[scalar](required) The userid of this user on the system. Not required for any other requests to the server, but some developers have wanted it.
menus(optional): Returned if you set "getmenus" in your request.
[array](required)List of menu items in order that should be in the LiveJournal web menu in the client application. Containing items:
[struct](optional; multiple allowed)
Containing keys:
text(required):
[scalar](required) The text of the menu item, or "-" for a separator.
url(optional):
[scalar](required) The URL the menu item should launch, present for all menu items except separators and submenus.
sub(optional): If this is present, this menu item is a submenu.
[array](optional; multiple allowed)Same format as top-level menu structure Containing items:
[struct](required)
Containing keys:
Example 26. Sample return value for LJ.XMLRPC.login
HTTP/1.1 200 OK Connection: close Content-length: 755 Content-Type: text/xml Date: Sun, 14 Jul 2002 23:45:59 GMT Server: Apache/1.3.4 (Unix) <?xml version="1.0"?> <methodResponse> <params> <param> <value><struct> <member><name>userid</name> <value><int>3</int></value> </member> <member><name>message</name> <value><string>You need to validate your new email address. Your old one was good, but since you've changed it, you need to re-validate the new one. Visit the support area for more information.</string></value> </member> <member><name>fullname</name> <value><string>Test Account</string></value> </member> <member><name>friendgroups</name> <value><array> <data> </data> </array></value> </member> <member><name>usejournals</name> <value><array> <data> <value><string>test2</string></value> </data> </array></value> </member> </struct></value> </param> </params> </methodResponse>