NAME

LJ::Simple - Simple Perl to access LiveJournal

SYNOPSIS

  use LJ::Simple;

  ## Variables - defaults are shown and normally you'll
  ## not have to set any of the following.

  # Do we show debug info ?
  $LJ::Simple::debug = 0;

  # Do we show the LJ protocol ?
  $LJ::Simple::protocol = 0;

  # Where error messages are placed
  $LJ::Simple::error = "";

  # The timeout on reading from sockets in seconds
  $LJ::Simple::timeout = 10;

  # How much data to read from the socket in one read()
  $LJ::Simple::buffer = 8192;

  ## Object creation
  my $lj = new LJ::Simple ( {
		user	=>	"username",
		pass	=>	"password",
		site	=>	"hostname[:port]",
		proxy	=>	"hostname[:port]",
    } );
  my $lj = LJ::Simple->login ( {
		user	=>	"username",
		pass	=>	"password",
		site	=>	"hostname[:port]",
		proxy	=>	"hostname[:port]",
    } );

  ## Routines which pull information from the login data
  $lj->message()
  $lj->moods($hash_ref)
  $lj->communities()
  $lj->MemberOf($community)
  $lj->groups($hash_ref)
  $lj->MapGroupToId($group_name)
  $lj->MapIdToGroup($id)
  $lj->pictures($hash_ref)
  $lj->user()
  $lj->fastserver()

  ## Routines which pull data from the LJ server
  $lj->GetFriendOf()

  ## Routines for handling journal entries
  # Top level journal access routines
  $lj->UseJournal($event,$journal)
  $lj->NewEntry($event)
  $lj->PostEntry($event)
  $lj->DeleteEntry($item_id)
  $lj->SyncItems($time_t)

  # Routines which do more than just set a value within
  # a new journal entry
  $lj->SetDate($event,$time_t)
  $lj->SetMood($event,$mood)

  # Routines for setting subject and journal contents
  $lj->SetSubject($event,$subject)
  $lj->SetEntry($event,@entry)
  $lj->AddToEntry($event,@entry)

  # Routines for setting permissions on the entry
  $lj->SetProtectFriends($event)
  $lj->SetProtectGroups($event,$group1, $group2, ... $groupN)
  $lj->SetProtectPrivate($event)

  # Setting properties for the entry
  $lj->Setprop_backdate($event,$onoff)
  $lj->Setprop_current_mood($event,$mood)
  $lj->Setprop_current_mood_id($event,$id)
  $lj->Setprop_current_music($event,$music)
  $lj->Setprop_preformatted($event,$onoff)
  $lj->Setprop_nocomments($event,$onoff)
  $lj->Setprop_picture_keyword($event,$keyword)
  $lj->Setprop_noemail($event,$onoff)
  $lj->Setprop_unknown8bit($event,$onoff)

DESCRIPTION

LJ::Simple is a trival API to access LiveJournal. Currently all that it does is:

Login: Log into the LiveJournal system
Post: Post a new journal entry in the LiveJournal system
Synchronise: Returns a list of journal entries created or modified from a given date.
Delete: Delete an existing post from the LiveJournal system

Variables available are:

$LJ::Simple::debug

If set to 1, debugging messages are sent to stderr.

$LJ::Simple::protocol

If set to 1 the protocol used to talk to the remote server is sent to stderr.

$LJ::Simple::error

Holds error messages, is set with a blank string at the start of each method. Whilst the messages are relatively free-form, there are some prefixes which are sometimes used:

CODE:     An error in the code calling the API
INTERNAL: An internal error in this module

$LJ::Simple::timeout

The time - specified in seconds - to wait for data from the server. If given a value of undef the API will block until data is avaiable.

$LJ::Simple::buffer

The number of bytes to try and read in on each sysread() call.

The actual methods available are:

Logs into the LiveJournal system.

  my $lj = new LJ::Simple ( {
		user	=>	"username",
		pass	=>	"password",
		site	=>	"hostname[:port]",
		proxy	=>	"hostname[:port]",
    } );
  my $lj = LJ::Simple->login ( {
		user	=>	"username",
		pass	=>	"password",
		site	=>	"hostname[:port]",
		proxy	=>	"hostname[:port]",
    } );

