# 5.2. Points d'insertion

Depuis les scripts `loaded`, aussi bien que depuis `.sircrc.pl`, vous avez la possibilité de définir des routines à appeler lorsque des événements particuliers se produisent. C'est l'équivalent de ircII `/on's`.

Pour déclarer un point d'insertion, vous devez définir une sous-routine appelée `"hook_somename"` qui agit quoi que vous vouliez faire lorsqu'un point d'insertion de type `"hook_type"` est (déclenché), et ensuite appelle `&addhook("hook_type", "somename");`

Pour supprimer un point d'insertion, vous appelez `&remhook("hook_type", "somename");`

Les points d'insertion numériques son également disponibles, pour chaque nombre à 3 caractères; pour déclarer l'un d'eux, définissez une sous-routine appelée `"hook_somename"` qui agit comme vous le voulez, et appelez `&addhook("xxx", "somename")`, où xxx est le nombre représentant la réponse numérique. Pour supprimer l'un d'eux, appelez `&remhook("xxx", "somename");`

Les sous-programmes appelés à partir des points d'insertion ont accès aux mêmes fonctions et variables listées plus haut pour les fonctions, plus quelques-unes plus spécifiques (partout où c'est applicable) :

     $who		est le pseudonyme qui a déclenché le point d'insertion
     $user           est le nom d'utilisateur correspondant
     $host		est le nom d'hôte correspondant

Les points d'insertion peuvent également définir la variable `$silent` s'ils veulent assurer l'affichage pour l'éventualité (à travers `&print`) et bloquer les valeurs par défaut. C'est l'équivalent direct de la connexion `"ˆ"` sur ircII `/on's`, excepté `"raw_irc"`.

Les points d'insertion marqués avec une `*` peuvent aussi définir la variable spéciale `$skip` et la ligne sera ignorée par le client). Ceci est en général une mauvaise idée, utilisez `$silent` autant que possible. Seuls les points d'insertion où ce procédé fournit une fonctionnalité supplémentaire réelle ont cette possibilité. Pour `"raw_irc"` c'eest l'aquivalent de la connexion `"ˆ"` sur ircII `/on raw_irc`.

