NAME

Net::Lyskom - Perl module used to talk to LysKOM servers.

SYNOPSIS

  use Net::Lyskom;

  $a = Net::Lyskom->new();
  $conf = 6;

  $a->login(pers_no => 437, password => "God", invisible => 1)
    or die "Failed to log in: $a->err_string\n";

  $b = $a->send_message(7680, "Oook!");

  $b = $a->create_text(
                       subject => "Testsubject",
                       body => "A nice and tidy message body.",
                       recpt => [437],
                      );

  if ($b) {
      print "Text number $b created.\n";
  } else {
      print "Text creation failed: $a->err_string.\n";
  }

DESCRIPTION

Net::Lyskom is a module used to talk to LysKOM servers. This far it lacks a lot of functions, but there are enough functions implemented to program statistics robots and such.

Metoder

is_error($code, $err_no, $err_status)

Looks at a response from the server and decides if it is an error message and if that is the case sets some variables in the object and returns true.

Calls die() if the response does not look as a server response at all.

This sub is intended for internal use.

new([options])

Creates a new Net::Lyskom object and connect to a LysKOM server. By default it connects to the server at Lysator (kom.lysator.liu.se, port 4894). To connect to another server, use named arguments.

    $a = Net::Lyskom->new(Host => "kom.csd.uu.se", Port => 4894);

If the connection succeded, an object is returned, if not undef is returned.

getres()

Get responses and asynchronous messages from the server. The asynchronous messages is passed to handle_async(). This method is intended for internal use, and shall normally not be used anywhere else then in this module.

getres_sub()

Helper function to getres(). Be careful and understand what you are up to before using it.

handle_asynch()

Is automaticly called when a asynchronous message is returned from the server. Currently this routine does nothing.

logout

Log out from LysKOM, this call does not disconnect the session, which means you can login again without the need of calling another new.

     $a->logout();

change_conference ($conference)

Changes current conference of the session.

    $a->change_conference(4711);

change_name ($conference, $new_name)

Change name of the person or conference numbered $conference to $new_name.

    $a->change_name(46, 'Sweden (the strange land)');

change_what_i_am_doing ($what_am_i_doing)

Tells the server what the logged-in user is doing. You are encouraged to use this call creatively.

    $a->change_what_i_am_doing('Eating smorgasbord');

set_priv_bits($person, admin => 1, wheel => 1, statistic => 1, create_pers => 1, create_conf => 1, change_name => 1)

Set the privbits on person $person. User can specify one or more privileges by name. Privs not specified default to false.

set_passwd(person => $person, old_pwd => $old, new_pwd => $new)

Changes the password of $person to $new_pwd.

$old is the password of the currently logged in person. All three arguments are required.

delete_conf($conf)

Deletes the conference with number $conf. If $conf is a mailbox, the corresponding user is also deleted.

    $a->delete_conf(42);

sub_member($conf_no, $pers_no)

Removes the person $pers_no from the membership list of conference $conf_no.

    $a->sub_member(42,4711);

set_presentation($conf_no, $text_no)

Set the text $text_no as presentation for $conf_no. To remove a presentation, use $text_no = 0

    $a->set_presentation(42,4711);

set_etc_motd($conf_no, $text_no)

Sets the messages of the day on the conference or person $conf_no to $text_no and removes the old message.

    $a->set_etc_motd(6,1);

set_supervisor($conf_no, $admin)

Set person/conference $admin as supervisor for the conference $conf_no

set_permitted_submitters($conf_no, $perm_sub)

Set $perm_sub as permitted subscribers for $conf_no. If $perm_sub = 0, all users are welcome to write in the conference.

set_super_conf($conf_no, $super_conf)

Sets the conference $super_conf as super conference for $conf_no

set_garb_nice($conf_no, $nice)

Sets the garb time for the conference $conf_no to $nice days.

    $a->set_garb_nice(42,7);

get_text(text => $text, start_char => $start, end_char => $end)

Get a text from the server, the first argument, text, is the global text number for the text to get. The retrival stars at position start_char (the first character in the text is numbered 0) and ends at position end_char.

Default is 0 for start_char and 2147483647 for end_char. This means that a complete message is fetched, unless otherwise stated.

Also note that you can get an entire text, pre-split into subject and body, via the object returned from the get_text_stat method.

To get the first 100 chars from text 4711:

    my $text = $a->get_text(text => 4711, start_char => 0, end_char => 100);

delete_text($text)

Deletes the text with the global text number $text from the database.

add_recipient(text_no => $text, conf_no => $conf, type => $type)

Add a recipient to a text. $type can be one of "recpt", "cc" or "bcc". If not given (or if set to something other than one of those three strings) it defaults to "recpt". text_no and conf_no are required.

sub_recipient($text_no, $conf_no)

Remove a recipient from a text.

add_comment($text_no, $comment_to)

Add a comment link between the text comment-to and the text text-no (text-no becomes a comment to the text comment-to). This call is used to add comment links after a text has been created.

get_time

Ask the server for the current time. Returns a Net::Lyskom::Time object.

