LocalConnection  - AS3

Indique l’objet sur lequel des méthodes de rappel sont appelées. L’objet par défaut correspond à this, la connexion locale en cours de création. Si vous réglez la propriété client sur un autre objet, les méthodes de rappel sont appelées sur celui-ci.

Plus d’exemples

Chaîne représentant le domaine de l’emplacement du fichier actuel.

Dans le cas de contenu s’exécutant dans le sandbox de sécurité application dans Adobe AIR (contenu installé avec l’application AIR), le moteur d’exécution remplace le super-domaine par la chaîne app# suivie de l’ID correspondant à l’application AIR (défini dans le fichier descripteur de l’application). Par exemple, l’argument connectionName d’une application dont l’ID est com.example.air.MyApp connectionName devient "app#com.example.air.MyApp:connectionName".

Dans les fichiers SWF publiés pour Flash Player 9 ou version ultérieure, la chaîne renvoyée correspond au domaine exact du fichier, y compris aux sous-domaines. Par exemple, si le fichier se trouve à l’adresse www.adobe.com, cette commande renvoie "www.adobe.com".

Si le fichier actuel est un fichier local résidant sur l’ordinateur client et s’exécutant dans Flash Player, cette commande renvoie "localhost".

Les emplois les plus courants de cette propriété consistent à inclure le nom de domaine de l’objet LocalConnection d’envoi en tant que paramètre de la méthode que vous comptez appeler dans l’objet LocalConnection de réception, ou conjointement avec LocalConnection.allowDomain() pour accepter les commandes issues d’un domaine spécifique. Si vous autorisez uniquement la communication entre les objets LocalConnection appartenant au même domaine, vous n’aurez probablement pas besoin d’utiliser cette propriété.

Eléments de l’API associés

Indique si le domaine de l’objet LocalConnection est limité à l’utilisateur actuel (true) ou s’il est accessible à tous les utilisateurs sur le poste de travail (false). Cette propriété affecte uniquement le contenu s’exécutant sous Mac OS X ; les autres plates-formes ignorent ce paramètre. Les connexions sur les systèmes d’exploitation Windows et Linux s’effectuent toujours par utilisateur.

Dans Flash Player 10.0.22 et les versions antérieures, et dans AIR 1.5.1 et les versions antérieures, tous les objets LocalConnection sous Mac OS X ont un domaine global. Définissez toujours cette propriété sur true, à moins que vous ayez besoin de conserver la compatibilité avec les versions précédentes. Dans les futures versions, la valeur par défaut de cette propriété peut changer à true.

La valeur par défaut est false.

La propriété isSupported est définie sur true si la classe LocalConnection est disponible sur la plate-forme actuelle ; dans le cas contraire, elle est définie sur false.

Crée un objet LocalConnection. Les objets LocalConnection vous permettent d’activer les communications entre différents fichiers s’exécutant sur un même ordinateur client.

Eléments de l’API associés

Spécifie un ou plusieurs domaines qui peuvent envoyer des appels LocalConnection à cette occurrence de LocalConnection.

Vous ne pouvez pas utiliser cette méthode pour permettre aux fichiers hébergés à l’aide d’un protocole sécurisé (HTTPS) d’autoriser un accès à partir de fichiers hébergés avec des protocoles non sécurisés ; vous devez pour cela utiliser la méthode allowInsecureDomain().

Vous pouvez utiliser cette méthode pour faire en sorte qu’un fichier enfant issu d’un domaine différent puisse effectuer des appels LocalConnection vers le fichier parent, sans connaître le domaine final dont émanera le fichier enfant. Cela peut se produire, par exemple, lorsque vous utilisez des redirections d’équilibrage de charge ou des serveurs tiers. Dans ce cas, vous pouvez utiliser la propriété url de l’objet LoaderInfo utilisé avec le chargement de sorte que le domaine s’utilise avec la méthode allowDomain(). Par exemple, si vous chargez un fichier enfant à l’aide d’un objet Loader, à l’issue du chargement, vous pouvez vérifier la propriété contentLoaderInfo.url de l’objet Loader et analyser le domaine à travers la chaîne URL complète. Si vous procédez ainsi, veillez à attendre la fin du chargement du fichier, car la valeur de la propriété contentLoaderInfo.url ne sera correcte et définitive qu’une fois le fichier entièrement chargé.