Where:

user     is the username to use
pass     is the password associated with the username
site     is the remote site to use
proxy    is the HTTP proxy site to use

Sites defined in site or proxy are a hostname with an optional port number, separated by a :, i.e.:

www.livejournal.com
www.livejournal.com:80

If site is given undef then the code assumes that you wish to connect to www.livejournal.com:80. If no port is given then port 80 is the default.

If proxy is given undef then the code will go directly to the $site. If no port is given then port 3128 is the default.

On success this sub-routine returns an LJ::Simple object. On failure it returns undef with the reason for the failure being placed in $LJ::Simple::error.

Example code:

  ## Simple example, going direct to www.livejournal.com:80
  my $lj = new LJ::Simple ({ user => "someuser", pass => "somepass" });
  (defined $lj) ||
    die "$0: Failed to access LiveJournal - $LJ::Simple::error\n";

  ## More complex example, going via a proxy server on port 3000 to a
  ## a LiveJournal system available on port 8080 on the machine
  ## www.somesite.com.
  my $lj = new LJ::Simple ({ 
	user	=> "someuser",
	pass	=> "somepass", 
	site	=> "www.somesite.com:8080",
	proxy	=> "proxy.internal:3000",
  });
  (defined $lj) ||
    die "$0: Failed to access LiveJournal - $LJ::Simple::error\n";

$lj->message()

Returns back a message set in the LiveJournal system. Either returns back the message or undef if no message is set.

Example code:

my $msg = $lj->message();
(defined $msg) &&
  print "LJ Message: $msg\n";

$lj->moods($hash_ref)

Takes a reference to a hash and fills it with information about the moods returned back by the server. Either returns back the same hash reference or undef on error.

The hash the given reference is pointed to is emptied before it is used and after a successful call the hash given will contain:

%hash = (
  list    => [ list of mood names, alphabetical ]
  moods   => {
    mood_name => mood_id
  }
  idents  => {
    mood_id   => mood_name
  }
)

Example code:

my %Moods=();
if (!defined $lj->moods(\%Moods)) {
  die "$0: LJ error - $LJ::Simple::error";
}
foreach (@{$Moods{list}}) {
  print "$_ -> $Moods{moods}->{$_}\n";
}

$lj->communities()

Returns a list of shared access communities the user logged in can post to. Returns an empty list if no communities are available

Example code:

my @communities = $lj->communities();
print join("\n",@communities),"\n";

$lj->MemberOf($community)

Returns 1 if the user is a member of the named community. Returns 0 otherwise.

Example code:

if ($lj->MemberOf("some_community")) {
   :
   :
   :
}

$lj->groups($hash_ref)

Takes a reference to a hash and fills it with information about the friends groups the user has configured for themselves. Either returns back the hash reference or undef on error.

The hash the given reference points to is emptied before it is used and after a successful call the hash given will contain the following:

%hash = (
  "name" => {
    "Group name" => {
      id   => "Number of the group",
      sort => "Sort order",
      name => "Group name (copy of key)",
    },
  },
  "id"   => {
    "Id"   => "Group name",
  },
);

Example code:

my %Groups=();
if (!defined $lj->groups(\%Groups)) {
  die "$0: LJ error - $LJ::Simple::error";
}
my ($id,$name)=(undef,undef);
while(($id,$name)=each %{$Groups{id}}) {
  my $srt=$Groups{name}->{$name}->{sort};
  print "$id\t=> $name [$srt]\n";
}

$lj->MapGroupToId($group_name)

Used to map a given group name to its identity. On success returns the identity for the group name. On failure it returns undef and sets $LJ::Simple::error.

$lj->MapIdToGroup($id)

Used to map a given identity to its group name. On success returns the group name for the identity. On failure it returns undef and sets $LJ::Simple::error.

$lj->pictures($hash_ref)

Takes a reference to a hash and fills it with information about the pictures the user has configured for themselves. Either returns back the hash reference or undef on error. Note that the user has to have defined picture keywords for this to work.

The hash the given reference points to is emptied before it is used and after a successful call the hash given will contain the following:

%hash = (
  "keywords"	=> "URL of picture",
);

Example code:

