151 lines
6.1 KiB
XML
Executable File
151 lines
6.1 KiB
XML
Executable File
<chapter id="ljp.csp.guide">
|
|
<chapterinfo>
|
|
<title>Client / Server Protocol - Quick Reference</title>
|
|
</chapterinfo>
|
|
<title>Client / Server Protocol - Quick Reference</title>
|
|
<section id="ljp.csp.guide.intro">
|
|
<title>Introduction to the Protocol</title>
|
|
<note>
|
|
<para>
|
|
Before reading this document, it is assumed you know at least some
|
|
basics about network programming, at least the whole idea of opening
|
|
sockets and reading/writing to them. If not, this might be kinda
|
|
confusing.
|
|
</para>
|
|
</note>
|
|
<para>Basically, sending a LiveJournal request is like this:</para>
|
|
<procedure>
|
|
<title>Handshake</title>
|
|
<step>
|
|
<para>Open a socket to www.livejournal.com on port 80</para>
|
|
</step>
|
|
<step>
|
|
<para>Send an HTTP POST request, containing the request variables (mode, user, password, etc...)</para>
|
|
</step>
|
|
<step>
|
|
<para>Read the socket to get the response. The response is really easy to parse.</para>
|
|
</step>
|
|
<step>
|
|
<para>Close the socket. Do any approriate action based on the server's response.</para>
|
|
</step>
|
|
</procedure>
|
|
<para>For example, your client would output a request:
|
|
<programlisting>
|
|
<![CDATA[
|
|
POST /interface/flat HTTP/1.0
|
|
Host: www.livejournal.com
|
|
Content-type: application/x-www-form-urlencoded
|
|
Content-length: 34
|
|
|
|
mode=login&user=test&password=test
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
All values must be quoted or the values can interfere with the encoding form.
|
|
For example, if someone's password was <quote>blah&=2+&something=yeah</quote>,
|
|
it could quite possibly ruin the encoding format.
|
|
Here are some guidelines on how to encode values:
|
|
<itemizedlist>
|
|
<listitem><para>Leave all values from a-z, A-Z, and 0-9 alone. These are fine.</para></listitem>
|
|
<listitem><para>Convert spaces to a + (plus) sign.</para></listitem>
|
|
<listitem><para>Convert everything else to %<replaceable>hh</replaceable> where <replaceable>hh</replaceable> is the hex representation of the character's <abbrev>ASCII</abbrev> value.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
For example, the phrase <quote>I'm going to the mall</quote> could encoded as <quote>I%27m+going+to+the+mall</quote>.
|
|
There should be <abbrev>CGI</abbrev> libraries for all major languages which do this encoding for you.
|
|
If not, it isn't that hard to do it yourself.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
After you construct the big long ugly string of variables/values, find the length of
|
|
it and send it in the Content-length field, as in the example above.
|
|
Then send a blank line, then the big long ugly string.
|
|
</para>
|
|
<note><title>Line Endings</title>
|
|
<para>
|
|
Please note that the end of lines should be a carriage return
|
|
(<abbrev>ASCII</abbrev> <literal>13</literal>, <literal>0x0D</literal>) and then a
|
|
newline (<abbrev>ASCII</abbrev> <literal>10</literal>, <literal>0x0A</literal>).
|
|
In Perl, C/C++ or Java this is <quote>\r\n</quote>.
|
|
In Basic, this is <literal>Chr(13)</literal> & <literal>Chr(10)</literal>.
|
|
Sending just the newline may work too, but it's generally better to send both.
|
|
</para>
|
|
</note>
|
|
<para>A typical response would be:
|
|
<programlisting>
|
|
<![CDATA[
|
|
HTTP/1.1 200 OK
|
|
Date: Sat, 23 Oct 1999 21:32:35 GMT
|
|
Server: Apache/1.3.4 (Unix)
|
|
Connection: close
|
|
Content-Type: text/plain
|
|
|
|
name
|
|
Mr. Test Account
|
|
success
|
|
OK
|
|
message
|
|
Hello Test Account!
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
The top stuff is headers from the <abbrev>HTTP</abbrev> request.
|
|
There may be a lot of other stuff in there too.
|
|
First thing to do is make sure the first lines ends with <quote><literal>200 OK</literal></quote>.
|
|
If the first line does not end with <quote><literal>200 OK</literal></quote>,
|
|
tell the user that an error occurred on the server and that it's not their fault.
|
|
If you see <quote><literal>200 OK</literal></quote> at the end, proceed with parsing the output.
|
|
The format is as follows:
|
|
<programlisting>
|
|
variable
|
|
value
|
|
someothervariable
|
|
someothervalue
|
|
</programlisting>
|
|
The ordering of the variable/value pairs does not matter.
|
|
As you read them in, read them into a hash structure
|
|
(associative array, dictionary, collection…whatever it's called in your language.
|
|
Just a data structure that links one string variable key to another string variable value.).
|
|
</para>
|
|
<para>
|
|
After your hash is loaded, proceed with the logic of reporting errors if needed, as governed by the variables and logic above.
|
|
</para>
|
|
</section>
|
|
<section id="ljp.csp.guide.proxies">
|
|
<title>Working with Proxies</title>
|
|
<para>
|
|
As a final feature, once you get that stuff working, is to implement
|
|
support for HTTP proxies. This is <emphasis>very</emphasis> easy. Give the
|
|
user a checkbox if they want to use a proxy or not, and if so,
|
|
ask the proxy host and proxy port. Now, if they selected to use a proxy, do
|
|
not connect to www.livejournal.com and port 80, but instead connect to their
|
|
proxy host on whatever proxy port they specified. The rest is basically the
|
|
same, except for one difference. Instead of doing:
|
|
<programlisting>
|
|
<![CDATA[
|
|
POST /interface/flat HTTP/1.0 ]]>
|
|
</programlisting>
|
|
You would do:
|
|
<programlisting>
|
|
<![CDATA[
|
|
POST http://www.livejournal.com/interface/flat HTTP/1.0 ]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
That line tells the proxy what host it needs to connect to in order to
|
|
make the real request. The rest of the HTTP you should leave just as you did
|
|
before.
|
|
</para>
|
|
</section>
|
|
<note><title>Client Developer Community</title>
|
|
<para>
|
|
If you ever have any questions about building clients for LiveJournal, then
|
|
you'd probably interested in the <ulink url="http://www.livejournal.com/users/lj_clients/info">lj_clients community</ulink>
|
|
on LiveJournal.com
|
|
</para>
|
|
</note>
|
|
</chapter> |