Le cas contraire peut aussi se présenter : vous pouvez créer un fichier enfant qui souhaite accepter les appels LocalConnection émanant de son parent, mais qui ignore le domaine de ce dernier. Dans ce cas, mettez en œuvre cette méthode en vérifiant si l’argument de domaine correspond au domaine de la propriété loaderInfo.url dans le fichier chargé. Encore une fois, vous devez analyser le domaine à partir de l’adresse URL complète de loaderInfo.url. Dans ce cas, il n’est pas nécessaire d’attendre la fin du chargement du fichier parent ; le parent sera déjà chargé lorsque celui de l’enfant commencera.

Lorsque vous employez cette méthode, tenez compte du modèle de sécurité de Flash Player. Par défaut, un objet LocalConnection est associé au sandbox du fichier qui l’a créé et les appels interdomaines des objets LocalConnection sont interdits, à moins que vous n’appeliez la méthode LocalConnection.allowDomain() dans le fichier de réception. Néanmoins, dans Adobe AIR, le contenu du sandbox de sécurité application (contenu installé avec l’application AIR) n’est pas soumis à ces restrictions de sécurité.

Pour plus d’informations concernant la sécurité, voir la rubrique du Pôle de développement Flash Player : Sécurité (disponible en anglais uniquement).

Remarque : le format de la méthode allowDomain() n’est plus le même que dans ActionScript 1.0 et 2.0. Dans ces versions, allowDomain était une méthode de rappel que vous implémentiez. Dans ActionScript 3.0, allowDomain() est une méthode intégrée de LocalConnection que vous appelez. Le fonctionnement de la nouvelle version de allowDomain() est similaire à celui de flash.system.Security.allowDomain().

Paramètres

Plus d’exemples

Eléments de l’API associés

Spécifie un ou plusieurs domaines qui peuvent envoyer des appels LocalConnection à cet objet LocalConnection.

Le fonctionnement des méthodes allowInsecureDomain() et allowDomain() est identique, mais la méthode allowInsecureDomain() permet en outre aux fichiers de source non HTTPS d’envoyer des appels LocalConnection à des fichiers SWF de source HTTPS. Cette différence n’a d’importance que si vous appelez la méthode allowInsecureDomain() à partir d’un fichier chargé via HTTPS. Vous devez appeler la méthode allowInsecureDomain() même si vous franchissez une limite non HTTPS/HTTPS au sein du même domaine. Par défaut, les appels de LocalConnection entre les fichiers non HTTPS et les fichiers HTTPS sont systématiquement interdits, même au sein d’un même domaine.

L’appel de allowInsecureDomain() est déconseillé, car il risque de compromettre la sécurité offerte par HTTPS. Lorsque vous chargez un fichier via HTTPS, vous avez la quasi-certitude qu’il ne sera pas altéré pendant sa mise en circulation dans le réseau. Si vous autorisez ensuite un fichier non HTTPS à effectuer des appels de LocalConnection vers le fichier HTTPS, vous acceptez des appels en provenance d’un fichier qui a pu être altéré pendant son transport. Vous devez donc redoubler de vigilance, car vous ne pouvez pas vous fier à l’authenticité des appels LocalConnection que reçoit votre fichier HTTPS.

Par défaut, les fichiers hébergés via le protocole HTTPS sont accessibles uniquement aux autres fichiers hébergés également par l’intermédiaire du protocole HTTPS. Cette implémentation préserve l’intégrité fournie par le protocole HTTPS.

Il n’est pas recommandé d’utiliser cette méthode pour annuler le comportement par défaut car elle compromet la sécurité HTTPS. Cependant, vous devrez peut-être l’utiliser, par exemple, si vous devez autoriser l’accès aux fichiers SWF publiés pour Flash Player 9 ou version ultérieure via HTTPS à partir de fichiers SWF publiés pour Flash Player 6 ou version antérieure via HTTP.

Pour plus d’informations concernant la sécurité, voir la rubrique du Pôle de développement Flash Player : Sécurité (disponible en anglais uniquement).