my %pictures=();
if (!defined $lj->pictures(\%pictures)) {
  die "$0: LJ error - $LJ::Simple::error";
}
my ($keywords,$url)=(undef,undef);
while(($keywords,$url)=each %pictures) {
  print "\"$keywords\"\t=> $url\n";
}

$lj->user()

Returns the username used to log into LiveJournal

Example code:

my $user = $lj->user();

$lj->fastserver()

Used to tell if the user which was logged into the LiveJournal system can use the fast servers or not. Returns 1 if the user can use the fast servers, 0 otherwise.

Example code:

if ($lj->fastserver()) {
  print STDERR "Using fast server for ",$lj->user(),"\n";
}

$lj->GetFriendOf()

Returns a list of the other LiveJournal users who list the current user as a friend. The list returned contains a least one entry, the number of entries in the list. This value can range from 0 to however many users are in the list. In the event of a failure this value is undefined.

The list of friends is a list of hash references which contain data about the users who list the current user as a friend. Each hash referenced will contain the following:

{
  user     => The LiveJournal username
  name     => The full name of the user
  fg       => The foreground colour which represents the user
  bg       => The background colour which represents the user
  status   => The status of the user
  type     => The type of the user
}

Both the bg and fg values are stored in the format of "#RRGGBB" where the RR, GG, BB values are given as two digit hexadecimal numbers which range from 00 to ff.

The status of a user can be one of "active", "deleted", "suspended" or "purged".

The type of a user can either be "user" which means that the user is a normal LiveJournal user or it can be "community" which means that the user is actually a community which the current LJ user is a member of.

It should be noted that any of the values in the hash above can be undefined if that value was not returned from the LiveJournal server.

Example code:

my ($num_friends_of,@FriendOf)=$lj->GetFriendOf();
(defined $num_friends_of) ||
  die "$0: Failed to get friends of user - $LJ::Simple::error\n";
print "LJ login\tReal name\tfg\tbg\tStatus\tType\n";
foreach (@FriendOf) {
  print "$_->{user}\t",
        "$_->{name}\t",
        "$_->{fg}\t",
        "$_->{bg}\t",
        "$_->{status}\t",
        "$_->{type}\n";
}

$lj->NewEntry($event)

Prepares for a new journal entry to be sent into the LiveJournal system. Takes a reference to a hash which will be emptied and prepared for use by the other routines used to prepare a journal entry for posting.

On success returns 1, on failure returns 0

Example code:

my %Entry=();
$lj->NewEntry(\%Entry) 
  || die "$0: Failed to prepare new post - $LJ::Simple::error\n";

$lj->SetDate($event,$time_t)

Sets the date for the event being built from the given time_t (i.e. seconds since epoch) value. Bare in mind that you may need to call $lj-Setprop_backdate(\%Event,1)> to backdate the journal entry if the journal being posted to has events more recent than the date being set here. Returns 1 on success, 0 on failure.

If the value given for time_t is undef then the current time is used. If the value given for time_t is negative then it is taken to be relative to the current time, i.e. a value of -3600 is an hour earlier than the current time.

Note that localtime() is called to convert the time_t value into the year, month, day, hours and minute values required by LiveJournal. Thus the time given to LiveJournal will be the local time as shown on the machine the code is running on.

Example code:

## Set date to current time
$lj->SetDate(\%Event,undef)
  || die "$0: Failed to set date of entry - $LJ::Simple::error\n";

## Set date to Wed Aug 14 11:56:42 2002 GMT
$lj->SetDate(\%Event,1029326202)
  || die "$0: Failed to set date of entry - $LJ::Simple::error\n";

## Set date to an hour ago
$lj->SetDate(\%Event,-3600)
  || die "$0: Failed to set date of entry - $LJ::Simple::error\n";

$lj->SetMood($event,$mood)

Given a mood this routine sets the mood for the journal entry. Unlike the more direct $lj-Setprop_current_mood()> and $lj-Setprop_current_mood_id(\%Event,)> routines, this routine will attempt to first attempt to find the mood given to it in the mood list returned by the LiveJournal server. If it is unable to find a suitable mood then it uses the text given.

Returns 1 on success, 0 otherwise.

Example code:

