Connexion à d'autres instances Flash Player -- Flash CS3

La classe LocalConnection vous permet de communiquer avec différentes instances de Flash Player, par exemple un fichier SWF dans un conteneur HTML ou dans un lecteur intégré ou autonome. Vous pouvez ainsi élaborer des applications très polyvalentes, capables de partager des données entre plusieurs instances de Flash Player, par exemple des fichiers SWF exécutés dans un navigateur Web ou incorporés dans des applications de bureau.

Sous-rubriques

Classe LocalConnection

La classe LocalConnection permet de développer des fichiers SWF qui peuvent échanger des instructions avec d'autres fichiers SWF sans utiliser la méthode fscommand() ni JavaScript. Les objets LocalConnection peuvent uniquement communiquer entre des fichiers SWF exécutés sur le même ordinateur client, mais ils peuvent concerner différentes applications. Par exemple, un fichier SWF exécuté dans un navigateur et un fichier SWF de projection peuvent partager des informations, le fichier de projection se chargeant de maintenir les informations locales et le fichier SWF du navigateur se connectant à distance. (Un fichier de projection est un fichier SWF enregistré dans un format tel qu'il peut s'exécuter de manière autonome ; il n'est donc pas nécessaire de disposer de Flash Player pour le lire car il est incorporé dans le fichier exécutable.)

Les objets LocalConnection peuvent être utilisés pour communiquer entre des SWF utilisant différentes versions d'ActionScript :

Flash Player gère automatiquement les communications entre les objets LocalConnection de versions différentes.

La meilleure façon d'utiliser un objet LocalConnection est d'autoriser la communication uniquement entre des objets LocalConnection se trouvant dans le même domaine. Ainsi, vous évitez les problèmes de sécurité. Toutefois, si vous devez autoriser la communication entre les domaines, vous pouvez procéder de différentes façons pour mettre en œuvre vos mesures de sécurité. Pour plus d'informations, reportez-vous à la section consacrée au paramètre connectionName de la méthode send() et aux entrées allowDomain() et domain dans la liste de la classe LocalConnection dans la Référence du langage et des composants ActionScript 3.0.

Les méthodes de rappel peuvent être ajoutées aux objets LocalConnection de trois manières :

La première manière d'ajouter des méthodes de rappel est d'étendre la classe LocalConnection. Vous pouvez définir les méthodes au sein de la classe personnalisée, plutôt que de les ajouter dynamiquement à l'instance LocalConnection. Ceci est illustré par le code suivant :

package
{
    import flash.net.LocalConnection;
    public class CustomLocalConnection extends LocalConnection
    {
        public function CustomLocalConnection(connectionName:String)
        {
            try
            {
                connect(connectionName);
            }
            catch (error:ArgumentError)
            {
                // serveur déjà créé/connecté
            }
        }
        public function onMethod(timeString:String):void
        {
            trace("onMethod called at: " + timeString);
        }
    }
}

Pour créer une nouvelle instance de la classe DynamicLocalConnection, vous pouvez utiliser le code suivant :

var serverLC:CustomLocalConnection;
serverLC = new CustomLocalConnection("serverName");

La deuxième manière d'ajouter des méthodes de rappel consiste à utiliser la propriété LocalConnection.client. Il s'agit de créer une classe personnalisée et d'affecter une nouvelle instance à la propriété client, comme le montre le code suivant :

var lc:LocalConnection = new LocalConnection();
lc.client = new CustomClient();

La propriété LocalConnection.client indique les méthodes de rappel d'objet à appeler. Dans le code précédent la propriété client était définie sur une nouvelle instance de la classe personnalisée CustomClient. La valeur par défaut de la propriété client est l'instance LocalConnection actuelle. Vous pouvez utiliser la propriété client si vous disposez de deux gestionnaires de données dotés du même jeu de méthodes mais qui agissent différemment ; par exemple, dans une application où un bouton situé dans une fenêtre permet d'afficher le contenu d'une deuxième fenêtre.

package
{
    public class CustomClient extends Object
    {
        public function onMethod(timeString:String):void
        {
            trace("onMethod called at: " + timeString);
        }
    }
}

La troisième manière d'ajouter des méthodes de rappel consiste à créer une classe dynamique et d'y joindre dynamiquement des méthodes. Elle se rapproche de l'utilisation de la classe LocalConnection dans les versions précédentes d'ActionScript, comme le montre le code suivant :

import flash.net.LocalConnection;
dynamic class DynamicLocalConnection extends LocalConnection {}

Les méthodes de rappel peuvent être ajoutées dynamiquement à cette classe à l'aide du code suivant :

var connection:DynamicLocalConnection = new DynamicLocalConnection();
connection.onMethod = this.onMethod;
// Insertion du code ici.
public function onMethod(timeString:String):void
{
    trace("onMethod called at: " + timeString);
}

Cette manière d'ajouter des méthodes de rappel est déconseillée, car le code n'est pas vraiment portable. En outre, cette méthode de création de connexions locales pourrait présenter des problèmes de performance car l'accès aux propriétés dynamiques prend bien plus de temps que l'accès aux propriétés scellées.

Envoi de messages entre deux instances de Flash Player

La classe LocalConnection permet de communiquer entre différentes instances de Flash Player. Par exemple, vous pouvez utiliser plusieurs instances de Flash Player sur une même page Web ou vous servir d'une instance de Flash Player pour récupérer des données dans une instance de Flash Player affichée dans une fenêtre distincte.