Paramètres

Plus d’exemples

Eléments de l’API associés

Ferme (déconnecte) un objet LocalConnection. Appelez cette commande lorsque vous ne souhaitez plus que l’objet accepte de commandes, par exemple, lorsque vous souhaitez exécuter une commande connect() en utilisant le même paramètre connectionName dans un autre fichier SWF.

Eléments de l’API associés

Prépare un objet LocalConnection à recevoir les commandes envoyées à partir d’une commande send() (l’objet LocalConnection d’envoi). L’objet utilisé avec la méthode connect() est appelé objet LocalConnection de réception. Les objets de réception et d’envoi doivent s’exécuter sur le même ordinateur client.

Pour éviter tout conflit, définissez les méthodes associées à l’objet LocalConnection de réception avant d’appeler cette méthode, comme illustré dans l’exemple de la classe LocalConnection.

Par défaut, l’argument connectionName devient "superdomain:connectionName", superdomain représentant le super-domaine du fichier qui contient la commande connect(). Par exemple, si le fichier contenant l’objet LocalConnection de réception se trouve à l’adresse www.someDomain.com, connectionName devient "someDomain.com:connectionName". (si un fichier s’exécutant dans Flash Player se trouve sur l’ordinateur client, la valeur affectée au superdomain est "localhost").

Dans le cas de contenu s’exécutant dans le sandbox de sécurité application dans Adobe AIR (contenu installé avec l’application AIR), le moteur d’exécution remplace le super-domaine par la chaîne app# suivie de l’ID correspondant à l’application AIR (défini dans le fichier descripteur de l’application). Par exemple, l’argument connectionName d’une application dont l’ID est com.example.air.MyApp connectionName devient "app#com.example.air.MyApp:connectionName".

De même, par défaut, Flash Player ne permet à l’objet LocalConnection de réception de n’accepter que les commandes provenant d’objets LocalConnection d’envoi dont le nom de connexion correspond également à une valeur "superdomain:connectionName". De cette manière, Flash Player facilite la communication entre les fichiers situés dans un même domaine.

Si vous implémentez une communication uniquement entre des fichiers appartenant au même domaine, spécifiez pour connectionName une chaîne qui ne commence pas par un caractère de soulignement (_) et qui ne spécifie pas un nom de domaine (par exemple, "myDomain:connectionName"). Utilisez cette même chaîne dans la méthode connect(connectionName).

Si vous implémentez des communications entre des fichiers de domaines différents, la spécification pour connectionName d’une chaîne qui commence par un caractère de soulignement (_) accroît la portabilité interdomaines du fichier associé à l’objet LocalConnection de réception. Les cas de figure possibles sont les suivants :

• Si la chaîne dédiée à l’argument connectionName ne commence pas par un caractère de soulignement (_), un préfixe suivi de deux points est ajouté au super-domaine (par exemple, "myDomain:connectionName"). Vous avez ainsi la garantie que votre connexion n’entrera pas en conflit avec les connexions de même nom dans d’autres domaines. Cependant, tous les objets LocalConnection d’envoi doivent spécifier ce super-domaine (par exemple, "myDomain:connectionName"). Si le fichier associé à l’objet LocalConnection de réception est déplacé dans un autre domaine, Flash Player modifie le préfixe afin qu’il reflète le nouveau super-domaine (par exemple, « anotherDomain:connectionName »). Tous les objets LocalConnection d’envoi doivent être modifiés manuellement pour pointer vers le nouveau super-domaine.
• Si la chaîne dédiée à l’argument connectionNamecommence par un caractère de soulignement (par exemple, "_connectionName"), aucun préfixe n’est ajouté à la chaîne. Les objets LocalConnection de réception et d’envoi utilisent donc des chaînes identiques pour connectionName. Si l’objet de réception utilise allowDomain() pour spécifier que les connexions seront acceptées à partir de tous les domaines, le fichier contenant l’objet LocalConnection de réception peut être déplacé dans un autre domaine, sans qu’il soit nécessaire de modifier les objets LocalConnection d’envoi.

Pour plus d’informations, voir la présentation de la classe et la section consacrée au paramètre connectionName de la méthode send(), ainsi que les entrées de allowDomain() et domain.

