BK::Client - Bummskraut client API

0.1

my $obj = BK::Client->new (%args)

$obj->start ($interested_states)

This will initialize and start the client. It will then issue connected and killed events whenever it got a connection to a backend or lost it. No further action on your side is required, reconnecting is done automatically.

$interested_states should be an array ref containing all the state names this client is interested in.

$interested_states may contain these states:

   highlights
   presence
   members
   commands
   roster

$obj->invoke_command ($id, $cmd, $arg)

This method will invoke the backend command $cmd for the backend that is responsible for $id. $arg is the argument string, which contains the input which the user typed in.

Any output related to this command will be printed to some specific ID and that ID will be told to you by the command_reply event.

my $txt = $obj->get_command_help ($id, $cmd)

This method returns the help text that belongs to the command $cmd that is provided in the context $id. If $cmd does not exist undef is returned.

$obj->send_msg ($id, $type, $msg)

This will send the message $msg to the backend responsible for the id $id. $type is the message type, which should be normal or action. If $type is undef it defaults to normal.

$obj->list_available_configs ($cb->($configs))

This method will fetch the list of available configurations in the core. $cb will be executed with an array ref containing available configuration names. $configs will be undef if no names could be retrieved, usually due to an error.

$obj->fetch_config ($cfgname, $cb->($config_txt))

This method fetches the configuration for the Bummskraut part $cfgname, which usually is some value like xmpp, irc or for the client frontends client. For a listing use the list_available_configs method.

When the configuration is retrieved $cb will be called with the configuration data structure. The $config_txt argument will contain the text of the configuration file or undef if no such configuration exists.

$obj->fetch_default_config ($cfgname, $cb->($config_txt))

This method fetches the default configuration $cfgname. That is the current version dependent configuration of the corresponding protocol backend or other part of Bummskraut. You can use this method to look at unmodified versions of the configuration, that contains the documentation of the configuration.

The parameters have analogous semantics as the parameters to the fetch_config method above.

$obj->update_config ($cfgname, $config_txt)

This will upload the previously via fetch_config fetched configuration. See also fetch_config above for more details.

$obj->query_backlog ($id, $seq, $num)

This queries the core backend for a chunk of backlog for id $id, starting at sequence number $seq (which can be undefined, which means that the latest messages will be retrieved) BUT not including that sequence number. $num contains the count of messages of backlog that should be retrieved.

The backlog event notifies you about a new chunk of backlog you earlier requested via this method.

$obj->mark_buffer_seen ($id)

This will tell the core that we've seen the buffer/id $id and it is free to clear any pending highlights.

$obj->presence ($presence, $description)

This will set your presence for all protocols. There are these possible values for $presence:

   xa
   dnd
   away
   chat
   available

$description is the human readable status like "Out for coffee!".

($presence, $description) = $obj->presence_id ($id)

This method returns the presence for the ID $id. If no presence is available this method returns no values at all (or undef for $presence and $description).

For possible values of $presence and $description see the presence method above.

my @ids = $obj->roster_ids;

Returns a list of IDs of the roster.

my $item = $obj->roster ($id)

This method returns the roster $item for the ID $id. The $item is either undef in case there is no roster entry for $id (anymore). And otherwise it's a hash reference containing these keys:

nick => $nickname

groups => [$group1, $group2, ...]

subscription => 'to' | 'from' | 'none' | 'both'

$obj->latency_measurements ($enable)

This will enable (or disable, depending on the trueness of $enable) latency measurements of the connection to the core backend. Latency updates will be given to you via the latency event.

$obj->config ($section, $subsection, ...)

This method allows you to access the client configuration. The arguments are just for convenience of accessing the configuration hash data structure.

connected

Emitted when we connected and synchronized with the initial states successfully. Be prepared to get state update events before this event.

killed => $reason

Emitted when the client connection to the core has been interrupted. Some human readable reason can be found in $reason.

message => $id, $seq, $msg

Emitted when we received a new message. $id is the source ID, $seq it's sequence and $msg the message.

backlog => $id, $bl

This event is emitted when a chunk of backlog was received. $id is the ID the backlog belongs to. $bl is an array containing the chunk of messages. Each entry consists of the sequence of the message and the message itself as second element.

latency => $secs

This event tells you your new value of latency to the core backend. If $secs is undefined it means that the connection was probably interrupted.

update_commands => $proto, $commands

This event updates the commands list that is available for the protocol $proto. $commands is an array reference containing the commands as list of strings.

command_reply => $id, $cmd, $src_id

This event is emitted when command output is presented in the ID $id. You should usually redirect the user to $id.

$cmd is the command that resulted in this redirection and $src_id is the ID where you executed the command.

update_highlights => $hl_map

This will be emitted when the highlights have changed. $hl_map is a hash reference that contains the buffer IDs where the highlights are as keys and an array reference for each highlight with these contents:

   [$seq, $lvl, $time]

The $seq is the message sequence of the message that highlighted the corresponding ID. $lvl is the level of the highlight. The higher the number in $lvl the more important the highlight is. $time is the UNIX timestamp for the time when the highlight happened.

add_members => $id, $members

This event is called whenever a member is added to the context $id. $members is an array reference of strings which contain the members nicknames.

Please note that you should not use this event for making join/part messages, they are sent separately/explicitly by the protocol backends.

remove_members => $id, [$members]

This event is emitted when either all members ($members is undef) should be removed from the id $id or when specific members should be removed.

Please note that you should not use this event for making join/part messages, they are sent separately/explicitly by the protocol backends.

These events are usually good for maintaining lists of channel members or for example for updating the input line completion.

update_presences => $ids

This event is emitted when the presence for the ids in the array reference $ids changes. Use the presence_id method to fetch the current presence status for each id.

update_client_config

This event is emitted whenever the client configuration has changed. Please use the config method for accessing the client configuration.

update_own_presence => $presence, $description

This event is emitted whenever a presence update of you self has been received. $presence and $description have the same semantics and values as the parameters to presence.

update_roster => $ids

Emitted whenever a roster update arrives and the IDs listed in the array reference in $ids were updated in some way. Use the roster method to access the roster items.

Robin Redeker, <elmex@ta-sa.org>

Copyright 2009 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.