742 lines
36 KiB
Plaintext
Executable File
742 lines
36 KiB
Plaintext
Executable File
{ getfriendgroups
|
|
.des
|
|
Retrieves a list of the user's defined groups of friends.
|
|
.response
|
|
{ frgrp_<I>num</I>_name
|
|
.des
|
|
The name of the friend group with number <I>num</I>.
|
|
}
|
|
{ frgrp_<I>num</I>_sortorder
|
|
.des
|
|
The sort-order of the friend group with number <I>num</I>. An integer value between 0 and 255.
|
|
}
|
|
{ frgrp_<I>num</I>_public
|
|
.des
|
|
If this key is returned and its value is "1", then group <I>num</I> is a public group. (that is, other users can see the name of the group and who is in it)
|
|
}
|
|
{ frgrp_maxnum
|
|
.des
|
|
The largest friend group number that was returned. This is <B>not</B> 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 <TT>frgrp_maxnum</TT>, 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.
|
|
}
|
|
}
|
|
|
|
{ editfriendgroups
|
|
.des
|
|
Edit the user's defined groups of friends.
|
|
.request
|
|
{ editfriend_groupmask_<I>friend</I>
|
|
.des
|
|
Send a key in the form editfriend_groupmask_<I>friend</I> where <I>friend</I> is the friend's username. The value should be a string representing an unsigned 32-bit integer with bit 0 set (or the server will force it on anyway), bits 1-30 set for each group the friend belongs to, and bit 31 unset (reserved for future use).
|
|
}
|
|
{ efg_delete_<I>groupnum</I>
|
|
.des
|
|
Send a key of this type to delete the friend group with number <I>groupnum</I> (which can be from 1-30, inclusive). The server will modify all old entries that allow access to that friend group, so a new friend group using that number won't have access to old non-related entries, and unset the bit for that friend group on the groupmask of each friend, unless your client sends the friend's new groupmask explicitly.
|
|
}
|
|
{ efg_set_<I>groupnum</I>_name
|
|
.des
|
|
Create or rename the friend group by sending this key, where <I>groupnum</I> is from 1-30. The value is the name of the group.
|
|
}
|
|
{ efg_set_<I>groupnum</I>_sort
|
|
.des
|
|
If <TT>efg_set_<I>groupnum</I>_sort</TT> is sent, this field should be sent to indicate the sorting order of this group. The value must be in the range of 0-255. The default is 50.
|
|
}
|
|
{ efg_set_<I>groupnum</I>_public
|
|
.des
|
|
If <TT>efg_set_<I>groupnum</I>_public</TT> is "1", then this group is marked as public. If public, other users can see the name of the group and the people that are in it.
|
|
.optional
|
|
1
|
|
}
|
|
}
|
|
|
|
{ login
|
|
.des
|
|
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 <TT>getfriendgroups</TT> mode)
|
|
.request
|
|
{ clientversion
|
|
.des
|
|
Although optional, this <B>should</B> be a string of the form <tt>Platform-ProductName/ClientVersionMajor.Minor.Rev</tt>, like <B><tt>Win32-MFC/1.2.7</tt></B> or <B><tt>Gtk-LoserJabber/1.0.4</tt></B>. 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.
|
|
.optional
|
|
1
|
|
}
|
|
{ getmoods
|
|
.des
|
|
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
|
|
.des
|
|
Send something for this key if you want to get a list/tree of web jump menus to show in your client.
|
|
}
|
|
{ getpickws
|
|
.des
|
|
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
|
|
.des
|
|
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.
|
|
}
|
|
.response
|
|
{ name
|
|
.des
|
|
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
|
|
.des
|
|
A message that <B>should</B> 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, use the user account <TT>test</TT> with the password <TT>test</TT>... a message will always be returned.
|
|
}
|
|
{ frgrp_<I>num</I>_name
|
|
.des
|
|
The name of the friend group with number <I>num</I>.
|
|
}
|
|
{ frgrp_<I>num</I>_sortorder
|
|
.des
|
|
The sort-order of the friend group with number <I>num</I>. An integer value between 0 and 255.
|
|
}
|
|
{ frgrp_<I>num</I>_public
|
|
.des
|
|
If this key is returned and its value is "1", then group <I>num</I> is a public group. (that is, other users can see the name of the group and who is in it)
|
|
}
|
|
{ frgrp_maxnum
|
|
.des
|
|
The largest friend group number that was returned. This is <B>not</B> 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 <TT>frgrp_maxnum</TT>, 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
|
|
.des
|
|
If this user has access to post in shared journals (i.e., 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_<I>n</I>
|
|
.des
|
|
The <I>n</I>th shared journal this user has access to post to. These are returned in alphabetical order.
|
|
}
|
|
{ mood_count
|
|
.des
|
|
The number of new moods that are being returned.
|
|
}
|
|
{ mood_<I>n</I>_id
|
|
.des
|
|
The server mood ID for mood <I>n</I>, where <I>n</I> is between 1 and <TT>mood_count</TT>.
|
|
}
|
|
{ mood_<I>n</I>_name
|
|
.des
|
|
The mood text for mood <I>n</I>, where <I>n</I> is between 1 and <TT>mood_count</TT>.
|
|
}
|
|
{ menu_<I>menunum</I>_count
|
|
.des
|
|
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_<I>menunum</I>_<I>itemnum</I>_text
|
|
.des
|
|
The text of the <I>itemnum</I>th menu item (1-based index) in the <I>menunum</I>th menu (0-based index.. kinda. it's not really an array.) If the text is a single hypen "-", then show a menu separator bar instead of any text.
|
|
}
|
|
{ menu_<I>menunum</I>_<I>itemnum</I>_url
|
|
.des
|
|
The URL to jump to for the <I>itemnum</I>th menu item (1-based index) in the <I>menunum</I>th menu. This may be absent, in which case this is a menu item which opens a sub-menu.
|
|
}
|
|
{ menu_<I>menunum</I>_<I>itemnum</I>_sub
|
|
.des
|
|
For menus that don't have associated URLs, this key contains the <I>menunum</I> of the associated sub menu. Call your menu creation function recursively and start making that menu.
|
|
}
|
|
{ pickw_count
|
|
.des
|
|
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_<I>n</I>
|
|
.des
|
|
The <I>n</I>th picture keyword, where <I>n</I> is between 1 and <tt>pickw_count</tt>. 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
|
|
.des
|
|
The number of picture URLs being returned, if you sent the 'getpickwurls' key. This number will always be the same as pickw_count.
|
|
}
|
|
{ pickwurl_<i>n</i>
|
|
.des
|
|
The URL of the <i>n</i>th picture. It corresponds with the <i>n</i>th picture keyword returned in the other list. Note that the content behind these URLs can <u>never</u> 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
|
|
.des
|
|
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
|
|
.des
|
|
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 "<tt>Cookie: ljfastserver=1</tt>". 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.
|
|
}
|
|
}
|
|
|
|
{ getdaycounts
|
|
.des
|
|
This mode retrieves the number of journal entries per day. Useful for populating
|
|
calendar widgets in GUI clients.
|
|
.request
|
|
{ usejournal
|
|
.des
|
|
If getting the day counts of a shared journal, include this key and the username you wish to get the counts of. By default, you load the counts of "user" as specified above.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ <I>yyyy-mm-dd</I>
|
|
.des
|
|
For each day that the user has posted a journal entry, a key in the form <TT>yyyy-mm-dd</TT> is returned, with the value being the number of entries posted that day. The absence of a key implies zero entries for that day, as well as the presence of a key with the value "<TT>0</TT>". Note that <TT>mm</TT> and <TT>dd</TT> are always two digits, zero padded, so the total key length will always be 10 characters.
|
|
}
|
|
}
|
|
|
|
{ postevent
|
|
.des
|
|
The most important mode, this is how a user actually submits a new log entry to the server.
|
|
.response
|
|
{ itemid
|
|
.des
|
|
The unique number the server assigned to this post. Currently nothing else in the protocol requires the use of this number so it's pretty much useless, but somebody requested it be returned, so it is.
|
|
}
|
|
{ anum
|
|
.des
|
|
The authentication number generated for this entry. It can be used by the client to generate URLs, but that is not recommended. (See the returned 'url' element if you want to link to a post.)
|
|
}
|
|
{ url
|
|
.des
|
|
The permanent link address to this post. This is an opaque string--you should store it as is. While it will generally follow a predictable pattern, there is no guarantee of any particular format for these, and it may change in the future.
|
|
}
|
|
.request
|
|
{ event
|
|
.des
|
|
The event/log text the user is submitting. Carriage returns are okay (<TT>0x0A</TT>, <TT>0x0A0D</TT>, or <TT>0x0D0A</TT>), although <TT>0x0D</TT> are removed internally to make everything into Unix-style line-endings (just <TT>\n</TT>s). Posts may also contain HTML, but be aware that the LiveJournal server converts newlines to HTML <TT><BR></TT>s when displaying them, so your client should not try to insert these itself.
|
|
}
|
|
{ lineendings
|
|
.des
|
|
Specifies the type of line-endings you're using. Possible values are <B><TT>unix</TT></B> (<TT>0x0A (\n)</TT>), <B><TT>pc</TT></B> (<TT>0x0D0A (\r\n)</TT>), or <B><TT>mac</TT></B> (<TT>0x0D (\r)</TT>). The default is not-Mac. Internally, LiveJournal stores all text as Unix-formatted text, and it does the conversion by removing all <TT>\r</TT> characters. If you're sending a multi-line event on Mac, you have to be sure and send a <TT>lineendings</TT> value of <B><TT>mac</TT></B> or your line endings will be removed. PC and Unix clients can ignore this setting, or you can send it. It may be used for something more in the future.
|
|
}
|
|
{ subject
|
|
.des
|
|
The subject for this post. Limited to 255 characters. No newlines.
|
|
}
|
|
{ security
|
|
.des
|
|
Specifies who can read this post. Valid values are <B><TT>public</TT></B> (default), <B><TT>private</TT></B> and <B><TT>usemask</TT></B>. When value is <TT>usemask</TT>, viewability is controlled by the <TT>allowmask</TT>.
|
|
.optional
|
|
1
|
|
}
|
|
{ allowmask
|
|
.des
|
|
Relevant when <TT>security</TT> is <TT>usemask</TT>. A 32-bit unsigned integer representing which of the user's groups of friends are allowed to view this post. Turn bit 0 on to allow any defined friend to read it. Otherwise, turn bit 1-30 on for every friend group that should be allowed to read it. Bit 31 is reserved.
|
|
}
|
|
{ year
|
|
.des
|
|
The current 4-digit year (from the user's local timezone).
|
|
}
|
|
{ mon
|
|
.des
|
|
The current 1- or 2-digit month (from the user's local timezone).
|
|
}
|
|
{ day
|
|
.des
|
|
The current 1- or 2-digit day of the month (from the user's local timezone).
|
|
}
|
|
{ hour
|
|
.des
|
|
The current 1- or 2-digit hour from 0 to 23 (from the user's local timezone).
|
|
}
|
|
{ min
|
|
.des
|
|
The current 1- or 2-digit minute (from the user's local timezone).
|
|
}
|
|
{ prop_<I>name</I>
|
|
.des
|
|
Set an arbitrary (but restricted) meta-data property to this log item. See [special[logprops]] for the documentation of them and the list of valid names. You may send zero or more keys like this, one for each property you're setting.
|
|
}
|
|
{ usejournal
|
|
.des
|
|
If posting to a shared journal, include this key and the username you wish to post to. By default, you post to the journal of "user" as specified above.
|
|
.optional
|
|
1
|
|
}
|
|
}
|
|
|
|
{ friendof
|
|
.des
|
|
Returns a list of which other LiveJournal users list this user as their friend.
|
|
.request
|
|
{ friendoflimit
|
|
.des
|
|
If set to a numeric value greater than zero, this mode will only return the number of results indicated. Useful only for building pretty lists for display which might have a button to view the full list nearby.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ friendof_count
|
|
.des
|
|
The number of records that will be returned. The records returned are named numerically,
|
|
using a 1-based index. (1 .. <TT>friendof_count</TT>)
|
|
}
|
|
{ friendof_<I>n</I>_user
|
|
.des
|
|
The <I>n</I>th user that lists this user as their friend.
|
|
}
|
|
{ friendof_<I>n</I>_name
|
|
.des
|
|
The <I>n</I>th user's full name.
|
|
}
|
|
{ friendof_<I>n</I>_bg
|
|
.des
|
|
The background color the <I>n</I>th user chose to represent the current user.
|
|
}
|
|
{ friendof_<I>n</I>_fg
|
|
.des
|
|
The text color the <I>n</I>th user chose to represent the current user.
|
|
}
|
|
{ friendof_<I>n</I>_type
|
|
.des
|
|
The account type of this user, if it's not a personal account. Currently the only possible value is "community", which means you're a member of that community.
|
|
}
|
|
{ friendof_<I>n</I>_status
|
|
.des
|
|
The status of this user. If this field is absent, the user has a normal active account. Otherwise the currently possible values for this field are "deleted", "suspended" and "purged".
|
|
}
|
|
}
|
|
|
|
{ getfriends
|
|
.des
|
|
Returns a list of which other LiveJournal users this user lists as their friend.
|
|
.request
|
|
{ includefriendof
|
|
.des
|
|
If set to <TT>1</TT>, you will also get back the info from the "friendof" mode. Some clients show friends and friendof data in separate tabs/panes. If you're always going to load both, then use this flag (as opposed to a tabbed dialog approach, where the user may not go to the second tab and thus would not need to load the friendof data.) friendof request variables can be used.
|
|
.optional
|
|
1
|
|
}
|
|
{ includegroups
|
|
.des
|
|
If set to <TT>1</TT>, you will also get back the info from the "getfriendgroups" mode. See above for the reason why this would be useful.
|
|
.optional
|
|
1
|
|
}
|
|
{ includebdays
|
|
.des
|
|
If set to <TT>1</TT>, birthdays will be included with the friends results below.
|
|
.optional
|
|
1
|
|
}
|
|
{ friendlimit
|
|
.des
|
|
If set to a numeric value greater than zero, this mode will only return the number of results indicated. Useful only for building pretty lists for display which might have a button to view the full list nearby.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ friend_count
|
|
.des
|
|
The number of records that will be returned. The records returned are named numerically,
|
|
using a 1-based index. (1 .. <TT>friend_count</TT>)
|
|
}
|
|
{ friend_<I>n</I>_user
|
|
.des
|
|
The <I>n</I>th friend's user name.
|
|
}
|
|
{ friend_<I>n</I>_name
|
|
.des
|
|
The <I>n</I>th friend's full name.
|
|
}
|
|
{ friend_<I>n</I>_birthday
|
|
.des
|
|
The <I>n</I>th friend's birthday. Note that this is only returned if the user has set
|
|
their info to visible and if they have set a birthday, otherwise this key is skipped.
|
|
You will also need to set <TT>includebdays</TT> to 1 when you make the request in order to
|
|
receive this field.
|
|
}
|
|
{ friend_<I>n</I>_bg
|
|
.des
|
|
The background color representing the <I>n</I>th friend.
|
|
}
|
|
{ friend_<I>n</I>_fg
|
|
.des
|
|
The text color representing the <I>n</I>th friend.
|
|
}
|
|
{ friend_<I>n</I>_groupmask
|
|
.des
|
|
If the group mask is not "1" (just bit 0 set), then this variable is returned with an 32-bit unsigned integer with a bit 0 always set, and bits 1-30 set for each group this friend is a part of. Bit 31 is reserved.
|
|
}
|
|
{ friend_<I>n</I>_type
|
|
.des
|
|
The account type of this friend, if it's not a personal account. Currently the only possible values are "community" and "syndicated", which means you're monitoring this community/syndicated feed on your friends list. (Note that it does not imply that you're a member of the community if the type is community, just that you monitor it.)
|
|
}
|
|
{ friend_<I>n</I>_status
|
|
.des
|
|
The status of this user. If this field is absent, the user has a normal active account. Otherwise the currently possible values for this field are "deleted", "suspended" and "purged".
|
|
}
|
|
}
|
|
|
|
{ editfriends
|
|
.des
|
|
Add, edit, or delete friends from the user's friends list.
|
|
.request
|
|
{ editfriend_delete_<I>user</I>
|
|
.des
|
|
Sending a variable of this form removes the friend <I>user</I> from the user's friend list. It is not an error to delete an already non-existant friend. The value should just be <TT><B>1</B></TT>.
|
|
}
|
|
{ editfriend_add_<I>i</I>_user
|
|
.des
|
|
To add a friend, send a variable of this form, where <I>i</I> is any unique integer. The value is the username of the friend to add.
|
|
}
|
|
{ editfriend_add_<I>i</I>_fg
|
|
.des
|
|
Sets the text color of the friend <I>i</I> being added. This value is a HTML-style hex-triplet, and must either be of the form <B><TT>#rrggbb</TT></B> or not sent at all. By default, the value assumed is <TT>#000000</TT>, black.
|
|
.optional
|
|
1
|
|
}
|
|
{ editfriend_add_<I>i</I>_bg
|
|
.des
|
|
Sets the background color of the friend <I>i</I> being added. This value is a HTML-style hex-triplet, and must either be of the form <B><TT>#rrggbb</TT></B> or not sent at all. By default, the value assumed is <TT>#FFFFFF</TT>, white.
|
|
.optional
|
|
1
|
|
}
|
|
{ editfriend_add_<I>i</I>_groupmask
|
|
.des
|
|
Sets this user's groupmask. Only use this in clients if you've very recently loaded the friend groups. If your client has been loaded on the end user's desktop for days and you haven't loaded friend groups since it started, they may be inaccurate if they've modified their friend groups through the website or another client. In general, don't use this key unless you know what you're doing.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ friends_added
|
|
.des
|
|
The number of friends that were added with this transaction. The records returned indicate which friends were added, along with their names, named using a 1-based index. (from 1 .. <TT>friends_added</TT>)
|
|
}
|
|
{ friend_<I>n</I>_user
|
|
.des
|
|
The username of the <I>n</I>th friend that was added.
|
|
}
|
|
{ friend_<I>n</I>_name
|
|
.des
|
|
The name of the <I>n</I>th friend that was added.
|
|
}
|
|
}
|
|
|
|
{ getevents
|
|
.des
|
|
Download parts of the user's journal.
|
|
.request
|
|
{ truncate
|
|
.des
|
|
An optional value that if greater than or equal to 4, truncates the length of the returned events (after being decoded) to the value specified. Entries less than or equal to this length are left untouched. Values greater than this length are truncated to the specified length minus 3, and then have "<TT>...</TT>" appended to them, bringing the total length back up to what you specified. This is good for populating list boxes where only the beginning of the entry is important, and you'll double-click it to bring up the full entry.
|
|
.optional
|
|
1
|
|
}
|
|
{ prefersubject
|
|
.des
|
|
If this setting is set to true (<B><TT>1</TT></B>), then no subjects are returned, and the events are actually subjects if they exist, or if not, then they're the real events. This is useful when clients display history and need to give the user something to double-click. The subject is shorter and often more informative, so it'd be best to download only this.
|
|
}
|
|
{ noprops
|
|
.des
|
|
If this setting is set to true (<B><TT>1</TT></B>), then no meta-data properties are returned.
|
|
}
|
|
{ selecttype
|
|
.des
|
|
Determines how you want to specify what part of the journal to download. Valid values are <B><TT>day</TT></B> to download one entire day, <B><TT>lastn</TT></B> to get the most recent <I>n</I> entries (where <I>n</I> is specified in the <TT>howmany</TT> field), <B><TT>one</TT></B> to download just one specific entry, or <b><tt>syncitems</tt></b> to get some number of items (which the server decides) that have changed since a given time (specified in the <tt>lastsync</tt> parameter>). Not that because the server decides what items to send, you may or may not be getting everything that's changed. You should use the <tt>syncitems</tt> selecttype in conjuntions with the <tt>syncitems</tt> protocol mode.
|
|
}
|
|
{ lastsync
|
|
.des
|
|
For a <tt>selecttype</tt> of <b><tt>syncitems</tt></b>, the date (in "yyyy-mm-dd hh:mm:ss" format) that you want to get updates since.
|
|
}
|
|
{ year
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>day</TT></B>, the 4-digit year of events you want to retrieve.
|
|
}
|
|
{ month
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>day</TT></B>, the 1- or 2-digit month of events you want to retrieve.
|
|
}
|
|
{ day
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>day</TT></B>, the 1- or 2-digit day of the month of events you want to retrieve.
|
|
}
|
|
{ howmany
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>lastn</TT></B>, how many entries to get. Defaults to 20. Maximum is 50.
|
|
}
|
|
{ beforedate
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>lastn</TT></B>, you can optionally include this variable and restrict all entries returned to be <I>before</I> the date you specify, which must be of the form <B><TT>yyyy-mm-dd hh:mm:ss</TT></B>.
|
|
.optional
|
|
1
|
|
}
|
|
{ itemid
|
|
.des
|
|
For a <TT>selecttype</TT> of <B><TT>one</TT></B>, the journal entry's unique ItemID for which you want to retrieve. Or, to retrieve the most recent entry, use the value <TT>-1</TT>. Using <TT>-1</TT> has the added effect that the data is retrieved from the master database instead of a replicated slave. Clients with an "Edit last entry" feature might want to send -1, to make sure the data that comes back up is accurate, in case a slave database is a few seconds behind in replication.
|
|
}
|
|
{ lineendings
|
|
.des
|
|
The desired type of line-endings you'd like LiveJournal to return. Possible values are
|
|
<B><TT>unix</TT></B> (<TT>0x0A (\n)</TT>),
|
|
<B><TT>pc</TT></B> (<TT>0x0D0A (\r\n)</TT>, the default),
|
|
<B><TT>mac</TT></B> (<TT>0x0D (\r)</TT>),
|
|
<B><TT>space</TT></B> (newlines become spaces),
|
|
or <B><TT>dots</TT></B> (newlines become " ... "). The PC format was chosen
|
|
as a default because it contains both Unix and Mac line endings in it, so if a client doesn't pick a line ending format, the worst case scenario is there are some ugly characters in the client's textbox beside the real newlines.
|
|
}
|
|
{ usejournal
|
|
.des
|
|
If getting the history of a shared journal, include this key and the username you wish to get the history of. By default, you load the history of "user" as specified above.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ events_count
|
|
.des
|
|
The number of events being returned. The records returned are number from 1 to <TT>events_count</TT>.
|
|
}
|
|
{ events_<I>n</I>_itemid
|
|
.des
|
|
The unique integer ItemID of the <I>n</I>th item being returned.
|
|
}
|
|
{ events_<I>n</I>_eventtime
|
|
.des
|
|
The time the user posted (or said they posted, rather, since users can back-date posts) the <I>n</I>th item being returned.
|
|
}
|
|
{ events_<I>n</I>_event
|
|
.des
|
|
The <I>n</I>th event text itself. This value is first truncated if the <TT>truncate</TT> variable is set, and then it is URL-encoded (alphanumerics stay the same, weird symbols to <TT>%hh</TT>, and spaces to <TT>+</TT> signs, just like URLs or post request). This allows posts with line breaks to come back on one line.
|
|
}
|
|
{ events_<I>n</I>_security
|
|
.des
|
|
If this variable is <U>not</U> returned, then the security of the post is <B><TT>public</TT></B>, otherwise this value will be <B><TT>private</TT></B> or <B><TT>usemask</TT></B>.
|
|
}
|
|
{ events_<I>n</I>_allowmask
|
|
.des
|
|
If <TT>security</TT> is <B><TT>usemask</TT></B> then this is defined with the 32-bit unsigned int bit-mask of who is allowed to access this post.
|
|
}
|
|
{ events_<I>n</I>_subject
|
|
.des
|
|
The subject of the journal entry. This won't be returned if "prefersubjects" is set, instead the subjects will show up as the events.
|
|
}
|
|
{ events_<I>n</I>_poster
|
|
.des
|
|
If the poster of this event is different from the <B><TT>user</TT></B> value sent above, then this key will be included and will specify the username of the poster of this event. If this key is not present, then it is safe to assume that the poster of this event is none other than <B><TT>user</TT></B>.
|
|
}
|
|
{ events_<I>n</I>_anum
|
|
.des
|
|
The authentication number generated for this entry. It can be used by the client to generate URLs, but that is not recommended. (See the returned 'url' element if you want to link to a post.)
|
|
}
|
|
{ events_<I>n</I>_url
|
|
.des
|
|
The permanent link address to this post. This is an opaque string--you should store it as is. While it will generally follow a predictable pattern, there is no guarantee of any particular format for these, and it may change in the future.
|
|
}
|
|
{ prop_count
|
|
.des
|
|
The number of event properties being returned (meta-data about journal entries). Note that this will not even be returned if you set <TT>noprops</TT> to true.
|
|
}
|
|
{ prop_<I>n</I>_itemid
|
|
.des
|
|
The ItemID of the journal entry that this meta-data is attached to.
|
|
}
|
|
{ prop_<I>n</I>_name
|
|
.des
|
|
The character string (alphanumerics and underscore only) of the meta-data property name.
|
|
}
|
|
{ prop_<I>n</I>_value
|
|
.des
|
|
The value of the <I>n</I>th meta-data property.
|
|
}
|
|
}
|
|
|
|
{ editevent
|
|
.des
|
|
Edit or delete a user's past journal entry
|
|
.request
|
|
{ itemid
|
|
.des
|
|
The unique ItemID of the item being modified or deleted.
|
|
}
|
|
{ event
|
|
.des
|
|
The revised event/log text the user is submitting. Or, to delete an entry, just send no text at all. Carriage returns are okay (<TT>0x0A</TT>, <TT>0x0A0D</TT>, or <TT>0x0D0A</TT>), although <TT>0x0D</TT> are removed internally to make everything into Unix-style line-endings (just <TT>\n</TT>s). Posts may also contain HTML, but be aware that the LiveJournal server converts newlines to HTML <TT><BR></TT>s when displaying them, so your client should not try to insert these itself.
|
|
}
|
|
{ lineendings
|
|
.des
|
|
Specifies the type of line-endings you're using. Possible values are <B><TT>unix</TT></B> (<TT>0x0A (\n)</TT>), <B><TT>pc</TT></B> (<TT>0x0D0A (\r\n)</TT>), or <B><TT>mac</TT></B> (<TT>0x0D (\r)</TT>). The default is not-Mac. Internally, LiveJournal stores all text as Unix-formatted text, and it does the conversion by removing all <TT>\r</TT> characters. If you're sending a multi-line event on Mac, you have to be sure and send a <TT>lineendings</TT> value of <B><TT>mac</TT></B> or your line endings will be removed. PC and Unix clients can ignore this setting, or you can send it. It may be used for something more in the future.
|
|
}
|
|
{ subject
|
|
.des
|
|
The subject for this post. Limited to 255 characters. No newlines.
|
|
}
|
|
{ security
|
|
.des
|
|
Specifies who can read this post. Valid values are <B><TT>public</TT></B> (default), <B><TT>private</TT></B> and <B><TT>usemask</TT></B>. When value is <TT>usemask</TT>, viewability is controlled by the <TT>allowmask</TT>.
|
|
.optional
|
|
1
|
|
}
|
|
{ allowmask
|
|
.des
|
|
Relevant when <TT>security</TT> is <TT>usemask</TT>. A 32-bit unsigned integer representing which of the user's groups of friends are allowed to view this post. Turn bit 0 on to allow any defined friend to read it. Otherwise, turn bit 1-30 on for every friend group that should be allowed to read it. Bit 31 is reserved.
|
|
}
|
|
{ year
|
|
.des
|
|
If modifying only, the 4-digit year of the event (from the user's local timezone).
|
|
}
|
|
{ mon
|
|
.des
|
|
If modifying only, the 1- or 2-digit month of the event (from the user's local timezone).
|
|
}
|
|
{ day
|
|
.des
|
|
If modifying only, the 1- or 2-digit day of the month of the event (from the user's local timezone).
|
|
}
|
|
{ hour
|
|
.des
|
|
If modifying only, the 1- or 2-digit hour from 0 to 23 of the event (from the user's local timezone).
|
|
}
|
|
{ min
|
|
.des
|
|
If modifying only, the 1- or 2-digit minute of the event (from the user's local timezone).
|
|
}
|
|
{ prop_<I>name</I>
|
|
.des
|
|
Set an arbitrary (but restricted) meta-data property to this log item. If a key is sent, but the value is blank or zero (0), then the value of the given <I>name</I> is deleted from this item's property list. See [special[logprops]] for more information.
|
|
}
|
|
{ usejournal
|
|
.des
|
|
If editing a shared journal entry, include this key and the username you wish to edit the entry in. By default, you edit the entry as if it were in user "user"'s journal, as specified above.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ itemid
|
|
.des
|
|
The unique number the server assigned to this post.
|
|
}
|
|
{ anum
|
|
.des
|
|
The authentication number for this entry. It can be used by the client to generate URLs, but that is not recommended. (See the returned 'url' element if you want to link to a post.)
|
|
}
|
|
{ url
|
|
.des
|
|
The permanent link address to this post. This is an opaque string--you should store it as is. While it will generally follow a predictable pattern, there is no guarantee of any particular format for these, and it may change in the future.
|
|
}
|
|
}
|
|
|
|
{ syncitems
|
|
.des
|
|
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 LiveJournal 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 <tt>getevents</tt> mode with a <tt>selecttype</tt> of "syncitems".
|
|
.request
|
|
{ lastsync
|
|
.des
|
|
The date you last downloaded synced, in "yyyy-mm-dd hh:mm:ss" format. <b>Note:</b> 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.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ sync_total
|
|
.des
|
|
The total number of items that have been updated since the time specified.
|
|
}
|
|
{ sync_count
|
|
.des
|
|
The number of items that are contained in this response (numbered started at 1). If <tt>sync_count</tt> is equal to <tt>sync_total</tt>, then you can stop your sync after you complete fetching every item in this response.
|
|
}
|
|
{ sync_<i>n</i>_item
|
|
.des
|
|
The <i>n</i>th item, in the form "Type-Number". Type can be one of "L" for log entries (journal entries), "C" for comments (not implemented), "T" for to-do items (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 "T" and go back and fetch everything of that type from the beginning.
|
|
}
|
|
{ sync_<i>n</i>_action
|
|
.des
|
|
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".
|
|
}
|
|
{ sync_<i>n</i>_time
|
|
.des
|
|
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", "T", "C", etc...). This is what you send in subsequent requests in <tt>lastsync</tt>.
|
|
}
|
|
}
|
|
|
|
{ checkfriends
|
|
.des
|
|
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.
|
|
.request
|
|
{ lastupdate
|
|
.des
|
|
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
|
|
.des
|
|
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.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ lastupdate
|
|
.des
|
|
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
|
|
.des
|
|
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, <b>stop polling!</b> 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
|
|
.des
|
|
How many seconds you <b>must</b> 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.
|
|
}
|
|
}
|
|
|
|
{ getchallenge
|
|
.des
|
|
Generate a one-time, quick expiration challenge to be used in challenge/response authentication methods.
|
|
.response
|
|
{ auth_scheme
|
|
.des
|
|
You can ignore this for now. By default this is the highest version of our
|
|
authentication schemes, if in the future if we implement other auth schemes or change the default.
|
|
In that case we'd add a new capabilities exchange: your client could say, "I know c0 and c1", and
|
|
our server would then say, "Use c1, it's the best."
|
|
}
|
|
{ challenge
|
|
.des
|
|
An opaque cookie to generate a hashed response from.
|
|
}
|
|
{ expire_time
|
|
.des
|
|
The expiration time of the challenge, as measured in seconds since the Unix epoch.
|
|
}
|
|
{ server_time
|
|
.des
|
|
The server time when the challenge was generated, as measured in seconds since the Unix epoch.
|
|
}
|
|
}
|
|
|
|
{ sessionexpire
|
|
.des
|
|
Expires one or more sessions that a user has active within the system. This can be used to log a user out of any browsers they are logged in from as well as to cancel any sessions created with the sessionexpire mode.
|
|
.request
|
|
{ expireall
|
|
.des
|
|
If present and true, will expire all of a user's sessions.
|
|
.optional
|
|
1
|
|
}
|
|
{ expire_id_<I>num</I>
|
|
.des
|
|
If present and true, will expire the session with id <i>num</i>. You can get the id of a session from the third element of the session: <tt>ws:<i>username</i>:<i>session_id</i>:<i>auth_code</i></tt>.
|
|
.optional
|
|
1
|
|
}
|
|
}
|
|
|
|
{ sessiongenerate
|
|
.des
|
|
Generates a session that can be used to setup a cookie for accessing the site with a user's privileges.
|
|
.request
|
|
{ expiration
|
|
.des
|
|
Sessions can either expire in a short amount of time or last for a long period of time. You can specify either "short" or "long" as the value of this parameter.
|
|
.optional
|
|
1
|
|
}
|
|
{ ipfixed
|
|
.des
|
|
If specified and true, this will cause the server to generate a session that is only valid from the IP address the sessiongenerate request was sent from. If you leave out this value, it will default to allowing any IP address to use this session information.
|
|
.optional
|
|
1
|
|
}
|
|
.response
|
|
{ ljsession
|
|
.des
|
|
This part of the response contains the actual session data. If you use the complete contents of this element as a cookie named "ljsession" then you will be able to access the site using the privileges of the user you authenticated as.
|
|
}
|
|
}
|