Remarque : les deux-points sont utilisés en tant que caractères spéciaux pour séparer le super-domaine de la chaîne connectionName. Toute chaîne associée à connectionName contenant deux-points n’est pas valide.

Lorsque vous utilisez cette méthode, tenez compte du modèle de sécurité Flash Player : Par défaut, un objet LocalConnection est associé au sandbox du fichier qui l’a créé et les appels interdomaines des objets LocalConnection sont interdits, à moins que vous n’appeliez la méthode LocalConnection.allowDomain() dans le fichier de réception. Vous pouvez empêcher un fichier d’utiliser cette méthode en définissant le paramètre allowNetworking des balises object et embed dans la page HTML qui comporte le contenu SWF. Néanmoins, dans Adobe AIR, le contenu du sandbox de sécurité application (contenu installé avec l’application AIR) n’est pas soumis à ces restrictions de sécurité.

Pour plus d’informations concernant la sécurité, voir la rubrique du Pôle de développement Flash Player : Sécurité (disponible en anglais uniquement).

Paramètres

Plus d’exemples

Eléments de l’API associés

Appelle la méthode nommée methodName sur une connexion établie à l’aide de la méthode connect(connectionName) (dans l’objet LocalConnection de réception). L’objet utilisé avec la méthode send() est appelé objet LocalConnection d’envoi. Les fichiers SWF qui contiennent les objets d’envoi et de réception doivent s’exécuter sur le même ordinateur client.

La quantité de données que vous pouvez transmettre en tant que paramètres à cette commande est limitée à 40 Ko. Si send() émet une ArgumentError mais que votre syntaxe est correcte, tentez de répartir les requêtes send() dans plusieurs commandes, chacune comportant moins de 40 Ko de données.

Comme nous l’avons vu à la rubrique connect(), le super-domaine actuel est ajouté à connectionName par défaut. Si vous implémentez la communication entre différents domaines, vous devez définir connectionName dans les objets LocalConnection d’envoi et de réception de sorte que le super-domaine actuel ne soit pas ajouté à connectionName. Pour ce faire, procédez de l’une des deux façons suivantes :

• Placez un caractère de soulignement (_) au début de connectionName dans les objets LocalConnection d’envoi et de réception. Dans le fichier contenant l’objet de réception, utilisez LocalConnection.allowDomain() pour spécifier que des connexions seront acceptées de tous les domaines. Cette implémentation vous permet de stocker vos fichiers d’envoi et de réception dans n’importe quel domaine.
• Intégrez le super-domaine à connectionName dans l’objet LocalConnection d’envoi, par exemple, myDomain.com:myConnectionName. Dans l’objet de réception, utilisez LocalConnection.allowDomain() pour spécifier que les connexions à partir du super-domaine spécifié seront acceptées (dans ce cas, myDomain.com) ou que les connexions de tous les domaines seront acceptées.

Remarque : vous ne pouvez pas spécifier de super-domaine dans connectionName dans l’objet LocalConnection de réception ; vous ne pouvez le faire que dans celui d’envoi.

Lorsque vous utilisez cette méthode, tenez compte du modèle de sécurité Flash Player : Par défaut, un objet LocalConnection est associé au sandbox du fichier qui l’a créé et les appels interdomaines des objets LocalConnection sont interdits, à moins que vous n’appeliez la méthode LocalConnection.allowDomain() dans le fichier de réception. Dans le cas de contenu SWF s’exécutant dans le navigateur, vous pouvez empêcher un fichier d’utiliser cette méthode en définissant le paramètre allowNetworking des balises object et embed dans la page HTML qui héberge le contenu SWF. Néanmoins, dans Adobe AIR, le contenu du sandbox de sécurité application (contenu installé avec l’application AIR) n’est pas soumis à ces restrictions de sécurité.

Pour plus d’informations concernant la sécurité, voir la rubrique du Pôle de développement Flash Player : Sécurité (disponible en anglais uniquement).

Paramètres

Plus d’exemples

Eléments de l’API associés

Distribué lorsqu’une erreur est renvoyée de manière asynchrone ; autrement dit, lorsqu’elle provient du code asynchrone natif.

