SharedObject  - AS3

Indique l’objet sur lequel des méthodes de rappel sont appelées. L’objet par défaut est this. Si vous réglez la propriété client sur un autre objet, les méthodes de rappels sont appelées sur celui-ci.

Ensemble des attributs affectés à la propriété data de l’objet. Ces attributs peuvent être partagés et stockés. Chaque attribut peut être un objet d’un quelconque type ActionScript ou JavaScript : tableau, nombre, valeur booléenne, ByteArray, XML, etc. Par exemple, les lignes suivantes affectent des valeurs à différents aspects d’un objet partagé :

     var items_array:Array = new Array(101, 346, 483);
     var currentUserIsAdmin:Boolean = true;
     var currentUserName:String = "Ramona";
     
     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.data.itemNumbers = items_array;
     my_so.data.adminPrivileges = currentUserIsAdmin;
     my_so.data.userName = currentUserName;
     
     for (var prop in my_so.data) {
       trace(prop+": "+my_so.data[prop]);
     }
     

Tous les attributs de la propriété data d’un objet partagé sont enregistrés si l’objet est persistant, et l’objet partagé contient les informations suivantes :

     userName: Ramona
     adminPrivileges: true
     itemNumbers: 101,346,483
     

Remarque : n’affectez pas directement de valeurs à la propriété data d’un objet partagé, tel que dans so.data = someValue car Flash Player ignore ces affectations.

Pour supprimer des attributs pour des objets partagés locaux, utilisez un code tel que delete so.data.attributeName. La définition d’un attribut sur null ou undefined pour un objet partagé local ne supprime pas l’attribut.

Pour créer des valeurs privées pour un objet partagé, valeurs qui ne sont disponibles que pour l’occurrence du client alors que l’objet est utilisé et qui ne sont pas enregistrées avec l’objet lorsqu’il est fermé, créez des propriétés qui ne sont pas nommées data pour les enregistrer, comme l’illustre l’exemple suivant :

     var my_so:SharedObject = SharedObject.getLocal("superfoo");
     my_so.favoriteColor = "blue";
     my_so.favoriteNightClub = "The Bluenote Tavern";
     my_so.favoriteSong = "My World is Blue";
     
     for (var prop in my_so) {
       trace(prop+": "+my_so[prop]);
     }
     

L’objet partagé contient les données suivantes :

     favoriteSong: My World is Blue
     favoriteNightClub: The Bluenote Tavern
     favoriteColor: blue
     data: [object Object]
     

Dans le cas d’objets partagés distants utilisés avec un serveur, tous les attributs de la propriété data sont accessibles à tous les clients connectés à l’objet partagé, et tous les attributs sont enregistrés si l’objet est persistant. Lorsqu’un client modifie la valeur d’un attribut, tous les clients voient ensuite la nouvelle valeur.

Eléments de l’API associés

Encodage d’objet par défaut (version AMF) de tous les objets partagés locaux créés dans le fichier SWF. Lorsque les objets partagés locaux sont écrits sur le disque, la propriété SharedObject.defaultObjectEncoding indique la version AMF (Action Message Format) devant être utilisée : format ActionScript 3.0 (AMF3) ou format ActionScript 1.0 ou 2.0 (AMF0).

Pour plus d’informations sur l’encodage des objets, y compris sur les différences d’encodage des objets partagés selon qu’ils sont locaux ou distants, voir la description de la propriété objectEncoding.

La valeur par défaut de SharedObject.defaultObjectEncoding stipule l’utilisation du format ActionScript 3.0 (AMF3). Pour écrire des objets partagés locaux qui doivent être lus par des fichiers SWF ActionScript 2.0 ou 1.0, réglez SharedObject.defaultObjectEncoding sur flash.net.ObjectEncoding.AMF0 afin qu’elle utilise le format ActionScript 1.0 ou ActionScript 2.0, au début de votre script, avant de créer les objets. Tous les objets partagés locaux créés ultérieurement utiliseront l’encodage AMF0 et pourront interagir avec du contenu plus ancien. Après la création des objets partagés locaux, il est impossible de modifier leur valeur objectEncoding correspondante en définissant SharedObject.defaultObjectEncoding.