set_unread($conf_no, $no_of_unread)

Only read the $no_of_unread texts in the conference $conf_no.

set_motd_of_lyskom($text_no)

Sets the login message of LysKOM, can only be executed by a privileged person, with the proper privileges enabled.

enable($level)

Sets the security level for the current session to $level.

sync_kom

This call instructs the LysKOM server to make sure the permanent copy of its databas is current. This call is privileged in most implementations.

    $a->sync_kom();

shutdown_kom($exit_val)

Instructs the server to save all data and shut down. The variable $exit_val is currently not used.

get_person_stat($persno)

Get status for a person from the server. Returns a Net::Lyskom::Person object.

get_unread_confs($pers_no)

Get a list of conference numbers in which the person $pers_no may have unread texts.

    my @unread_confs = $a->get_unread_confs(7);

send_message($recipient, $message)

Sends the message $message to all members of $recipient that is currently logged in. If $recipient is 0, the message is sent to all sessions that are logged in.

who_am_i

Get the session number of the current session.

    my $session_number = $a->who_am_i();

get_last_text($time)

$time should be given a as a unix time_t (that is, as the number of seconds since 00:00:00 01 Jan 1970 UCT).

find_next_text_no($text_no)

Returns the global number of the readable text that follows the text $text_no.

find_previous_text_no($text_no)

Returns the global number of the readable text that precedes the text $text_no.

login(pers_no => $pers, password => $pwd, invisible => $invis)

Log in to LysKOM. $persno is the number of the person which is to be logged in. $pwd is the password of that person. If $invis is true, a secret login is done (the session is not visible in who-is-on-lists et al.)

set_client_version($client_name, $client_version)

Tells the server that this is the software $client_name and the version $client_version.

    $a->set_client_version('My-cool-software','0.001 beta');

get_client_name($session)

Ask the server for the name of the client software logged in with session number $session.

get_client_version($session)

Ask the server for the version of the client software logged in with session number $session.

get_version_info

Ask the server for the version info of the server software itself. Returns a three-element array with the protocol version, server software name and server software version.

lookup_z_name(name => $name, want_pers => $wp, want_conf => $wc)

Lookup the name $name in the server, returns a list of all matching conferences and/or persons, in the form of Net::Lyskom::ConfZInfo objects. The server database is searched with standard kom name expansion.

If $want_pers is true, the server includes persons in the answer, if $want_conf is true, conferences is included.

re_z_lookup(name => $name, want_pers => $wp, want_conf => $wc)

Regexp lookup of the name $name in the server, returns a list of all matching conferences and/or persons, in the form of Net::Lyskom::ConfZInfo objects.

If $want_pers is true, the server includes persons in the answer, if $want_conf is true, conferences is included.

user_active

Tells the server that the user is active.

who_is_on_dynamic(want_visible => $wv, want_invisible => $wi, active_last => $al)

Returns a list of Net::Lyskom::DynamicSession objects. If want_visible is true, the visible users are included in the answer. If want_invisible is true, invisible users are included.

Only the users active the last active_last seconds are included in the answer. If active_last is zero, all users (who match the visibility limits) are returned.

If not given, want_visible defaults to true, want_invisible defaults to false and active_last defaults to 0.

get_static_session_info($session_no)

Returns a Net::Lyskom::StaticSession object holding details on the specified session.

create_text(subject => "This is the subject", body => "This is the text body.", recpt => [6], cc_recpt => [437], bcc_recpt => [19, 23], comm_to => [4711], footn_to => [11147], aux => [@aux_obj_list])

Creates texts. Takes arguments as indicated in the synopsis just above (that is, as a hash with zero or more of the given keys and strings or arrayrefs as values, as appropriate). Any of the arguments can be left out, but a text without at least one recipient is not very useful (nor is one with neither subject nor body). The aux argument should be a reference to a list of Net::Lyskom::AuxInfo objects.

If the aux list is not given, or given but not containing a content-type item, an item with content type text/x-kom-basic;charset=utf-8 will be added. In this case, the subject and body will also be converted from Perl's internal encoding to UTF-8 before being sent out over the network.

Example:

  $k->create_text(
                  subject => "Test",
                  body => "Body",
                  recpt => [437],
                  aux => [
                          Net::Lyskom::AuxItem->new(
                                                    tag => content_type,
                                                    data => "text/plain"
                                                   )
                         ]);

get_text_stat($textno)

Fetch the status for a text from the server. Returns a Net::Lyskom::TextStat object.

get_conf_stat(@conf_no)

Get status for one or more conferences from the server. Returns a Net::Lyskom::Conference object in scalar context and a list of such objects in list context.

modify_text_info( text => $text, delete => $delete_array_ref, add => $add_array_ref)

Add and/or delete aux items to/from a text. delete should be a reference to an array of aux_info order numbers to remove from the text. add should be a reference to an array of Net::Lyskom::AuxInfo objects to add to the text.

butt_ugly_fast_reply($text, $data)

Adds a fast-reply auxitem with the contents $data to the text $text. Now implemented in terms of modify_text_info, name retained for backwards compatibility.