Les propriétés de cet événement sont les suivantes :

Distribué si un appel de LocalConnection.send() tente d’envoyer des données à un autre sandbox de sécurité.

Les propriétés de cet événement sont les suivantes :

Eléments de l’API associés

Distribué lorsqu’un objet LocalConnection publie son état. Si LocalConnection.send() aboutit, la valeur de la propriété level de l’objet d’événement status correspond à "status". Dans le cas contraire, la propriété level correspond à "error". Si le fichier de réception refuse la connexion, l’appel peut échouer sans que le fichier d’envoi n’en soit averti.

Les propriétés de cet événement sont les suivantes :

Eléments de l’API associés

Une occurrence de LocalConnection est créée dans le fichier SWF LocalConnectionSenderExample. Lorsque l’utilisateur appuie sur le bouton, la méthode call() est utilisée pour appeler la méthode lcHandler dans le fichier SWF contenant le nom de connexion « myConnection » et le contenu de TextField est transmis en tant que paramètre.

Une occurrence de LocalConnection est créée dans le fichier SWF LocalConnectionReceiverExample et la méthodeconnect() est appelée pour désigner ce fichier SWF comme destinataire des messages adressés à la connexion « myConnection ». En outre, cette classe comprend une méthode publique intitulée lcHandler(). Il s’agit de la méthode appelée par le fichier SWF LocalConnectionSenderExample. Lorsqu’elle est appelée, le texte reçu en tant que paramètre est ajouté à TextField sur la scène.

Remarque : pour tester l’exemple, chargez les deux fichiers SWF simultanément sur le même ordinateur.

// Code in LocalConnectionSenderExample.as
package {
    import flash.display.Sprite;
    import flash.events.MouseEvent;
    import flash.net.LocalConnection;
    import flash.text.TextField;
    import flash.text.TextFieldType;
    import flash.events.StatusEvent;
    import flash.text.TextFieldAutoSize;

    public class LocalConnectionSenderExample extends Sprite {
        private var conn:LocalConnection;
        
        // UI elements
        private var messageLabel:TextField;
        private var message:TextField;
        private var sendBtn:Sprite;
        
        public function LocalConnectionSenderExample() {
            buildUI();
            sendBtn.addEventListener(MouseEvent.CLICK, sendMessage);
            conn = new LocalConnection();
            conn.addEventListener(StatusEvent.STATUS, onStatus);
        }
        
        private function sendMessage(event:MouseEvent):void {
            conn.send("myConnection", "lcHandler", message.text);
        }
        
        private function onStatus(event:StatusEvent):void {
            switch (event.level) {
                case "status":
                    trace("LocalConnection.send() succeeded");
                    break;
                case "error":
                    trace("LocalConnection.send() failed");
                    break;
            }
        }
        
        private function buildUI():void {
            const hPadding:uint = 5;
            // messageLabel
            messageLabel = new TextField();
            messageLabel.x = 10;
            messageLabel.y = 10;
            messageLabel.text = "Text to send:";
            messageLabel.autoSize = TextFieldAutoSize.LEFT;
            addChild(messageLabel);
            
            // message
            message = new TextField();
            message.x = messageLabel.x + messageLabel.width + hPadding;
            message.y = 10;
            message.width = 120;
            message.height = 20;
            message.background = true;
            message.border = true;
            message.type = TextFieldType.INPUT;
            addChild(message);
            
            // sendBtn
            sendBtn = new Sprite();
            sendBtn.x = message.x + message.width + hPadding;
            sendBtn.y = 10;
            var sendLbl:TextField = new TextField();
            sendLbl.x = 1 + hPadding;
            sendLbl.y = 1;
            sendLbl.selectable = false;
            sendLbl.autoSize = TextFieldAutoSize.LEFT;
            sendLbl.text = "Send";
            sendBtn.addChild(sendLbl);
            sendBtn.graphics.lineStyle(1);
            sendBtn.graphics.beginFill(0xcccccc);
            sendBtn.graphics.drawRoundRect(0, 0, (sendLbl.width + 2 + hPadding + hPadding), (sendLbl.height + 2), 5, 5);
            sendBtn.graphics.endFill();
            addChild(sendBtn);
        }
    }
}