$lj->SetMood(\%Event,"happy")
  || die "$0: Failed to set mood - $LJ::Simple::error\n";

$lj->UseJournal($event,$journal)

The journal entry will be posted into the shared journal given as an argument rather than the default journal for the user.

Returns 1 on success, 0 otherwise.

Example code:

$lj->UseJournal(\%Event,"some_community")
  || die "$0: Failed to - $LJ::Simple::error\n";

$lj->SetSubject($event,$subject)

Sets the subject for the journal entry. The subject has the following limitations:

o Limited to a length of 255 characters
o No newlines are allowed

Returns 1 on success, 0 otherwise.

Example code:

$lj->SetSubject(\%Event,"Some subject")
  || die "$0: Failed to set subject - $LJ::Simple::error\n";

$lj->SetEntry($event,@entry)

Sets the entry for the journal; takes a list of strings. It should be noted that this list will be join()ed together with a newline between each list entry.

If the list is null or undef then any existing entry is removed.

Returns 1 on success, 0 otherwise.

Example code:

# Single line entry
$lj->SetEntry(\%Event,"Just a simple entry")
  || die "$0: Failed to set entry - $LJ::Simple::error\n";

# Three lines of text
my @stuff=(
     "Line 1",
     "Line 2",
     "Line 3",
);
$lj->SetEntry(\%Event,@stuff)
  || die "$0: Failed to set entry - $LJ::Simple::error\n";

# Clear the entry
$lj->SetEntry(\%Event,undef)
  || die "$0: Failed to set entry - $LJ::Simple::error\n";
$lj->SetEntry(\%Event)
  || die "$0: Failed to set entry - $LJ::Simple::error\n";

$lj->AddToEntry($event,@entry)

Adds a string to the existing journal entry being worked on. The new data will be appended to the existing entry with a newline separating them. It should be noted that as with $lj-SetEntry()> the list given to this routine will be join()ed together with a newline between each list entry.

If $lj-SetEntry()> has not been called then $lj-AddToEntry()> acts in the same way as $lj-SetEntry()>.

If $lj-SetEntry()> has already been called then calling $lj-AddToEntry()> with a null list or a list which starts with undef is a NOP.

Returns 1 on success, 0 otherwise.

Example code:

# Single line entry
$lj->AddToEntry(\%Event,"Some more text")
  || die "$0: Failed to set entry - $LJ::Simple::error\n";

# Three lines of text
my @stuff=(
     "Line 5",
     "Line 6",
     "Line 7",
);
$lj->AddToEntry(\%Event,@stuff)
  || die "$0: Failed to set entry - $LJ::Simple::error\n";

$lj->SetProtectFriends($event)

Sets the current post so that only friends can read the journal entry. Returns 1 on success, 0 otherwise.

Example code:

$lj->SetProtectFriends(\%Event)
  || die "$0: Failed to protect via friends - $LJ::Simple::error\n";

$lj->SetProtectGroups($event,$group1, $group2, ... $groupN)

Takes a list of group names and sets the current entry so that only those groups can read the journal entry. Returns 1 on success, 0 otherwise.

Example code:

$lj->SetProtectGroups(\%Event,"foo","bar")
  || die "$0: Failed to protect via group - $LJ::Simple::error\n";

$lj->SetProtectPrivate($event)

Sets the current post so that the owner of the journal only can read the journal entry. Returns 1 on success, 0 otherwise.

Example code:

$lj->SetProtectPrivate(\%Event)
  || die "$0: Failed to protect via private - $LJ::Simple::error\n";

$lj->Setprop_backdate($event,$onoff)

Used to indicate if the journal entry being written should be back dated or not. Back dated entries do not appear on the friends view of your journal entries. The $onoff value takes either 1 for switching the property on or 0 for switching the property off. Returns 1 on success, 0 on failure.

You will need to set this value if the journal entry you are sending has a date earlier than other entries in your journal.

Example code:

$lj->Setprop_backdate(\%Event,1) ||
  die "$0: Failed to set back date property - $LJ::Simple::error\n";

$lj->Setprop_current_mood($event,$mood)

Used to set the current mood for the journal being written. This takes a string which describes the mood.

It is better to use $lj-SetMood()> as that will automatically use a mood known to the LiveJournal server if it can.