Le code suivant définit l'objet LocalConnection qui joue le rôle de serveur et accepte les appels entrants en provenance d'autres instances de Flash Player :

package
{
    import flash.net.LocalConnection;
    import flash.display.Sprite;
    public class ServerLC extends Sprite
    {
        public function ServerLC()
        {
            var lc:LocalConnection = new LocalConnection();
            lc.client = new CustomClient1();
            try
            {
                lc.connect("conn1");
            }
            catch (error:Error)
            {
                trace("error:: already connected");
            }
        }
    }
}

Ce code crée un objet LocalConnection nommé lc et définit la propriété client sur une classe personnalisée, CustomClient1. Lorsqu'une autre instance de Flash Player appelle une méthode dans cette instance LocalConnection, Flash Player recherche la méthode dans la classe CustomClient1.

Dès qu'une instance Flash Player se connecte à ce fichier SWF et essaie d'appeler l'une des méthodes de la connexion local, la requête est envoyée à la classe spécifiée par la propriété client, à savoir la classe CustomClient1 :

package
{
    import flash.events.*;
    import flash.system.fscommand;
    import flash.utils.Timer;
    public class CustomClient1 extends Object
    {
        public function doMessage(value:String = ""):void
        {
            trace(value);
        }
        public function doQuit():void
        {
            trace("quitting in 5 seconds");
            this.close();
            var quitTimer:Timer = new Timer(5000, 1);
            quitTimer.addEventListener(TimerEvent.TIMER, closeHandler);
        }
        public function closeHandler(event:TimerEvent):void
        {
            fscommand("quit");
        }
    }
}

Pour créer un serveur LocalConnection, appelez la méthode LocalConnection.connect() et fournissez un nom de connexion unique. Si une connexion est déjà ouverte avec le nom choisi, une erreur ArgumentError est générée, ce qui indique que la tentative de connexion a échoué parce que l'objet était déjà connecté.

L'extrait de code suivant illustre comment créer une nouvelle connexion de socket nommée conn1 :

try
{
    connection.connect("conn1");
}
catch (error:ArgumentError)
{
    trace("Error! Server already exists\n");
}

La connexion au fichier SWF principal à partir d'un fichier SWF secondaire nécessite que vous créiez un objet LocalConnection dans l'objet LocalConnection d'envoi, puis que vous appeliez la méthode LocalConnection.send() avec le nom de la connexion et le nom de la méthode à exécuter. Par exemple, pour connecter un objet LocalConnection créé précédemment, vous pouvez utiliser le code suivant :

sendingConnection.send("conn1", "doQuit");

Ce code établit une connexion conn1 à l'objet LocalConnection existant, puis appelle la méthode doQuit() dans le fichier SWF distant. Si vous souhaitez envoyer des paramètres au fichier SWF distant, spécifiez les arguments supplémentaires après le nom de la méthode send(), comme le montre l'extrait de code suivant :

sendingConnection.send("conn1", "doMessage", "Hello world");

Connexion à des documents SWF de domaines différents

Pour autoriser uniquement les communications issues de domaines précis, appelez la méthode allowDomain() ou allowInsecureDomain() de la classe LocalConnection et transmettez la liste des domaines autorisés à accéder à cet objet LocalConnection.

Dans les versions antérieures d'ActionScript, LocalConnection.allowDomain() et LocalConnection.allowInsecureDomain() étaient des méthodes de rappel que les développeurs devaient mettre en œuvre et qui devaient renvoyer une valeur booléenne. Dans ActionScript 3.0, LocalConnection.allowDomain() et LocalConnection.allowInsecureDomain() sont deux méthodes intégrées, que les développeurs peuvent appeler de la même façon que Security.allowDomain() et Security.allowInsecureDomain(), en transmettant un ou plusieurs noms de domaines à autoriser.

Deux valeurs spéciales peuvent être transmises aux méthodes LocalConnection.allowDomain() et LocalConnection.allowInsecureDomain() : * et localhost. L'astérisque (*) permet d'accéder à tous les domaines. La chaîne localhost permet d'appeler le fichier SWF à partir des fichiers SWF installés localement.

Dans Flash Player 8, des restrictions de sécurité relatives aux fichiers SWF locaux ont été introduites. Un fichier SWF autorisé à accéder à Internet n'a pas accès au système de fichiers local. Si vous spécifiez localhost, tout fichier SWF local peut accéder à ce fichier SWF. Si la méthode LocalConnection.send() essaie de communiquer avec un fichier SWF à partir d'un sandbox de sécurité auquel le code d'appel n'a pas accès, un événement securityError (SecurityErrorEvent.SECURITY_ERROR) est distribué. Pour résoudre l'erreur, vous pouvez spécifier le domaine de l'appelant dans la méthode LocalConnection.allowDomain() de la cible.

Si vous mettez en œuvre la communication uniquement entre les fichiers SWF du même domaine, vous pouvez spécifier un paramètre connectionName qui ne commence pas par un trait de soulignement (_) et ne renvoie pas à un nom de domaine (par exemple myDomain:connectionName). Utilisez la même chaîne dans la commande LocalConnection.connect(connectionName).

Si vous mettez en œuvre la communication entre les fichiers SWF de différents domaines, spécifiez un paramètre connectionName qui commence par un trait de soulignement. L'ajout d'un trait de soulignement améliore la portabilité entre domaines du fichier SWF contenant l'objet LocalConnection de réception. Voici deux cas de figures possibles :