Pour configurer l’encodage objet par objet, plutôt que pour la totalité des objets partagés créés par le fichier SWF, définissez la propriété objectEncoding de l’objet concerné.

Eléments de l’API associés

Indique la fréquence, en secondes, d’envoi au serveur des modifications apportées à un client.

Cette méthode vous permet de contrôler le trafic entre le client et le serveur. Si la connexion entre le client et le serveur est relativement lente, par exemple, réglez fps sur une valeur peu élevée. Inversement, si le client est connecté à une application multi-utilisateurs et que la vitesse des échanges est primordiale, réglez fps sur une valeur relativement élevée.

La définition de fps déclenchera un événement sync et actualisera toutes les modifications sur le serveur. Pour actualiser le serveur manuellement, définissez fps sur 0.

Les modifications ne sont envoyées au serveur qu’après la diffusion de l’événement sync. En d’autres termes, si le serveur réagit lentement, l’envoi des mises à jour risque d’être moins fréquent que ne le spécifie la valeur de cette propriété.

Encodage d’objet (version AMF) de cet objet partagé. Lors de l’écriture d’un objet partagé local sur le disque, la propriété objectEncoding indique la version AMF (Action Message Format) devant être utilisée : format ActionScript 3.0 (AMF3) ou format ActionScript 1.0 ou 2.0 (AMF0).

L’encodage d’objet est géré différemment selon que l’objet partagé est local ou distant.

• Objets partagés locaux. Vous pouvez extraire ou définir la valeur de la propriété objectEncoding des objets partagés locaux. La valeur de la propriété objectEncoding a une incidence sur le formatage utilisé pour écrire l’objet local partagé. Si l’objet local partagé doit pouvoir être lu par des fichiers SWF ActionScript 2.0 ou 1.0, réglez objectEncoding sur ObjectEncoding.AMF0. Flash Player peut lire les objets partagés locaux AMF0 même si l’encodage d’objet écrit au format AMF3. En d’autres termes, si vous utilisez la valeur par défaut de cette propriété, ObjectEncoding.AMF3, votre fichier SWF peut néanmoins lire les objets partagés créés par les fichiers ActionScript 2.0 ou 1.0.
• Objets partagés distants. Lorsqu’il est connecté au serveur, un objet partagé distant hérite de son paramètre objectEncoding de l’occurrence de NetConnection associée (utilisée pour la connexion à l’objet partagé distant). Lorsqu’il n’est pas connecté au serveur, un objet partagé distant hérite du paramètre defaultObjectEncoding de l’occurrence de NetConnection associée. Comme la valeur de la propriété objectEncoding de l’objet partagé distant est déterminée par l’occurrence de NetConnection, cette propriété est en lecture seule pour les objets partagés distants.

Eléments de l’API associés

Indique si les objets partagés locaux seront sauvegardés par le service de sauvegarde dans le cloud d’iOS.

Indiquez la valeur true ou false :

• true : empêche la sauvegarde des objets partagés locaux par le service de sauvegarde dans le cloud d’iOS.
• false (par défaut) : les objets partagés locaux sont sauvegardés par le service de sauvegarde dans le cloud d’iOS.

Cette propriété ne s’applique qu’aux objets partagés locaux et ne concerne qu’iOS.

Taille actuelle de l’objet partagé, en octets.

Flash calcule la taille d’un objet partagé en examinant toutes ses propriétés data ; plus un objet a de propriétés data, plus l’estimation de sa taille prend du temps. L’estimation de la taille de l’objet peut monopoliser beaucoup de temps de traitement. Il est donc recommandé d’éviter cette méthode à moins d’en avoir réellement besoin.

Plus d’exemples

import flash.net.SharedObject;

// if these get copied or not
var mySo:SharedObject = SharedObject.getLocal("thehobbit");
mySo.data.username = "bilbobaggins";
trace(mySo.size); // 55

Dans le cas d’un objet partagé local, cette méthode purge toutes les données et supprime l’objet du disque. La référence à l’objet partagé reste active, mais ses propriétés data sont effacées.

