ExternalInterface 클래스 사용

Flash Player 9 이상, Adobe AIR 1.0 이상

ActionScript와 컨테이너 응용 프로그램 간의 통신은 다음 두 가지 양식 중 하나를 사용할 수 있습니다. 즉, ActionScript가 컨테이너에 정의된 코드(예: JavaScript 함수)를 호출하거나 컨테이너의 코드가 호출 가능한 것으로 지정된 ActionScript 함수를 호출할 수 있습니다. 두 경우에 호출되는 코드에 정보를 전송하고 호출을 만드는 코드에 결과를 반환할 수 있습니다.

ExternalInterface 클래스에는 이러한 통신을 쉽게 하기 위한 두 개의 정적 속성과 두 개의 정적 메서드가 포함되어 있습니다. 이러한 속성과 메서드를 사용하여 외부 인터페이스 연결에 대한 정보를 가져오고, ActionScript에서 컨테이너의 코드를 실행하고, 컨테이너에서 ActionScript 함수를 호출할 수 있는 상태로 만듭니다.

외부 컨테이너에 대한 정보 얻기

ExternalInterface.available 속성은 현재 Flash Player가 외부 인터페이스를 제공하는 컨테이너에 있는지 여부를 나타냅니다. 외부 인터페이스를 사용할 수 있는 경우 이 속성은 true이고, 그렇지 않으면 false입니다. ExternalInterface 클래스에서 다른 함수를 사용하기 전에 항상 다음과 같이 현재 컨테이너에서 외부 인터페이스 통신을 지원하는지 확인해야 합니다.

if (ExternalInterface.available) 
{ 
    // Perform ExternalInterface method calls here. 
}
참고: ExternalInterface.available 속성은 현재 컨테이너가 ExternalInterface 연결을 지원하는 유형인지 여부를 보고합니다. 현재 브라우저에서 JavaScript가 활성화되어 있는지 여부는 표시되지 않습니다.

ExternalInterface.objectID 속성을 사용하면 Flash Player 인스턴스의 고유한 ID(특히 Internet Explorer에서 object 태그의 id 특성 또는 NPRuntime 인터페이스를 사용하는 브라우저에서 embed 태그의 name 특성)를 확인할 수 있습니다. 이 고유한 ID는 브라우저에 있는 현재 SWF 문서를 나타내고 SWF 문서에 대한 참조를 만드는 데 사용할 수 있습니다. 예를 들어 컨테이너 HTML 페이지에서 JavaScript 함수를 호출할 때 사용할 수 있습니다. Flash Player 컨테이너가 웹 브라우저가 아니면 이 속성은 null입니다.

ActionScript에서 외부 코드 호출

ExternalInterface.call() 메서드는 컨테이너 응용 프로그램에서 코드를 실행합니다. 이때 컨테이너 응용 프로그램에서 호출할 함수 이름이 포함된 문자열이 매개 변수로 반드시 필요합니다. ExternalInterface.call() 메서드에 전달된 그 밖의 매개 변수는 함수 호출의 매개 변수로 컨테이너에 전달됩니다.

// 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);

컨테이너가 HTML 페이지이면 이 메서드는 해당 HTML 페이지의 script 요소에 정의된 이름으로 JavaScript 함수를 호출합니다. JavaScript 함수의 반환 값은 ActionScript로 다시 전달됩니다.

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

컨테이너가 다른 ActiveX 컨테이너인 경우 이 메서드로 인해 Flash Player ActiveX 컨트롤이 해당 FlashCall 이벤트를 전달합니다. 지정된 함수 이름 및 매개 변수는 Flash Player에서 XML 문자열로 직렬화합니다. 컨테이너는 event 객체의 request 속성에서 이 정보에 액세스할 수 있으며 이 정보를 통해 자신의 코드를 어떻게 실행할지 결정합니다. 컨테이너 코드는 ActionScript에 값을 반환하기 위해 ActiveX 객체의 SetReturnValue() 메서드를 호출하여 그 결과(XML 문자열로 직렬화된 결과)를 해당 메서드의 매개 변수로 전달합니다. 이 통신에 사용되는 XML 형식에 대한 자세한 내용은 외부 API의 XML 형식을 참조하십시오.

컨테이너가 웹 브라우저인지 또는 다른 ActiveX 컨테이너인지 관계없이 호출이 실패하거나 컨테이너 메서드에서 반환 값을 지정하지 않으면 null이 반환됩니다. 포함 환경이 호출 코드가 액세스할 수 없는 보안 샌드박스에 속하는 경우 ExternalInterface.call() 메서드가 SecurityError 예외를 발생시킵니다. 컨테이너 환경에서 allowScriptAccess에 적절한 값을 설정하면 이 문제를 해결할 수 있습니다. 예를 들어 HTML 페이지에서 allowScriptAccess의 값을 변경하려면 objectembed 태그에서 해당 특성을 편집합니다.

컨테이너에서 ActionScript 코드 호출

컨테이너는 함수에 있는 ActionScript 코드만 호출할 수 있고 다른 ActionScript 코드는 호출할 수 없습니다. 컨테이너 응용 프로그램에서 ActionScript 함수를 호출하려면 ExternalInterface 클래스로 함수를 등록한 다음 컨테이너의 코드에서 호출해야 합니다.

먼저 ActionScript 함수를 등록하여 컨테이너에서 사용할 수 있도록 나타내야 합니다. 다음과 같이 ExternalInterface.addCallback() 메서드를 사용합니다.

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

