Editing mirc/commands/signal

{{mIRC menu}}
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:
<syntaxhighlight lang="mirc">/signal [-n] <name> [parameters]</syntaxhighlight>

=== Flags ===
'''-n''': This flag tells the ''/signal'' command to fire immediately after the end of the current routine, not after the end of the whole script processing, which is the case if you don't provide -n.

=== Examples ===
Let's check out an example of a signal command below:
<syntaxhighlight lang="mirc">/signal mysignal Signal information!</syntaxhighlight>

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 listening for that signal will trigger, and perform whatever tasks they have been set to perform.

<syntaxhighlight lang="mirc">ON *:SIGNAL:mysignal:echo -s rcvd: $signal : $1-</syntaxhighlight>

== Identifiers ==
<span style="display: inline-block; width: 85px;">''$signal''</span>Returns the signal name of the signal which triggered the current event.

<span style="display: inline-block; width: 85px;">''$1-''</span>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:
<syntaxhighlight lang="mirc">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 }
}</syntaxhighlight>

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:
<syntaxhighlight lang="mirc">ON *:NOTICE:*Your vhost*activated*:?: {
  ; Send the delayAutoJoin signal to all listening scripts
  signal delayAutoJoin
}</syntaxhighlight>

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:

<syntaxhighlight lang="mirc">ON *:SIGNAL:delayAutoJoin: {
  join #mychannel
}</syntaxhighlight>

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 ==
{{mIRC compatibility|6.0}}

== See also ==
* [[List of commands - mIRC|List of commands]]
* [[List of identifiers - mIRC|List of identifiers]]
* [[On events - mIRC|ON Events]]
{{mIRC command list}}

[[Category:mIRC commands|signal command - mIRC]]