The on BAN and on UNBAN events trigger when a user on a channel is banned or unbanned.
Format: on <level>:BAN:<#[,#]>:<commands>
Example: on 1:BAN:#mirc,#irchelp:/msg $nick Sorry but you're not allowed on $chan
on 9:BAN:#newbies:/mode $chan -o $nick | /mode $chan -b $banmask
This triggers when someone bans a user with access level 9. The nick who did the banning is de-opped and the banmask is set again. $banmask refers to the banmask used to ban the user.
on 1:UNBAN:#:/msg $bnick You have just been unbanned
This triggers when any user is unbanned from any channel. $bnick refers to the banned users nickname, however this would actually only be filled if the banmask itself includes a nickname. If the banmask does not include a nickname, $bnick is $null.
Remember that $banmask is usually a wildcard string which means that it will be matching wildcard strings in your remote users section. For example, if someone sets a ban of *!k*d@*.com it will match users:
You can compare the levels of the banner and the banned by prefixing the line with <,>,<=,=>,<>, or =, in the following way:
on >=2:BAN:#mIRC:/msg $chan $nick banned $banmask (legal)
on 1:BAN:#mIRC:/msg $chan $nick banned $banmask (illegal)
In this situation, if the banners level is larger than or equal to the banned users level, then it is a legal ban. Otherwise, it defaults to the second ON BAN line which indicates that it is an illegal ban. Remember, this is comparing the banners and banned users levels and has nothing to do with the level 2 in the definition.
Note: These events only work on nicknames because the IRC server only sends the nickname of the user being banned/unbanned and not an address. Also, IP addresses will not be matched against named addresses, and banmasks ending in @* will be ignored since this can match almost any user address.