addCallback() 메서드는 두 가지 매개 변수를 사용합니다. 먼저 문자열로 된 함수 이름에 의해 컨테이너에서 함수를 인식하게 됩니다. 두 번째 매개 변수는 컨테이너가 정의된 함수 이름을 호출할 때 실행될 실제 ActionScript 함수입니다. 이러한 이름은 고유하므로 실제 ActionScript 함수에 다른 이름이 있더라도 컨테이너에서 사용할 함수 이름을 지정할 수 있습니다. 이것은 함수 이름을 모르는 경우, 예를 들어 익명 함수가 지정되거나 호출할 함수가 런타임에 확인되는 경우에 특히 유용합니다.

ActionScript 함수는 ExternalInterface 클래스로 등록되었으므로 컨테이너에서 실제로 이 함수를 호출할 수 있습니다. 실행 방법은 컨테이너 유형에 따라 다양합니다. 예를 들어 웹 브라우저의 JavaScript 코드에서 ActionScript 함수는 Flash Player 브라우저 객체의 메서드(object 또는 embed 태그를 나타내는 JavaScript 객체의 메서드)와 마찬가지로 등록된 함수 이름을 사용하여 호출됩니다. 즉, 로컬 함수가 호출되는 것처럼 매개 변수가 전달되고 결과가 반환됩니다.

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

또는 데스크톱 응용 프로그램에서 실행되는 SWF 파일에서 ActionScript 함수를 호출할 때 등록된 함수 이름 및 매개 변수를 XML 형식 문자열로 직렬화해야 합니다. 그러면 XML 문자열을 매개 변수로 ActiveX 컨트롤의 CallFunction() 메서드를 호출하는 방식으로 호출이 실제로 수행됩니다. 이 통신에 사용되는 XML 형식에 대한 자세한 내용은 외부 API의 XML 형식을 참조하십시오.

두 경우 모두 ActionScript 함수의 반환 값은 다시 컨테이너 코드로 전달됩니다. 호출자가 브라우저의 JavaScript인 경우에는 직접 값으로 전달되고 호출자가 ActiveX 컨테이너인 경우에는 XML 형식 문자열로 직렬화되어 전달됩니다.

외부 API의 XML 형식

Shockwave Flash ActiveX 컨트롤을 호스팅하는 ActionScript와 응용 프로그램 간의 통신은 특정 XML 형식을 사용하여 함수 호출과 값을 인코딩합니다. 외부 API에서 사용하는 XML 형식에는 두 부분이 있습니다. 한 가지 형식은 함수 호출을 나타내는 데 사용됩니다. 다른 형식은 개별 값을 나타내는 데 사용됩니다. 이 형식은 함수의 매개 변수와 함수 반환 값에 사용됩니다. 함수 호출의 XML 형식은 ActionScript에서 송수신되는 호출에 사용됩니다. ActionScript에서 함수를 호출하는 경우에는 Flash Player가 XML을 컨테이너에 전달하고, 컨테이너에서 호출하는 경우에는 Flash Player에서 컨테이너 응용 프로그램이 이 형식으로 XML 문자열을 전달해야 합니다. 다음 XML 프래그먼트는 XML 형식의 함수 호출을 보여 줍니다.

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

루트 노드는 invoke 노드입니다. 이 노드에는 호출할 함수 이름을 나타내는 name과 항상 xmlreturntype의 두 가지 특성이 있습니다. 함수 호출에 매개 변수가 포함되는 경우 invoke 노드에 자식 arguments 노드가 포함되고 그 노드의 자식 노드는 아래 설명하는 개별 값 형식의 매개 변수 값이 됩니다.

함수 매개 변수와 함수 반환 값 등의 개별 값은 실제 값뿐 아니라 데이터 형식 정보가 포함된 형식 지정 스키마를 사용합니다. 다음 표에는 ActionScript 클래스 및 해당 데이터 유형의 값을 인코딩하는 데 사용되는 XML 형식이 나와 있습니다.

ActionScript 클래스/값

C# 클래스/값

형식

설명

null

null

<null/>

 

Boolean true

bool true

<true/>

 

Boolean false

bool false

<false/>

 

String

string

<string>문자열 값</string>

 

Number, int, uint

single, double, int, uint

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

Array(요소는 혼합 유형일 수 있습니다.)

ArrayList 또는 object[] 등 혼합 유형 요소를 허용하는 컬렉션

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

property 노드는 개별 요소를 정의하고 id 특성은 숫자 0부터 시작하는 인덱스입니다.

Object

문자열 키가 있는 HashTable처럼 문자열 키와 객체 값이 있는 사전

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

property 노드는 개별 속성을 정의하고 id 특성은 속성 이름(문자열)입니다.

기타 기본 제공 또는 사용자 정의 클래스

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

ActionScript에서는 다른 객체를 null 또는 빈 객체로 인코딩합니다. 두 경우 모두 속성 값이 사라집니다.

참고: 이 표에서는 예제로 ActionScript 클래스와 함께 해당 C# 클래스를 보여 줍니다. 그러나 외부 API는 ActiveX 컨트롤을 지원하는 모든 프로그래밍 언어 또는 런타임 통신에 사용될 수 있으며 C# 응용 프로그램에만 사용하는 것이 아닙니다.

외부 API와 ActiveX 컨테이너 응용 프로그램을 사용하여 직접 응용 프로그램을 작성할 때는 네이티브 함수 호출을 직렬화된 XML 형식으로 변환하는 작업을 수행할 프록시를 작성하는 것이 편하다는 것을 알게 될 것입니다. C#으로 작성된 proxy 클래스 예제는 ExternalInterfaceProxy 클래스 내부를 참조하십시오.