Utilisation de la classe ExternalInterface

La propriété ExternalInterface.available indique si Flash Player se trouve dans un conteneur offrant une interface externe. Si l’interface externe est disponible, cette propriété est true ; sinon, elle est false . Avant d’utiliser toute autre fonctionnalité de la classe ExternalInterface, vous devez toujours vérifier que le conteneur actif prend en charge la communication avec l’interface externe, comme suit :

if (ExternalInterface.available) 
{ 
    // Perform ExternalInterface method calls here. 
}

La propriété ExternalInterface.objectID vous permet de déterminer l’identifiant unique de l’occurrence Flash Player (c’est-à-dire, l’attribut id de la balise object dans Internet Explorer ou l’attribut name de la balise embed dans les navigateurs utilisant l’interface NPRuntime). Cet identifiant unique représente le document SWF actif dans le navigateur et permet d’y faire référence, par exemple si vous appelez une fonction JavaScript dans une page HTML conteneur. Si le conteneur Flash Player n’est pas un navigateur Web, la propriété est null .

La méthode ExternalInterface.call() exécute le code dans l’application conteneur. Elle nécessite au moins un paramètre, une chaîne contenant le nom de la fonction à appeler dans cette application. Tout paramètre supplémentaire transmis à la méthode ExternalInterface.call() est retransmis au conteneur comme paramètres de l’appel de fonction.

// calls the external function "addNumbers" 
// passing two parameters, and assigning that function's result 
// to the variable "result" 
var param1:uint = 3; 
var param2:uint = 7; 
var result:uint = ExternalInterface.call("addNumbers", param1, param2);

Si le conteneur est une page HTML, la méthode appelle la fonction JavaScript avec le nom spécifié, qui doit être défini dans un élément script de la page HTML. La valeur de retour de la fonction JavaScript est retransmise à ActionScript.

<script language="JavaScript"> 
    // adds two numbers, and sends the result back to ActionScript 
    function addNumbers(num1, num2) 
    { 
        return (num1 + num2); 
    } 
</script>

Si le conteneur est un autre conteneur ActiveX, le contrôle ActiveX Flash Player distribue alors son événement FlashCall . Flash Player sérialise le nom de fonction spécifié et les éventuels paramètres dans une chaîne XML. Le conteneur peut accéder à ces informations dans la propriété request de l’objet événement, puis les utiliser pour déterminer comment il doit exécuter son propre code. Pour renvoyer une valeur à ActionScript, le code conteneur appelle la méthode SetReturnValue() de l’objet ActiveX et transmet le résultat (sérialisé dans une chaîne XML) comme paramètre de cette méthode. Pour plus d’informations sur le format XML utilisé pour cette communication, voir Format XML de l’API externe .

Que le conteneur soit un navigateur Web ou un autre conteneur ActiveX, si l’appel échoue ou que la méthode conteneur ne spécifie aucune valeur de retour, la valeur null est alors renvoyée. La méthode ExternalInterface.call() renvoie une exception SecurityError si l’environnement conteneur appartient à un sandbox de sécurité auquel le code appelant n’a pas accès. Vous pouvez contourner ce problème en attribuant à allowScriptAccess une valeur adaptée dans l’environnement conteneur. Par exemple, vous changez la valeur de allowScriptAccess dans une page HTML, vous devez modifier l’attribut approprié dans les balises object et embed .

Un conteneur peut uniquement appeler du code ActionScript compris dans une fonction, et aucun autre code ActionScript. Pour appeler une fonction ActionScript à partir de l’application conteneur, deux opérations sont nécessaires : enregistrer la fonction auprès de la classe ExternalInterface, puis l’appeler à partir du code du conteneur.

Dans un premier temps, vous devez enregistrer votre fonction ActionScript pour indiquer qu’elle doit être mise à disposition du conteneur. Pour ce faire, utilisez la méthode ExternalInterface.addCallback() comme suit :

function callMe(name:String):String 
{ 
    return "busy signal"; 
} 
ExternalInterface.addCallback("myFunction", callMe);