Pour les objets partagés distants utilisés avec Flash Media Server, clear() déconnecte l’objet et purge toutes ses données. Si l’objet partagé est persistant localement, cette méthode le supprime également du disque. La référence à l’objet partagé reste active, mais ses propriétés data sont effacées.

package {
    import flash.net.SharedObject;

    public class SharedObject_clear {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_clear() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            if(mySo.data.username == null) {
                mySo.data.username = username;
                trace("set: " + mySo.data.username); // yourUsername
            }
            else {
                mySo.clear();
                trace("cleared: " + mySo.data.username); // undefined
            }
        }
    }
}

Ferme la connexion entre un objet partagé distant et le serveur. Si un objet partagé distant est persistant localement, l’utilisateur peut modifier la copie locale de l’objet après l’appel de cette méthode. Toute modification apportée à l’objet local est envoyée au serveur à la prochaine connexion de l’utilisateur à l’objet partagé distant.

Se connecte à un objet partagé distant sur un serveur par l’intermédiaire d’un objet NetConnection spécifié. Utilisez cette méthode après un appel à getRemote(). Lorsque la connexion est réussie, l’événement sync est distribué.

Avant de tenter d’utiliser un objet partagé distant, commencez par vérifier la présence d’erreurs éventuelles à l’aide d’une instruction try..catch..finally. Ensuite, écoutez et gérez l’événement sync avant de modifier l’objet partagé. Toute modification effectuée localement, avant la distribution de l’événement sync, peut être perdue.

Appelez la méthode connect() pour vous connecter à un objet partagé distant, par exemple :

     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", myNC.uri, false);
     myRemoteSO.connect(myNC);
     

Paramètres

Eléments de l’API associés

Ecrit immédiatement un objet partagé persistant localement dans un fichier local. Si vous n’utilisez pas cette méthode, Flash écrit l’objet partagé dans un fichier lorsque la session d’objet partagé se termine, c’est-à-dire lorsque le fichier SWF est fermé, lorsque l’objet partagé est effacé par l’outil de nettoyage de la mémoire car il n’est plus associé à aucune référence ou lorsque vous appelez SharedObject.clear() ou SharedObject.close().

Si cette méthode renvoie SharedObjectFlushStatus.PENDING, Flash Player ouvre une boîte de dialogue demandant à l’utilisateur d’augmenter la quantité d’espace disque disponible pour les objets de ce domaine. Pour ménager un espace permettant à la taille de l’objet partagé de croître lors d’un enregistrement ultérieur, évitant ainsi des valeurs renvoyées de PENDING, transmettez une valeur à minDiskSpace. Lorsque Flash Player tente d’écrire le fichier, il recherche le nombre d’octets transmis à minDiskSpace plutôt que l’espace nécessaire à l’enregistrement de l’objet partagé à sa taille actuelle.

Par exemple, si vous pensez qu’un objet partagé atteindra une taille maximale de 500 octets, même s’il est au départ beaucoup plus petit, transmettez 500 à minDiskSpace. Le cas échéant, Flash demandera à l’utilisateur d’affecter 500 octets d’espace disque à l’objet partagé. Une fois que l’utilisateur affecte l’espace nécessaire, Flash ne demande pas davantage d’espace lors des prochaines tentatives de purge de l’objet (tant que sa taille ne dépasse pas les 500 octets).

Une fois que l’utilisateur a répondu dans la boîte de dialogue, cette méthode est de nouveau appelée. Un événement netStatus est distribué avec une propriété code SharedObject.Flush.Success ou SharedObject.Flush.Failed.

Paramètres

Plus d’exemples

Eléments de l’API associés

package {
    import flash.net.SharedObject;

    public class SharedObject_flush {
        private var hostName:String = "yourDomain";
        private var username:String = "yourUsername";

        public function SharedObject_flush() {
            var mySo:SharedObject = SharedObject.getLocal(hostName);
            mySo.data.username = username;
            var flushResult:Object = mySo.flush();
            trace("flushResult: " + flushResult);
            trace(mySo.data.username); // yourUsername
        }
    }
}

