Revision as of 12:47, 23 June 2014

Signals are a simple way of triggering signal events in multiple scripts at the same time. Once set up to listen for the signal event, either directly or indirectly (using a * wildcard), your scripts can each perform their own duties based on the signal you've provided.

Signal Command

Signals have a very simple syntax:

/signal [-n] <name> [parameters]

Flags

-n: This flag tells the /signal command to fire immediately, rather than wait for all other listening scripts to finish executing their events.

Examples

Let's check out an example of a signal command below:

/signal mysignal Signal information!

Once you've executed this command, it will send a signal named mysignal to all scripts in your mIRC remotes. Any script files that have signal event listeners listening for the event will trigger, and perform whatever tasks they have been set to perform.

How do the other scripts listen for a signal event? That's a great question, which brings us to our next section regarding these listeners.

Signal Event Listener

ON *:SIGNAL:name:command

Note: The script that called /signal is triggered first, and then all other scripts are triggered.

Parameters

nameA unique name given to your signal which is usually related to its purpose.

commandThis is a command, or a set of commands, which can be executed when the signal event is triggered.

You can also specify a wildcard within the signal name. For example, review the following:

ON *:SIGNAL:*nick:echo -a I just got a signal from $signal $+ !

The above code will listen for any signals that end in nick. Let's take a look at a basic command to trigger this signal event:

/signal endsIn-nick Here is some info!

The signal event we are listening for triggers on this command because the signal name we've given /signal ends in nick. Below is the result of executing the above signal:

I just got a signal from bestSignal!

Identifiers

$signalReturns the signal name of the signal which triggered the current event.

$1-Returns any optional parameters that have been passed along with the signal.

Example Script

Now that we know some basic data that can be obtained from a signal, as well as how to trigger a signal and listen for a signal, let's create a signal and an event that puts these signals to good use!

Useful Scenario

First, we need to think of something that would make a signal useful. Although signals are useful in simple scenarios, more difficult scenarios can truly pinpoint just how useful these signals can be. How about delaying an auto join script until after your auto identifier script has identified you to a network's NickServ? Let's get into some details.

Some networks allow users to have their own, personalized virtual hosts, which change their host masks to any vanity they would like. Host masks are in the form username@their.isp.address.net. If you've ever performed a /whois on a nickname on an IRC network, this will look familiar. What a vHost will do, when a network offers and or provides you with one, is they mask your true host, and usually they can be vanity, meaning you can make them anything you desire. For example, you could make yours username@ILOVEmIRCScripting.net. It can really be any combination of letters and numbers you'd like.

The personalized vHosts will only activate once you have properly identified yourself to NickServ. Once you're identified, your host becomes a vHost mask/vanity, and then your true connection ID is hidden. Well, what if your auto join triggers before you've properly identifed to NickServ services? The vHost would be useless, as your true identity would already have been exposed to the channel upon joining.

This is where a signal can truly shine, and next we are going to show you how :)

Code

First, what should we name our signal? How about delayAutoJoin? That works, and it identifies the purpose of the signal. Next, which script should perform the /signal command, the auto join, or the auto identifier? Well, just remember that we don't want to join channels until the auto identifier has completed. In this case, we can ascertain that the auto identifier should be the one to trigger the command, the auto join should listen for the signal.

Let's go to our auto identifier and setup our script:

ON *:NOTICE:*This nickname is registered*:?:{
  ; Check to make sure NickServ issued this notice,
  ; and then identify our nickname with our password
  ; (Note: mypassword is an example password; you would insert
  ; your real password here)
  if ($nick == NickServ) { ns identify mypassword }
}

Alright, so what have we done? This event listens for NickServ to send you a notice requesting that you identify yourself to this registered nickname. If that event triggers, next thing we do is check to make sure the nickname who sent us the notice was actually NickServ (security purposes, optional but recommended). Finally, if the nickname was NickServ, send the identification command which includes our password.

Note: For the most part, most NickServ requests like this are defaulted for cross-platform compatibility. Using this example is most-likely fine, but do some research for your own NickServ's requests to properly utilize the above event.

Next, let's check for when NickServ acknowledges that we've properly been identified by letting us know our vHost is now applied:

ON *:NOTICE:*Your vhost*activated*:?: {
  ; Send the delayAutoJoin signal to all listening scripts
  signal delayAutoJoin
}

This event waits for the NickServ notice letting us know our vHost has been activated, and then sends a signal with the name delayAutoJoin to all currently loaded scripts. The auto identifier portion of our example is finished. Now we will move on to the auto join, where we will create our signal listener, and perform the auto join function. Remember, this portion of code belongs in the auto join, not the auto identifier:

ON *:SIGNAL:delayAutoJoin: {
  join #mychannel
}

So, now our auto join script will listen for the signal, which will be triggered once our vHost has been successfully activated, and then join the channel(s) it has been coded to join. For all intense purposes, this event has been trimmed to the simplest possible explanation. It could be made much more extravagant, with an auto join list read from a hash table or an INI file.

Compatibility

Added: mIRC v6.0

Added On: 03/02/2002

See also

• List of commands
• List of identifiers
• ON Events