diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/PERL | 491 | ||||
| -rw-r--r-- | docs/SIGNALS | 218 |
3 files changed, 711 insertions, 0 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index ac39dcc4..c2d6f6c2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -2,6 +2,8 @@ EXTRA_DIST = \ FAQ \ COMMANDS \ FORMATS \ + PERL \ + SIGNALS \ botnet.txt SUBDIRS = help diff --git a/docs/PERL b/docs/PERL new file mode 100644 index 00000000..9a03e589 --- /dev/null +++ b/docs/PERL @@ -0,0 +1,491 @@ + + Functions that you can use in Irssi's Perl scripts + -------------------------------------------------- + +This is just my very first implementation and things will probably change. + +Commands marked with (!!) mean that you shouldn't use it unless you +know what you're doing.. + +If there's a "Xxxx::" text before the command, it means that it belongs to +that package. Like "Server::command" means that you should either call it as + Irssi::Server::command($server, $cmd); +or more easily: + $server->command($cmd); + +Commands that don't have the Xxxx prefix are called as Irssi::command(); + +A list of signals that irssi send can be found from SIGNALS file. + + + *** General + +Channel cur_channel() - return current channel +Server cur_server() - return current server + +channels() - return list of all channels +servers() - return list of all servers +commands() - return list of all commands +dccs() - return list of all dcc connections +logs() - return list of all log files +plugins() - return list of all plugins + +print(str) + Print `str' to current window as "Irssi notice". + +command(cmd, [Server server, [Channel channel]]) + Send a command `cmd' (in current channel). This will work just as if you + had typed `cmd' in command line, so you'll need to use /COMMANDS or the + text will be sent to the channel. + +Server::command(cmd, [Channel channel]) + Just like above, except different calling method. + +Channel::command(cmd) + Just like above, except different calling method. + +Server::printtext(channel, level, str) + Print `str'. + + + *** Message levels + +level2bits(level) + Level string -> number + +bits2level(bits) + Level number -> string + +combine_level(level, str) + Combine level number to level string ("+level -level"). + Return new level number. + + + *** Signals / timeouts + +signal_emit(signal, ...) + Send signal `signal' + +signal_add(signal, func) + Bind `signal' to function `func' + +signal_remove(signal, func) + Unbind `signal' from function `func' + +tag timeout_add(msecs, func, data) + Call `func' every `msecs' milliseconds (1000 = 1 second) with + parameter `data'. Returns tag which can be used to stop the timeout. + +timeout_remove(tag) + Remove timeout with tag. + + + *** Commands + +Command::values() + Get some information about command. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "cmd" - Command + "category" - Category + +command_bind(cmd, category, func) + Bind command `cmd' to call function `func'. `category' is the + category where the command is displayed in /HELP. + +command_unbind(cmd, func) + Unbind command `cmd' from function 'func. + +Server::command_split(cmd, arg, max_nicks) + Split the `cmd' into several commands so `arg' argument has only + `max_nicks' number of nicks. + + Example: $server->command_split("KICK nick1,nick2,nick3 :byebye", 1, 2); + Irssi will send commands "KICK nick1,nick2 :byebye" and + "KICK nick3 :byebye" to server. + + + *** Server functions + +Server::values() + Get some information about server. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "address" - Address where we connected (irc.blah.org) + "real_address" - Who the server thinks it is (irc1.blah.org) + "port" - Port where we connected + "tag" - Unique server tag. + "ircnet" - IRC network + "password" - Password we used in connection. + + "nick" - Current nick + "wanted_nick" - Nick which we would prefer to use + "username" - User name + "realname" - Real name + "usermode" - Current user mode + "connected" - Is connection finished? 1|0 + "connection_lost" - Did we lose the connection (1) or was + the connection meant to be disconnected (0) + Example: + %server_info = %{$Irssi::cur_server->values()}; + Irssi::print("Current server = ".$server_info{'address'}); + +Server server_connect(address, [port=6667, [password='', [nick='']]]) + Create new server connection. + +Server::disconnect() + Disconnect from server. + +Server server_find_tag(tag) + Find server with tag + +Server server_find_ircnet(ircnet) + Find first server that is in `ircnet' + +Channel channel_find_any(channel) + Find `channel' from any server + +Server::send_raw(cmd) + Send raw message to server, it will be flood protected so you + don't need to worry about it. + +Server::ctcp_send_reply(data) + Send CTCP reply. This will be "CTCP flood protected" so if there's too + many CTCP requests in buffer, this reply might not get sent. + + + *** Server redirections + +WARNING: It's easy to mess up the Irssi's internal server expectations with +these commands! + +This is a powerful feature of Irssi that I can't seen in other IRC clients. +You can EASILY grab the server's reply for a command you send to server +without any horrible kludges. + +Server::redirect_init(command, last, ...) + Initialize redirection for specified command. This needs to be done only + once. Irssi already initializes commands "WHOIS", "WHO", "LIST" and "ISON". + `command' is the whole name of the signal, like "command whois". + `last' specifies how many of the items in `...' is considered as the + "last event" from the command. + + Example: $server->redirection_init('command who', + 2, # 2 first events will finish the command + 'event 401', # unknown nick (finished) + 'event 315', # end of who (finished) + 'event 352'); # who line (wait..) + +Server::redirect_event(arg, last, ...) + Add redirection. `arg' is a space separated list of arguments that should + match before Irssi will redirect the event (think of /WHOIS nick nick and + doing another to different nick immediately after it, there's no way of + knowing which will return first. so, arg would be in this case 'nick'). + + `last' specifies how many of the following events are considered as + "last event" from command - just like in redirect_init(). + + `...' is `event, signal, argpos, ...`, where + `event' is the event we're waiting from server. + `signal' is the signal we will send after receiving the event. It should + always start with 'redir ' so that Irssi's perl handler knows to + send correct arguments to signal handler. + `argpos' is the argument position in event's data or -1 if it + should be ignored. + + Example: + $server->send_raw('WHOIS :cras'); + $server->redirect_event('cras', 2 + "event 318", "redir end_of_whois", -1, + "event 402", "redir no_such_server", -1, + "event 401", "redir no_such_nick", 1, + "event 311", "redir whois", 1, + "event 301", "redir whois_away", 1, + "event 312", "redir whois_server", 1, + "event 313", "redir whois_oper", 1, + "event 317", "redir whois_idle", 1, + "event 319", "redir whois_channels", 1); + In the 402-case we tried "/WHOIS nick nick" but nick didn't exist.. + +group Server::redirect_single_event(arg, last, group, event, signal, argpos) + Same as redirect_event() except you can set it up in pieces. + If `group' is 0, it will create new group and return it's id. + + + *** IRC masks + +irc_mask_match(mask, nick, user, host) + Return 1 if `mask' matches nick!user@host. + +irc_mask_match_address(mask, nick, address) + Return 1 if `mask' matches nick!address. + +irc_masks_match(masks, nick, address) + Return 1 if any mask in the `masks' (string separated with spaces) + matches nick!address. + +irc_get_mask(nick, host, flags) + Create IRC mask from nick!host. + flags = you need to combine these: + (FIXME: export the IRC_xxx defines to perl (or something)) + IRC_MASK_NICK 0x01 + IRC_MASK_USER 0x02 + IRC_MASK_HOST 0x04 + IRC_MASK_DOMAIN 0x08 + + + *** Channels + +Channel::values() + Get some information about channel. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "name" - channel name + "type" - channel type ("channel", "query", "dcc chat", "empty") + +Channel Server::channel_create(channel, type, automatic) + Create new channel with name `channel'. `type' is one of: + (FIXME: export these to perl somehow) + CHANNEL_TYPE_CHANNEL 0 + CHANNEL_TYPE_QUERY 1 + CHANNEL_TYPE_DCC_CHAT 2 + CHANNEL_TYPE_EMPTY 3 + `automatic' means that channel is created "automatically" and + Irssi will NOT change the active window to it. + +Channel::_destroy() + Destroy channel. + +Channel::change_name(name) + Change channel's name + +Channel::get_mode() + Return channel's mode + +Channel Server::channel_find(channel) + Find `channel' in server. + +Channel Server::channel_find_closest(channel, level) + Find `channel' or if not found, some other channel that has + level `level' (number). + +Channel channel_find_level(level) + Find channel with level `level'. + + + *** Channel modes + +Ban::values() + Get some information about ban. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "ban" - The ban + "setby" - Nick of who set the ban + "time" - Timestamp when ban was set + +Ban Channel::ban_add(ban, nick, time) + Add new ban. (!!) + +Channel::ban_remove(ban) + Remove ban. (!!) + +Ban Channel::ban_exception_add(ban, nick, time) + Add ban exception (!!) + +Channel::ban_exception_remove(ban) + Remove ban exception (!!) + +Channel::invitelist_add(mask) + Add invite (!!) + +Channel::invitelist_remove(mask) + Remove invite (!!) + +Channel::modes_parse_channel(setby, modestr) + Parse mode string (!!) + +Channel::ban_get_mask(nick) + Get ban mask for `nick'. + +Channel::modes_set(data, mode) + Set mode `mode' ("+o", "-o", etc.) to all nicks in `data' + separated with spaces. + + + *** Nick list + +Nick::values() + Get some information about nick. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "nick" - Plain nick + "host" - Host (blah@there.org) + "name" - Real name + "op", "voice", "gone", "ircop" - 1 or 0 + "last_check" - timestamp when last checked gone/ircop status. + "send_massjoin" - Waiting to be sent in a "massjoin" signal - 1 or 0 + +Nick Channel::nicklist_insert(nick, op, voice, send_massjoin) + Add nick to nicklist. (!!) + +Channel::nicklist_remove(nick) + Remove nick from nicklist. (!!) + +Nick Channel::nicklist_find(mask) + Find nick from nicklist. + +Channel::nicklist_getnicks(channel) + Return a list of all nicks (Nick packages) in channel. + + + *** DCC + +Dcc:destroy() + Destroy DCC connection. (!!) + +dcc_type2str(type) + DCC type number to string + +dcc_str2type(type) + DCC type string to number + +Dcc dcc_find_item(type, nick, arg) + Find DCC connection. + +Dcc dcc_find_by_port(nick, port) + Find DCC connection by port. + + + *** Netsplits + +Netsplit::values() + Get some information about netsplit. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "nick" - Nick + "address" - Nick's host + "server" - The server nick was in + "destserver" - The other server where split occured. + "destroy" - Timestamp when this record should be destroyed + /*FIXME: add list of channels the nick was in;*/ + +Netsplit Server::netsplit_find(nick, address) + Check if nick!address is on the other side of netsplit. Netsplit records + are automatically removed after 30 minutes (current default).. + +Nick Server::netsplit_find_channel(nick, address, channel) + Find nick record for nick!address in channel `channel'. + + + *** Notify list + +notifylist_add(nick, ircnet) + Add `nick' to notify list in irc network `ircnet' + +Server notifylist_ison(nick, ircnets) + Check if `nick' is in IRC. `ircnets' is a space separated + list of irc networks. If it's empty string, all servers will be checked. + +Server::notifylist_ison_server(nick) + Check if `nick' is on IRC server. + + + *** Rawlog + +Server::rawlog_input(str) + Send `str' to raw log as input text. (!!) + +Server::rawlog_output(str) + Send `str' to raw log as output text. (!!) + +Server::rawlog_redirect(str) + Send `str' to raw log as redirection text. (!!) + + + *** Ignores + +Autoignore::values() + Get some information about autoignore. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "nick" - Ignored nick + "timeleft" - Seconds left to ignore + "level" - Ignoring level number + +ignore_add(mask, level) + Ignore `mask' with level string + +ignore_remove(mask, level) + Unignore level string from `mask' + +Server::ignore_check(nick, host, type) + Return 1 if nick!host is ignored with level number `type'. + +Server::autoignore_add(type, nick) + Autoignore `nick' in server with level number `type'. + +Server::autoignore_remove(mask, level) + Remove autoignoring `nick' from server. `level' is a string. + + + *** Logging + +Log::values() + Get some information about log. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "fname" - Log file name + "autoopen_log" - Automatically open log at startup + "last" - Timestamp when last write occured. + "level" - Global logging level. + /*FIXME: add list of Logitems;*/ + +Logitem::values() + Get some information about logitem. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "name" - Log item name. + "level" - Logging level number. + +Log log_create(fname, data) + Create log file. `data' = logging level ("-all #channel +public") + +Log log_create_with_level(fname, level) + Create log file with level number. + +Log log_file_find(fname) + Find log file. + +Log::destroy() + Destroy log file + +Log::open() + Start logging + +Log::close() + Stop logging + +Log::append_item(name, level) + Append log item with level number `level' to log file. (!!) + +Log::remove_item(log, name) + Remove log item. (!!) + + + *** Plugins + +Plugin::values() + Get some information about plugin. This function returns a reference to + hash table (FIXME: can't it return the hash table itself?!). Hash table + has keys: + "name" - Plugin name + "description" - Plugin description + +plugin_load(name, args) + Load plugin. + +plugin_get_description(name) + Get plugin description string. + +Plugin plugin_find(name) + Find plugin. diff --git a/docs/SIGNALS b/docs/SIGNALS new file mode 100644 index 00000000..715e8ebe --- /dev/null +++ b/docs/SIGNALS @@ -0,0 +1,218 @@ +IRC base +-------- + +* Requires to work properly: + + "gui exit" + "gui channel open", CHANNEL_REC + "send command", char *command, SERVER_REC, CHANNEL_REC + +* Provides signals: + +bans.c: + + "ban new", BAN_REC + "ban remove", BAN_REC + "ban exception new", BAN_REC + "ban exception remove", BAN_REC + "ban type changed", char *bantype + +commands.c: + "commandlist new", COMMAND_REC + "commandlist remove", COMMAND_REC + +channels.c: + + "channel created", CHANNEL_REC + "channel destroyed", CHANNEL_REC + "channel name changed", CHANNEL_REC + "channel topic changed", CHANNEL_REC + "channel server changed", CHANNEL_REC + + "channel query", CHANNEL_REC + "channel wholist", CHANNEL_REC + "channel sync", CHANNEL_REC + +ctcp.c: + + "ctcp msg "<cmd>, char *args, SERVER_REC, char *nick, char *addr, char *target + "default ctcp msg", char *args, SERVER_REC, char *nick, char *addr, char *target + "ctcp reply "<cmd>, char *args, SERVER_REC, char *nick, char *addr, char *target + "default ctcp reply", char *args, SERVER_REC, char *nick, char *addr, char *target + +irc.c: + + "server incoming", SERVER_REC, char *data + + "send command", char *args, SERVER_REC + "command "<cmd>, char *args, SERVER_REC, CHANNEL_REC + "default command", char *args, SERVER_REC, CHANNEL_REC + + "server event", char *data, SERVER_REC, char *sender_nick, char *sender_address + "event "<cmd>, char *args, SERVER_REC, char *sender_nick, char *sender_address + "default event", char *data, SERVER_REC, char *sender_nick, char *sender_address + +(for perl parser..) + "redir "<cmd>, char *args, SERVER_REC, char *sender_nick, char *sender_address + +lag.c: + + "server lag", SERVER_REC + "server lag disconnect", SERVER_REC + "lag", char *server, int lag + +modes.c: + + "invitelist new", CHANNEL_REC, char *mask + "invitelist remove", CHANNEL_REC, char *mask + + "channel mode changed", CHANNEL_REC + "user mode changed", SERVER_REC + "nick mode changed", CHANNEL_REC, NICK_REC + +netsplit.c: + + "netsplit add", NETSPLIT_REC + "netsplit remove", NETSPLIT_REC + +nicklist.c: + + "nicklist new", CHANNEL_REC, NICK_REC + "nicklist remove", CHANNEL_REC, NICK_REC + "nicklist changed", CHANNEL_REC, NICK_REC, char *oldnick + "nick gone changed", CHANNEL_REC, NICK_REC + "nick ircop changed", CHANNEL_REC, NICK_REC + "server nick changed", SERVER_REC + "massjoin", CHANNEL_REC, GList of NICK_RECs + +rawlog.c: + + "rawlog", SERVER_REC, char *data + +server.c: + + "server connect failed", SERVER_REC + "server connected", SERVER_REC + "server connecting", SERVER_REC, ulong *ip + "server looking", SERVER_REC + "server disconnected", SERVER_REC + "event connected", SERVER_REC + +signal.c: + + "signal", char *name, ... + "last signal", char *name, ... + +IRC extra +--------- + +* Requires to work properly: + + "print text stripped", SERVER_REC, char *channel, int level, char *text + "plugin add menu", char *menuitem, void (*func) (gpointer, PLUGIN_REC), PLUGIN_REC + +* Provides signals: + +dcc.c: + + "dcc ctcp "<cmd>, char *args, DCC_REC + "default dcc ctcp", char *args, DCC_REC + "dcc unknown ctcp", char *args, char *sender, char *sendaddr + + "dcc reply "<cmd>, char *args, DCC_REC + "default dcc reply", char *args, DCC_REC + "dcc unknown reply", char *args, char *sender, char *sendaddr + + "dcc chat message", DCC_REC, char *msg + + "dcc created", DCC_REC + "dcc destroyed", DCC_REC + "dcc connected", DCC_REC + "dcc rejecting", DCC_REC + "dcc closed", DCC_REC + "dcc chat message", DCC_REC, char *msg + "dcc transfer update", DCC_REC + "dcc request", DCC_REC + "dcc get receive", DCC_REC + "dcc error connect", DCC_REC + "dcc error file create", DCC_REC, char *filename + "dcc error file not found", char *nick, char *filename + "dcc error get not found", char *nick + "dcc error send exists", char *nick, char *filename + "dcc error unknown type", char *type + "dcc error close not found", char *type, char *nick, char *filename + +flood.c: + + "flood", SERVER_REC, char *nick, char *host, char *level, char *target + +ignore.c: + + "autoignore new", SERVER_REC, AUTOIGNORE_REC + "autoignore remove", SERVER_REC, AUTOIGNORE_REC + "ignore new", LIST_REC + "ignore change", LIST_REC + "ignore remove", LIST_REC + +log.c: + + "log created", LOG_REC + "log destroyed", LOG_REC + "log opened", LOG_REC + "log closed", LOG_REC + "log written", LOG_REC, char *line + "log item created", LOG_REC, LOG_ITEM_REC + "log item destroyed", LOG_REC, LOG_ITEM_REC + +notifylist.c: + + "notifylist new", LIST_REC + "notifylist remove", LIST_REC + "notifylist joined", SERVER_REC, char *nick, char *username, char *host, char *realname + "notifylist left", SERVER_REC, char *nick + +plugins.c: + + "plugin created", PLUGIN_REC + "plugin loaded", PLUGIN_REC + "plugin destroyed", PLUGIN_REC + + "plugin error already loaded", char *plugin + "plugin error invalid", char *plugin + "plugin error load", char *plugin, char *error + "plugin error not loaded", char *plugin + "plugin error version", char *plugin + +UI common +--------- + +* Requires to work properly: + + "gui print text", CHANNEL_REC, int fg, int bg, int flags, char *text + "gui window goto", int number + +* Can be used to determine when all "gui print text"s are sent (not required) + + "print text finished", CHANNEL_REC + +* Provides signals: + +ui-keyboard.c: + + "keyinfo created", KEYINFO_REC + "keyinfo destroyed", KEYINFO_REC + +ui-printtext.c: + + "print text", SERVER_REC, char *channel, int level, char *text + "print text stripped", SERVER_REC, char *channel, int level, char *text + +ui-themes.c: + + "theme created", THEME_REC + "theme destroyed", THEME_REC + +ui-windows.c: + + "window created", WINDOW_REC + "window destroyed", WINDOW_REC |