Renvoie une référence à un objet partagé persistant localement qui est disponible uniquement pour le client actuel. Si l’objet partagé n’existe pas encore, cette méthode en crée un. Si des valeurs transmises à getLocal() sont incorrectes ou si l’appel échoue, Flash Player renvoie une exception.

Le code suivant illustre la procédure d’attribution à une variable de la référence à l’objet partagé renvoyé :

var so:SharedObject = SharedObject.getLocal("savedData");

Remarque : si l’utilisateur a choisi de ne jamais autoriser l’enregistrement local pour ce domaine, l’objet n’est pas enregistré localement, même si une valeur est spécifiée pour localPath. L’exception à cette règle est le contenu local. Un contenu local peut toujours écrire des objets partagés en provenance de domaines tiers sur un disque (domaines autres que celui de la barre d’adresse actuelle du navigateur), même s’il est interdit à un domaine tiers d’écrire des objets partagés sur un disque.

Pour éviter les conflits de noms, Flash examine l’emplacement du fichier SWF qui crée l’objet partagé. Par exemple, si un fichier SWF à l’adresse www.myCompany.com/apps/stockwatcher.swf crée un objet partagé nommé portfolio, cet objet partagé n’entre pas en conflit avec un autre objet nommé portfolio qui a été créé par un fichier SWF à l’adresse www.yourCompany.com/photoshoot.swf, étant donné que les fichiers SWF proviennent de répertoires différents.

Bien que le paramètre localPath soit facultatif, vous devez réfléchir à son utilisation, en particulier si les autres fichiers SWF doivent accéder à l’objet partagé. Si les données dans l’objet partagé sont spécifiques à un fichier SWF qui ne sera pas déplacé dans un autre emplacement, l’utilisation de la valeur par défaut prend alors tout son sens. Si d’autres fichiers SWF nécessitent un accès à l’objet partagé ou si le fichier SWF qui crée l’objet partagé est déplacé ultérieurement, la valeur de ce paramètre peut alors affecter l’accessibilité de l’objet partagé. Par exemple, si vous créez un objet partagé en réglant localPath sur la valeur par défaut du chemin complet du fichier SWF, aucun autre fichier SWF ne pourra accéder à cet objet partagé. Si vous déplacez par la suite le fichier SWF d’origine dans un autre emplacement, il ne pourra plus accéder aux données déjà enregistrées dans l’objet partagé.

Pour éviter de limiter inopinément l’accès à un objet partagé, utilisez le paramètre localpath. La meilleure option consiste à définir le paramètre localPath sur /. Cette opération rend l’objet partagé accessible à tous les fichiers SWF du domaine, mais augmente la probabilité de conflits de noms avec d’autres objets partagés dans ce domaine. Une autre option, plus restrictive, consiste à faire suivre localPath de noms de dossier figurant dans le chemin complet du fichier SWF. Prenons l’exemple de l’objet partagé portfolio créé par le fichier SWF à l’adresse www.myCompany.com/apps/stockwatcher.swf. Vous pouvez régler le paramètre localPath sur /, /apps ou /apps/stockwatcher.swf. Vous devrez identifier l’option qui offre la meilleure flexibilité à votre application.

Lorsque vous employez cette méthode, tenez compte du modèle de sécurité suivant :

• Vous ne pouvez pas accéder à des objets partagés en franchissant les limites sandbox.
• Les utilisateurs peuvent limiter l’accès aux objets partagés via la boîte de dialogue Paramètres de Flash Player ou via le Gestionnaire des paramètres. Par défaut, une application peut créer des objets partagés contenant jusqu’à 100 Ko de données par domaine. Les administrateurs et les utilisateurs peuvent également limiter la capacité à écrire dans le système de fichiers.

Imaginons que vous publiez le contenu de fichiers SWF afin qu’il soit lu sous forme de fichiers locaux (fichiers SWF installés localement ou fichiers EXE) et que vous deviez accéder à un objet partagé spécifique à partir de plusieurs fichiers SWF locaux. Dans ce cas, sachez que, pour ce qui est des fichiers locaux, il est possible d’utiliser deux emplacements différents pour le stockage des objets partagés. Le domaine utilisé dépend des autorisations de sécurité accordées au fichier local qui a créé l’objet partagé. Les fichiers locaux peuvent avoir trois niveaux distincts d’autorisation :