Les points d'insertion suivants sont disponibles, et sont appelés avec les arguments suivants :

     action		activée par une action ctcp;
     		le 1er argument est le pseudonyme ou le canal auquel il est envoyé
     		le 2e argument est le message

     commande      *	activée par l'utilisateur tapant une commande (sans tenir compte
                     si c'est une /commande ou seulement une ligne de texte)
                     le 1er argument est la ligne de l'utilisateur
                     ce point d'insertion est spécial (comme "print" et "status"), en ce
                     sens qu'il est clairement autorisé à modifier son argument ($_[0]) pour
                     modifier toute commande pouvant être interprétée.
     		la définition $skip=1 dans le point d'insertion obligera sirc à
                     ignorer la commande

     chat_disconnect activée lorqu'une discussion en ligne est perdue (mais non lorsque
                     l'utilisateur la clôture lui-même avec DCC CLOSE CHAT)
                     le 1er argument est le pseudonyme associé à la discussion en ligne

     ctcp	     *	activée par tout ctcp, AVANT que le client n'effectue l'analyse
                     et éventuellement réponde au ctcp.
     		le 1er argument est le nom ou le canal auquel il a été émis
                     le 2e argument est la commande ctcp
                     les 3e arguments sont les arguments eux-mêmes

     ctcp_reply	activée par les réponses ctcp;
                     le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                     le 2e argument est la commande ctcp
                     les 3e arguments sont les arguments eux-mêmes

     dcc_chat	activée par le texte reçu pendant une discussion en ligne dcc
     		le 1er argument est le pseudonyme
     		le 2e argument est le texte

     dcc_disconnect  activée lorsqu'une lecture ou une émission dcc est terminée ou fermée
                     (même lorsque l'utilisateur en clôture une avec DCC CLOSE GET/SEND)
                     le 1er argument est le pseudonyme associé à la discussion en ligne
                     le 2e argument est le nom de fichier
                     le 3e argument est le nombre de bytes transférés
                     le 4e argument est nombre de secondes nécessaires au transfert

     dcc_request	activée par la réception d'une discussion en ligne ou d'une demande
                     d'émission; Ceci est le point d'insertion à utiliser si vous voulez
                     mettre en oeuvre toute discussion auto-dcc.
                     le 1er argument est le type "(DISCUSSION" ou "EMISSION")
                     le 2e argument est l'adresse de la machine (un nombre entier 32 bits)
                     le 3e argument est le port
                     pour une proposition DCC SEND (émission DCC) :
                       le 4e argument est le nom de fichier
                       le 5e argument est la longueur du fichier

     disconnect      activée par la perte de la connexion au serveur, ou l'interruption
                     avec /déconnexion (mais pas avec le serveur).
                     il n'y a pas d'arguments

     input	     *	activée chaque fois que le client veut demander à l'utilisateur une
                     ligne par &getuserline (c'est-à-dire lorsque vous avez été
                     déconnecté, ou que vous avez besoin d'un nouveau pseudonyme,
                     ou d'un script appelé &getuserline).
                     le 1er argument est l'"invite" longue
                     le 2e argument est l'"invite" courte
                     si le point d'insertion définit $skip, &getuserline ne demandera
                     ensuite rien à l'utilisateur, et le contenu de  $_ will  sera renvoyé

     invite		activée par les invites;
                     le 1er argument est le canal que vous avez invité

     join		activée par les jonctions
                     le 1er argument est le canal que joint $who (qui)

     kick		activée par les ();
                     le 1er argument est le pseudonyme ou la personne qui a été ()
                     le 2e argument est le canal d'où ils ont été (virés)
                     le 3e argument est le motif

     leave		activée par les (partants);
                     le 1er argument est le canal que $who abandonne

     mode		activée par les changements de modes;
                     le 1er argument est le canal ou l'utilisateur auquel s'applique le changement
                     le 2e argument est le changement de mode lui-même

     msg		activée par les messages;
     		le 1er argument est le message

     nick		activée par les changements de pseudonymes
                     le 1er argument est le nouveau pseudonyme de $who (qui)

     notice		activée par les remarques
                     le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                     le 2e argument est le message

     server_notice	activée par les remarques depuis les serveurs
                     le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                     le 2e argument est le message

     notify_signon	activée par une ouverture de session
     		le 1er argument est le pseudonyme
                     $user et $host (utilisateur et hôte) ne sont *pas* définis
                     de façon significative

     notify_signoff	activée par une fermeture de session
                     le 1er argument est le pseudonyme
                     $user et $host ne sont *pas* définis de façon significative

     print	     *	activée par l'édition d'une ligne quelconque à l'écran
                     le 1er argument est la ligne à éditer
                     ce point d'insertion est spécial (comme "état" et "commande"),
                     en ce sens qu'il elle est clairement autorise à modifier
                     son argument ($_[0]) pour changer la ligne à éditer
                     la définitiion de $skip=1 dans le point d'insertion empêchera la ligne
                     d'être réellement éditée

     public		activée par les messages non-ctcp à un canal;
                     le 1er argument est le canal
                     le 2e argument est le message

     raw_irc      *	activée par une ligne du serveur
     	        $who    est l'initiateur (utilisateur ou serveur)
     		$user   est sont nom d'utilisateur ('' s'il vient d'un serveur)
     		$host   est son nom d'hôte (même commentaire)
                     le 1er argument est la commande
                     les seconds arguments sont les arguments eux-mêmes

     send_action	activée à l'émission  d'un /me ou d'un /de
     		($who, $user et $host ne s'appliquent pas ici)
                     le 1er argument est le pseudonyme/canal

     send_ctcp	activée à l'émission d'un ctcp
                     le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                     le second argument est le texte complet ctcp (type et arguments)

     send_dcc_chat	activée à l'émission du texte pendant une discussion en ligne dcc
                     ($who, $user et $host ne s'appliquent pas ici)
                     le 1er argument est le pseudonyme auquel nous émettons un message
                     le second argument est le texte

     send_text	activée à l'émission d'un /msg ou d'une communication sur un canal
     		($who, $user et $host ne s'appliquent pas ici)
                     le 1er argument est le pseudonyme/canal
                     le second argument est le message

     send_notice	activée à l'émission d'une remarque
                	($who, $user et $host ne s'appliquent pas ici)
                     le 1er argument est le pseudonyme/canal
                     le second argument est la remarque

     signoff		activée lorsque quelqu'un ferme une session
                     le 1er argument est le commentaire de sortie

     status		activée lorsque sirc reconfigure la ligne d'état (comme
                     résultat de l'appel à &dostatus, soit de façon interne,
                     soit par un script).
     		le 1er argument est la ligne d'état proposée
                     ce point d'insertion est spécial (comme "édition" et "commande")en ce sens
                     qu'il est clairement autorisé à modifier son argument ($_[0]) pour changer
                     ce qui devrait figurer sur la ligne d'état

     topic		activée lorsque quelqu'un change de sujet
                     le 1er argument est le canal
                     le second argument est le nouveau sujet

     <3-digit nb>  * activée par cette réponse numérique spéciale du serveur
                     le 1er argument est tout ce que le serveur a émis après le nombre,et
                     non analysé (qui signifie qu'il y a encore un caractère ":"
                     devant le dernier argument

Exemple, qu'est ce qui pourrait être placé dans un fichier et chargé directement, d'un point d'insertion qui joindra un canal chaque fois que vous serez (viré?) :

     # auto-rejoin hook (point d'insertion (auto-jonction?))

     sub hook_kicked {
       local($kicked, $where_from, $reason)=@_;
       					# local vars with the args (variables locales avec les arguments)
       if (&eq($kicked, $nick)) {		# if *we* got kicked (si *nous* sommes (virés?))
         &sl("JOIN $where_from");		# send a JOIN to the server (envoie une jonction au serveur)
       }
     }
     &addhook("kick", "kicked");	  	# activate the hook (active le point d'insertion)

Un autre exemple, pour afficher le nom d'utilisateur et le nom d'hôte avec chaque message (opération mieux réalisé avec /set printuh)

     # userhost-on message (point d'insertion du message)

     sub hook_uhmsg {
       &tell("[\cb${who}!${user}\@${host}\cb] $_[0]");  # print everything  (édite tout)
       $silent=1;			# disable the default display (désactive la variable par défaut)
     }
     &addhook("msg", "uhmsg");	  	# activate the hook  (active le point d'insertion)