iface2 is the second iteration of the sBNC interface, which provides an interface for external applications to interact with sBNC. A popular example is a webinterface to give users access to their sBNC accounts via a web page.
The interface can be accessed via the same port on which sBNC accepts IRC client connections, i.e. the system.port defined in sbnc.conf.
To initialize an iface2 session the first command send has to be RPC_IFACE, to which iface2 will reply RPC_IFACE_OK. Since revsion 1138 it is possible to set a password for iface2 initialization via /sbnc globalset iface2initpass. If this password is set it needs to be provided as parameter to the RPC_IFACE command, e.g. RPC_IFACE foobar. Failure to do so will result in the RPC_INVALIDINITPASS reply and connection termination. If there is no reply at all being received it is highly likely that either the TCL module has not been loaded or that the iface2.tcl script was not sourced.
Every subsequent iface2 call requires a valid user account and its password to be provided. They have the following syntax: {(user)(password)(command){}}
These calls consist of itype-arrays (enclosed by braces) and itype-strings (enclosed by parenthesis). As one can see an iface2 call is itself an itype-array consisting of three itype-strings and an itype-array. The first itype-string is the user which executes the iface2 call, the second itype-string is this users password and the third itype-string is the command to be executed. The itype-array at the end provides the (optional) arguments for the command call.
Example, with user river and password firefly:
> RPC_IFACE
RPC_IFACE_OK
> {(river)(firefly)(commands){}}
{(commands)(params)(overrides)(modules)(multicall)(addtrustedip)(removetrustedip)(gettrustedips)(istrustedip)(null)(raw)(getisupport)(getusercount)(getchanprefix)(getnick)(getvalue)(gettag)(getnetwork)(getchannels)(getuptimehr)(gettraffic)(getchanmodes)(gettopic)(getchanlist)(jump)(setvalue)(getlog)(getloglines)(eraselog)(simul)(hasmodule)(hascommand)(setlanguage)(getversion)(tcl)(getuserlist)(getmainlog)(getmainloglines)(erasemainlog)(adduser)(deluser)(admin)(unadmin)(setident)(suspend)(unsuspend)(globalmsg)(killuser)(disconnectuser)(rehash)(getglobaltag)(setglobaltag)(getglobaltags)(gethosts)(addhost)(delhost)(sendmessage)}
> {(river)(firefly)(getusercount){(#sbnc)}}
(81)
The first call initializes the iface2 session.
The second call executes commands, a command without arguments, provided by iface2.tcl. It returns an itype-array of itype-strings listing all commands currently registered with iface2.
The third call executes the getusercount command, provided by ifacecmds.tcl. It requires a channel to be provided as itype-string in the argument itype-array of the iface2 call. The getusercount command returns an itype-string describing the number of users in the channel provided by the command argument.
To provide additional iface2 commands via TCL, these have to be registered with iface2. This happens by calling the registerifacecmd command:
registerifacecmd module command proc ?accessproc? ?paramcount?
The module parameter specifies which module the new command belongs to. By creating commands in a new module it is possible to override the commands in the core module, provided by ifacecmds.tcl. The overriding command has to have the same parameter count as the command to be overridden. One could e.g. register a command called getusercount (see previous section) with one parameter in a new module called e.g. override_module. Calling getusercount via iface2 will then refer to getusercount in the override_module. Calling the iface2 command modules will return an itype-array consisting of itype-strings listing the modules currently provided by iface2.
The command parameter is the name of the new command.
The proc parameter specifies the TCL proc which handles the new iface2 command. It is required that any possible return values of this proc are an itype (see itypes section).
The ?accessproc? parameter is optional and can specify an access-proc. This proc has to accept an sBNC user as parameter, it has to return 1 when the user is allowed to use the iface2 command and 0 otherwise. Two basic access-procs are provided by iface2.tcl: access:anyone (which returns 1 for every user) and access:admin (which returns 1 only if the user is an admin and 0 otherwise). If no access-proc is specified the access-proc defaults to access:anyone.
The ?paramcount? parameter is optional and only relevant if you provide a TCL command instead of a proc in the second parameter. In this case you have to specify the number of parameters this command accepts.
There are three itypes: itype-string, itype-array and itype-exception.
itype-strings can be created by invoking the TCL command itype_string value, provided by itype.tcl.
% itype_string "foo" (foo)
itype-arrays can created in several ways, all of which are provided by itype.tcl. Invoking itype_list_strings value will create an array consisting of strings, each of which contain one element of the TCL list provided in value. Invoking itype_list_strings_args args will create an itype-array consisting of itype-strings, each of which has the value of an argument provided in args. Finally it is possible to create an itype-array incrementally by invoking itype_list_create, itype_list_insert and itype_list_end.
% itype_list_strings "foo bar"
{(foo)(bar)}
% itype_list_stings_args "foo bar" narf
{(foo bar)(narf)}
% set incremental_array [itype_list_create]
{
% itype_list_insert incremental_array [itype_string "foo bar"]
{(foo bar)
% itype_list_insert incremental_array [itype_list_strings "narf"]
{(foo bar){(narf)}
& itype_list_end incremental_array
{(foo bar){(narf)}}
itype-exceptions can be created by invoking itype_exception value, provided by itype.tcl. This type is used to return exceptions from your proc.
% itype_exception "Access denied." [Access denied.]
Alternatively one can invoke the TCL command return -code error “Error code” to return an error from the proc.
TCL script:
proc iface-samplecommand {argument} { if {$argument == "version"} { return [itype_string $::version] } elseif {$argument == "usercount"} { return [itype_string [llength [bncuserlist]]] } else { return [itype_exception "Parameter unkown, possible parameters are \"version\" and \"usercount\"."] } } registerifacecmd "sample_module" "samplecommand" "iface-samplecommand" "access:anyone"
And corresponding iface2 calls:
> RPC_IFACE
RPC_IFACE_OK
> {(river)(firefly)(samplecommand){(version)}}
(1.3alpha14 $Revision: 1134 $)
> {(river)(firefly)(samplecommand){(usercount)}}
(37)
> {(river)(firefly)(samplecommand){(foo)}}
[Parameter unkown, possible parameters are "version" and "usercount".]