1. Accès au système de fichiers local uniquement
2. Accès au réseau uniquement
3. Accès au réseau et au système de fichiers local

Les fichiers locaux pouvant accéder au système de fichiers local (niveau 1 ou 3) stockent leurs objets partagés à un emplacement unique. Les fichiers locaux ne pouvant pas accéder au système de fichiers local (niveau 2) stockent leurs objets partagés dans un autre emplacement.

Vous pouvez empêcher un fichier SWF 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.

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

Paramètres

  ~ % & \ ; : " ' , < > ? # 
  

Plus d’exemples

Renvoie une référence à un objet partagé sur Flash Media Server auquel plusieurs clients peuvent accéder. Si l’objet partagé distant n’existe pas encore, cette méthode en crée un.

Pour créer un objet partagé distant, appelez getRemote(), puis connect() pour connecter l’objet partagé distant au serveur, comme suit :

     var nc:NetConnection = new NetConnection();
     nc.connect("rtmp://somedomain.com/applicationName");
     var myRemoteSO:SharedObject = SharedObject.getRemote("mo", nc.uri, false);
     myRemoteSO.connect(nc);
     

Pour confirmer la synchronisation des copies locale et distante de l’objet partagé, écoutez et gérez l’événement sync. Tous les clients qui souhaitent partager cet objet doivent transmettre les mêmes valeurs pour les paramètres name et remotePath.

Pour créer un objet partagé accessible au client actuel uniquement, utilisez SharedObject.getLocal().

Paramètres

    ~ % & \ ; :  " ' , > ? ? #

Plus d’exemples

Eléments de l’API associés

Diffuse un message à tous les clients connectés à l’objet partagé distant, y compris au client qui a envoyé le message. Pour traiter le message et y répondre, créez une fonction de rappel associée à l’objet partagé.

Paramètres

Indique au serveur que la valeur d’une propriété a changé dans l’objet partagé. Cette méthode marque les propriétés comme dirty, ce qui signifie qu’elles ont été modifiées.

Pour créer les propriétés d’un objet partagé, appelez SharedObject.setProperty().

La méthode SharedObject.setProperty() implémente setDirty(). Dans la plupart des cas, par exemple lorsque la valeur d’une propriété est de type primitif, comme String ou Number, appelez setProperty() plutôt que setDirty(). En revanche, lorsque la valeur d’une propriété est un objet qui contient ses propres propriétés, appelez setDirty() pour indiquer la modification d’une valeur dans l’objet.

Paramètres

Eléments de l’API associés

Met à jour la valeur d’une propriété dans un objet partagé et indique cette modification au serveur. La méthode setProperty() marque explicitement les propriétés comme modifiées (dirty).

Pour plus d’informations sur les objets partagés distants, voir la Documentation de Flash Media Server.

Remarque : La méthode SharedObject.setProperty() implémente la méthode setDirty(). Dans la plupart des cas, par exemple lorsque la valeur d’une propriété est de type primitif, comme String ou Number, utilisez setProperty() plutôt que setDirty(). En revanche, lorsque la valeur de la propriété est un objet qui contient ses propres propriétés, utilisez setDirty() pour indiquer la modification d’une valeur dans l’objet. De façon générale, il est conseillé d’appeler setProperty() plutôt que setDirty(), car setProperty() ne met à jour la valeur d’une propriété que lorsqu’elle a changé, tandis que setDirty() impose la synchronisation à tous les clients abonnés.

Paramètres

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é lorsqu’une occurrence de SharedObject publie son état ou signale une erreur. L’événement netStatus renferme une propriété info, composée d’un objet d’informations contenant des renseignements spécifiques sur l’événement, telles que la réussite ou l’échec d’une tentative de connexion ou la réussite de l’écriture de l’objet partagé dans le disque dur local.

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

Eléments de l’API associés

Distribué lorsqu’un objet partagé distant a été mis à jour par le serveur.

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

Eléments de l’API associés