BK::Backend - The API for Bummskraut backends to communicate with the core

0.1

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

The constructor constructs the backend handle $obj and connects to the Bummskraut core.

$obj->lerr ($fmt, @args)

$obj->lwrn ($fmt, @args)

$obj->lnfo ($fmt, @args)

$obj->ldbg ($lvl, $fmt, @args)

$obj->ilerr ($id, $fmt, @args)

$obj->ilwrn ($id, $fmt, @args)

$obj->ilnfo ($id, $fmt, @args)

$obj->ildbg ($lvl, $id, $fmt, @args)

Logging functions for the backend implementations. Will place the logging message in the right backend context.

The i... functions take an additional argument, the $id, which is the buffer/context ID where the log message will be logged in.

For description of the arguments see BK::Log.

$obj->set_commands (%cmds)

This method sets the protocol specific frontend commands. The hash keys of %cmds contains the command name (the part usually after the /) and the values are hash references should contain following keys:

arg_map => $code

This sets the mapping of the argument string in the client to the actual RPC call arguments. The argument the user types if available in the variable $arg and the RPC arguments should be put into the array reference in $args.

cmd_cb => $callback->($obj, $reply->($rid, $errfmt, @errargs), $alias, $dest, @args)

This is the callback that will be called in the backend when the this command is invoked in the context of the alias $alias and destination $dest.

The result of the call should be displayed by sending messages to a specific context/buffer $rid. That ID should be passed to the $reply callback to signal the client where the response of his command is displayed in.

You are free to not call $reply at all if you don't want to redirect the user.

In case you want to signal an error pass $errfmt and @errargs to the $reply callback and pass undef as $rid. It will use $errfmt and @errargs as arguments to a sprintf and print the message in the appropriate error log and redirect the user there.

The arguments you did put into the $args array reference in the arg_map code above will be passed to $callback in @args.

help => $text

This should be a descriptive text about what the command does and how it's arguments are interpreted.

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

This function sets the presence for the ID $id. $presence should be one of these values:

   available
   chat
   away
   xa
   dnd
   unavailable

$description should be the human readable presence string (like "I'm out for coffee").

$obj->presence_by_prefix ($pref => $presence, $description)

This method sets the presence for all matching IDs which have been assigned a presence via the presence method before. An ID is matched by the prefix $pref.

my ($presence, $desc) = $obj->own_presence;

This method returns the presence status that the user configured he wants to have.

$obj->add_members ($id, $new_members)

$obj->remove_members ($id, [$removed_members])

These methods are for adding and removing members from the member list of a context/buffer/id. If $removed_members is undefined all members are removed from the id.

$new_members and $removed_members should just be array references containing the nicknames for the occupants.

$obj->remove_members_by_prefix ($pref)

This method removes all members from the IDs with the prefix $pref.

$obj->update_roster ($updates)

$updates should be a hash reference. The keys are the IDs for which the roster entry should be updated. The values are array references that should contain this:

   [$nick, $groups, $subscription]

Where $nick is the nickname. $groups an array references of groups that the user belongs to. $subscription be his subscription state (mostly like in XMPP: to, from, both, none).

$obj->remove_roster ($ids)

Removes the IDs in the array reference $ids from the roster.

$obj->remove_roster_by_prefix ($prefix)

This will remove any previously updated roster items identified by their IDs that match the $prefix from the roster.

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

This method sends the message $msg in the context/buffer $id. $msg should be a hash reference which has these well known keys:

timestamp => $time

$time should contain the UNIX timestamp of the time this message was generated (eg. typed in by the user). If the message doesn't have a timestamp attached it will automatically get one.

content => $message

$message should contain the actual contents of the message. (the text the user typed in).

src_nick => $nick

$nick should contain the source nickname of this message. (eg. the nickname of the user who sent the message).

scope => $scope

$scope is the scope of the message. Which can be either private in case of one-to-one communications or public in case of one-to-many communications. It usually just changes how the message is displayed later.

There is a special exception when type (see below) is log. In that case $scope is one of the defined logging message levels defined in BK::Log.

type => $type

$type describes the type of the message. Which can be one of these values:

normal

For normal and usual chat messages between people.

meta

Meta messages, describing that something related to the chat context has changed (for instance that the topic of an IRC channel has been changed, or that someone's mode was changed).

join

This message type represents a join message. Please note that this is just the join message that will be displayed in the client, and will not lead to any state changes (or update completion in the client).

part

This message type represents a part message. Please note that this is just the part message that will be displayed in the client, and will not lead to any state changes (or update completion in the client).

log

This is a special type for logging messages. The log message levels which are defined in BK::Log are specified over the scope key explained above.

is_echo => $bool

If the message is the echo of your self (meaning: it's a message written by you in the frontend) you should set this flag. It will display the message as if it is an echo.

highlight => $lvl

This flag describes whether this message should lead to a highlight. $lvl should contain the actual level of the highlight.

The highest currently defined level is 1, which is usually used for highlights that result from someone using your nickname in a message.

The next lower level is -1 which is usually used when a highlight from general activity in some context/buffer is generated.

The next lower level then is -2 which is used usually for non-urgent highlights, like new RSS/Atom feed entries.

Other levels might be used/provided in futurue.

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

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

my $s = $obj->state

Returns the state that the core stored for us. You can update the state via the update_state method (see below).

$obj->update_state ($new_state)

Updates the state that the core stores for us.

my $bool = $obj->check_highlight ($msg)

This method checks the string $msg for any of the globally configured highlight patterns.

connected

killed => $reason

message => $alias, $dest, $type, $msg

Emitted when a message from a frontend was received. $alias is the alias part of an ID. $dest is the destination part of an ID. $type is the message type, of which currently following exist:

   normal
   action
   notice

(See also type field for messages sent by send_msg)

$msg is the actual text content of the message.

update_config

Emitted whenever a new configuration is received. Use the config method to access it.

update_own_presence => $presence, $description

This event is emitted when new information arrives about the desired user presence.

$presence and $description can also be retrieved via the own_presence method.

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.