query_predefined_aux_items

Ask the server which predefined aux items that exists in the server.

get_membership(person => $p, first => $f, no_of_confs => $no, want_read_texts => $w)

Get a membership list for person, in the form of a list of Net::Lyskom::Membership objects. Start at position first in the membership list and get no_of_confs conferences. If want_read_texts is true the server will also send information about read texts in the conference.

local_to_global(conf => $conf, first => $first, number => $no)

Given a local text number and an integer smaller than 256, returns a Net::Lyskom::TextMapping object detailing the mapping between the local and global text numbers of up to that many texts. All arguments are required.

map_created_texts(pers_no => $pers, first => $first, number => $no)

Given a local text number and an integer smaller than 256, returns a Net::Lyskom::TextMapping object detailing the mapping between texts written by pers_no and global text numbers of up to that many texts. All arguments are required.

set_membership_type(pers => $p, conf => $c, invitation => $i, passive => $pa, secret => $s)

Set the membership flags for user pers in conference conf.

get_members(conf => $conf_no, first => $first_index, $count => $no_of_members)

add_member(conf => $conf, pers => $pers_no, priority => $prio, where => $where, invitation => $invite, passive => $pass, secret => $secret)

Add person number pers as a member of conference number conf, at priority priority and at position where. invitation, passive and secret specify the membership type.

query_read_texts($pers, $conf)

Return information on which texts person $pers has read in conference $conf. Returns an Net::Lyskom::Membership object.

set_expire($conf, $expire)

Set the garb-nice value for conference $conf to $expire.

mark_text($text, $mark)

Sets a mark of (numerical) type $mark on text number $text.

get_marks

Returns an array of (text_no, mark_type) pairs, showing the texts the current user has marked.

unmark_text($text)

Remove any marks on the specified text.

set_last_read($conf,$local_no)

Tell the server that the current user has read everything up to local number $local_no in conference number $conf.

set_conf_type(conf => $conf, rd_prot => $rp, original => $orig, secret => $sec, letterbox => $letter, allow_anonymous => $anon, forbid_secret => $nosecret)

Set the type of conference conf. conf is required, the rest default to false if not specified.

mark_as_read($conf, @texts)

Marks the texts specified by the local text numbers in @texts as read in the conference $conf.

sub_comment($text, $comment)

Removes $text from $comments list of comments.

add_footnote($text, $footnote_to)

Makes text number $text be a footnote to text number $footnote_to.

sub_footnote($text, $footnote_to)

Makes text number $text not be a footnote to text number $footnote_to.

disconnect($session)

Make session number $session lose its connection with the server, given sufficient privilege. Session zero is always interpreted as the current session.

set_user_area($pers_no, $text_no)

Make text number $text_no be the user area for user number $pers_no.

get_uconf_stat($conf)

Get a subset of all information for conference number $conf. Returns a Net::Lyskom::Conference object with only some fields filled.

set_info(conf_pres_conf => $cpc, pers_pres_conf => $ppc, motd_conf => $mc, kom_news_conf => $knc, motd_of_lyskom => $mol)

Sets server information.

accept_async(@call_numbers)

Tell the server to send the asynchronous calls with the numbers specified in @call_numbers.

query_async

Ask server which asynchronous calls are turned on for this session. Returns a list of integers.

get_collate_table

Get the active collate table from the server.

create_anonymous_text(...arguments...)

Exactly the same as create_text, except that it uses the call to create the text anonymously.

create_conf(name => $name, rd_prot => $rp, original => $orig, secret => $sec, letterbox => $letter, allow_anonymous => $anon, forbid_secret => $nosecret, aux => $aux_array_ref)

Create a conference.

create_person(name => $name, password => $pwd, unread_is_secret => $uis, aux => $aux_array_ref)

Create a person.

modify_conf_info(conf => $conf, delete => $del_array_ref, add => $add_array_ref)

Delete and/or add aux items to a conference. $del_array_ref is a reference to an array of aux item numbers to delete. $add_array_ref is a reference to an array of aux items to add.

modify_system_info(delete => $del_array_ref, add => $add_array_ref)

Add and/or delete aux items for the server itself. Similar arguments as above.

set_keep_commented($conf, $keep)

Set the keep_commented field for conference number $conf to $keep.

set_pers_flags(person => $pers, unread_is_secret => $uis)

Set the personal flags for person number person. At the moment there is only one such flag, but this method uses the many-args calling convention for ease of future expansion.

get_info

Get the server info. Returns a Net::Lyskom::Info object.

AUTHORS

Calle Dybedahl <calle@lysator.liu.se>

Erik S-O Johansson <fl@erp.nu>

Hans Persson <unicorn@lysator.liu.se>

SEE ALSO

Net::Lyskom::AuxItem, Net::Lyskom::ConfZInfo, Net::Lyskom::Conference, Net::Lyskom::Membership, Net::Lyskom::Object, Net::Lyskom::Person, Net::Lyskom::TextMapping, Net::Lyskom::Time, Net::Lyskom::Util