La méthode addCallback() prend deux paramètres : le premier, un nom de fonction sous forme de chaîne, correspond au nom de la fonction pour le conteneur. Le second paramètre est la fonction ActionScript elle-même, qui doit s’exécuter lorsque le conteneur appelle le nom de fonction défini. Comme ces noms sont différents, le nom que le conteneur utilise peut être différent du véritable nom de la fonction ActionScript. Cela vous servira particulièrement si vous ne connaissez pas le nom de la fonction, par exemple si une fonction anonyme est spécifiée ou si la fonction à appeler est déterminée au moment de l’exécution.

Une fois que la fonction ActionScript a été enregistrée auprès de la classe ExternalInterface, le conteneur peut alors appeler la fonction. La procédure d’appel varie en fonction du type de conteneur. Par exemple, si le conteneur est du code JavaScript dans un navigateur, la fonction ActionScript est appelée avec le nom de fonction enregistré, comme s’il s’agissait d’une méthode de l’objet de navigateur Flash Player (c’est-à-dire une méthode de l’objet JavaScript représentant la balise object ou embed ). En d’autres termes, les paramètres sont transmis et le résultat est renvoyé comme si une fonction locale était appelée.

<script language="JavaScript"> 
    // callResult gets the value "busy signal" 
    var callResult = flashObject.myFunction("my name"); 
</script> 
... 
<object id="flashObject"...> 
    ... 
    <embed name="flashObject".../> 
</object>

Si vous appelez une fonction ActionScript dans un fichier SWF exécuté dans une application de bureau, le nom de fonction enregistré et les éventuels paramètres doivent être sérialisés dans une chaîne au format XML. L’appel s’effectue alors sur la méthode CallFunction() du contrôle ActiveX avec comme paramètre la chaîne XML obtenue. Pour plus d’informations sur le format XML utilisé pour cette communication, voir Format XML de l’API externe .

Dans les deux cas, la valeur de retour de la fonction ActionScript est retransmise au code du conteneur, directement sous forme de valeur si l’appelant est un code JavaScript dans un navigateur ou sous forme de chaîne XML s’il s’agit d’un conteneur ActiveX.

La communication entre ActionScript et une application hébergeant le contrôle Active X Shockwave Flash nécessite un format XML spécifique qui servira à convertir les appels de fonction et les valeurs. Le format XML utilisé par l’API externe se divise en deux parties. L’une est destinée à représenter les appels de fonction. L’autre sert à représenter des valeurs individuelles ; ce format s’applique aux paramètres des fonctions comme aux valeurs de retour. Le format XML des appels de fonction est utilisé pour les appels en provenance et à destination d’ActionScript. Pour un appel de fonction issu d’ActionScript, Flash Player transmet les informations XML au conteneur ; pour un appel provenant du conteneur, Flash Player attend de l’application une chaîne XML du même format. L’extrait XML suivant donne un exemple d’appel de fonction formaté :

<invoke name="functionName" returntype="xml"> 
    <arguments> 
        ... (individual argument values) 
    </arguments> 
</invoke>

Le nœud racine est le nœud invoke . Il possède deux attributs : name indique le nom de la fonction à appeler et returntype a toujours la valeur xml . Si l’appel de fonction inclut des paramètres, le nœud invoke possède un nœud enfant arguments , dont les enfants seront les valeurs de paramètres formatées à l’aide du format de valeur individuelle expliqué ci-après.

Les valeurs individuelles, notamment les paramètres de fonction et les valeurs de retour, utilisent un format qui comprend des informations sur le type de données, en plus des valeurs elles-mêmes : Le tableau suivant répertorie les classes ActionScript et le format XML utilisé pour coder des valeurs de ce type de données :

<number>27.5</number> 
<number>-12</number>

<array> 
    <property id="0"> 
        <number>27.5</number> 
    </property> 
    <property id="1"> 
        <string>Hello there!</string> 
    </property> 
    ... 
</array>

<object> 
    <property id="name"> 
        <string>John Doe</string> 
    </property> 
    <property id="age"> 
        <string>33</string> 
    </property> 
    ... 
</object>

<null/> or  
<object></object>

Lorsque vous créez vos propres applications à l’aide de l’API externe avec une application conteneur ActiveX, il est commode d’écrire un proxy qui effectuera la tâche de conversion des appels de fonction native au format XML sérialisé. Pour consulter un exemple de classe proxy écrite dans C#, voir Fonctionnement interne de la classe ExternalInterfaceProxy.