ActionScript 3.0 의 프로그래밍 > Flash Player API > External API 의 사용 > 예 :ActiveX 컨테이너에 대한 External API 의 사용

예 :ActiveX 컨테이너에 대한 External API 의 사용

이 예는, External API 를 사용한, ActiveX 컨트롤을 사용하는 데스크탑 어플리케이션과 ActionScript 와의 사이의 통신을 나타내고 있습니다. 이 예에서는, ActionScript 코드 및 같은 SWF 파일을 포함해 Introvert IM 를 다시 사용하고 있기 (위해)때문에, ActionScript 의 External API 의 사용에 대해서는 설명하지 않습니다. 전술의 예를 잘 이해해 두면, 이 예를 이해하기 쉬워집니다.

이 예의 데스크탑 어플리케이션은, Microsoft Visual Studio . NET 를 사용해 C# 로 기술되고 있습니다. 설명의 중심은, ActiveX 컨트롤을 사용한 External API 의 조작 방법입니다. 이 예는, 다음 일을 나타내고 있습니다.

• Flash Player ActiveX 컨트롤을 호스팅 하고 있는 데스크탑 어플리케이션으로부터의 ActionScript 함수의 호출
• ActionScript 로부터의 함수 호출의 수신, 및 ActiveX 컨테이너에서의 그 처리
• ActiveX 컨테이너에의 메세지 송신에 Flash Player 가 사용하는 프록시 클래스를 사용한, 직렬화 XML 포맷의 상세한 비표시

Introvert IM C# 파일은 Samples/IntrovertIM_CSharp 폴더에 있습니다. 어플리케이션은, 다음의 파일로 구성되어 있습니다.

부 주제

Introvert IM C# 어플리케이션의 개요

이 어플리케이션예는, 서로 통신하는 2 개의 인스턴트 메세지 클라이언트 프로그램 (1 개은 SWF 파일내, 이제(벌써) 1 개은 Windows Forms 에 포함)을 나타내고 있습니다. 유저 인터페이스에는, Shockwave® Flash ActiveX 컨트롤의 인스턴스가 포함되어 ActionScript IM 클라이언트를 포함한 SWF 파일이 로드 됩니다. 이 인터페이스에는, Windows Forms IM 클라이언트를 구성하는 몇개의 텍스트 필드도 포함되어 있습니다. 1 개은 메세지 입력용 필드 (MessageText)에서, 이제(벌써) 1 개은 클라이언트간에 송신되는 메세지의 복제 (Transcript)를 표시해, 제 3 의 필드 (Status)는 SWF IM 클라이언트로 설정된 availability 스테이터스를 표시합니다.

Shockwave Flash ActiveX 컨트롤의 포함

Shockwave Flash ActiveX 컨트롤을 독자적인 Windows Forms 어플리케이션에 포함하려면 , 최초로 그것을 Microsoft Visual Studio Toolbox 에 추가할 필요가 있습니다.

컨트롤을 툴 박스에 추가하려면 :

1. Visual Studio Toolbox 를 엽니다.
2. Visual Studio 2003 의 [Windows 폼] 섹션, 또는 Visual Studio 2005 의 임의의 섹션을 오른쪽 클릭합니다. Visual Studio 2003 에서는 context menu로 [항목의 추가/삭제] 를 선택합니다. Visual Studio 2005 에서는 [항목의 선택...] (을)를 선택합니다.

   이것에 의해,[툴 박스의 커스터마이즈] (2003) 또는 [툴 박스 항목의 선택] (2005) 다이알로그 박스가 표시됩니다.

3. [COM 컴퍼넌트] 탭을 선택합니다. 이 탭에는, Flash Player ActiveX 컨트롤 등, 그 컴퓨터에 있는 모든 COM 컴퍼넌트가 표시됩니다.
4. 스크롤 해 Shockwave Flash Object 를 찾아, 선택합니다.

   이 항목이 표시되지 않는 경우는, 시스템에 Flash Player ActiveX 가 설치(Install) 되고 있든가 확인해 주세요.

ActionScript 로부터 ActiveX 컨테이너에의 통신에 대해

External API 를 사용한 ActiveX 컨테이너 어플리케이션과의 통신은, Web 브라우저와의 통신과 같게 됩니다만, 큰 차이가 1 개 있습니다. 전술한 것처럼, ActionScript 가 Web 브라우저와 통신하는 경우, 개발자가 고려하고 있는 한, 함수는 직접 불려 갑니다. 함수의 호출 방법과 응답 방법의 자세한 것은, 플레이어간에 수수할 수 있도록(듯이) 포맷 되어 브라우저는 인식되지 않습니다. 다만, ActiveX 컨테이너 어플리케이션과의 통신에 External API 가 사용되는 경우, Flash Player 는 메세지 (함수 호출 및 반환값)를 있는 XML 포맷으로 어플리케이션에 송신해, 컨테이너 어플리케이션으로부터의 함수 호출과 반환값에 같은 XML 포맷이 사용될 필요가 있습니다. ActiveX 컨테이너 어플리케이션의 개발자는, 적절한 포맷의 함수 호출과 응답을 인식해, 작성 가능한 코드를 작성할 필요가 있습니다.

샘플의 Introvert IM C# 에는, 메세지의 formatting 방지의 가능한 클래스가 포함되어 있습니다만, ActionScript 함수의 호출 및 ActionScript 로부터의 호출의 수신시는, 표준의 데이터형을 사용해 조작할 수가 있습니다. ExternalInterfaceProxy 클래스를 다른 헬퍼 클래스와 조합하는 곳의 기능이 제공되어 임의의 . NET 프로젝트로 재이용하는 것으로 External API 와의 통신이 용이하게 됩니다.

다음의 코드는, 메인 어플리케이션 폼 (AppForm.cs)으로부터 인용한 것으로, ExternalInterfaceProxy 클래스를 사용해 실현된 단순한 조작을 나타내고 있습니다.

public class AppForm : System.Windows.Forms.Form
{
    ...
    private ExternalInterfaceProxy proxy;
    ...
    public AppForm()
    {
        ...
        /* 이 어플리케이션을 등록하는 것으로, 프록시가 ActionScript 로부터의
             호출을 수신했을 때에 통지를 수신한다 */
        proxy = new ExternalInterfaceProxy(IntrovertIMApp);
        proxy.ExternalInterfaceCall += new ExternalInterfaceCallEventHandler(proxy_ExternalInterfaceCall);
        ...
    }
    ...

이 어플리케이션에서는,proxy 라는 이름의 ExternalInterfaceProxy 인스턴스가 선언 및 작성되어 그 참조가 유저 인터페이스의 Shockwave Flash ActiveX 컨트롤에게 건네집니다 (IntrovertIMApp). 다음에, 프록시의 ExternalInterfaceCall 이벤트를 수신하기 위한 proxy_ExternalInterfaceCall() 메소드가, 코드로 등록됩니다. 이 이벤트는, Flash Player 로부터 함수 호출이 있었을 때에 ExternalInterfaceProxy 클래스에 의해 송출(Dispatch)됩니다. 이 이벤트에의 예약(subscribe)는, C# 코드가 ActionScript 로부터의 함수 호출을 수신해, 응답하는 방법이 되어 있습니다.

ActionScript 로부터 함수 호출이 있으면, ExternalInterfaceProxy 인스턴스 (proxy)는 그 호출을 수신해, 그것을 XML 포맷으로 변환합니다. 그리고, 프록시의 ExternalInterfaceCall 이벤트의 Listener가 되고 있는 오브젝트에 통지합니다. AppForm 클래스의 경우,proxy_ExternalInterfaceCall() 메소드에서는 다음과 같이 이벤트가 처리됩니다.

    /// <summary>
    /// SWF 로 ActionScript ExternalInterface 호출을 하면,
    /// 프록시로부터 불려 간다
    /// </summary>
    private object proxy_ExternalInterfaceCall(object sender, ExternalInterfaceCallEventArgs e)
    {
        switch (e.FunctionCall.FunctionName)
        {
            case "isReady":
                return isReady();
            case "setSWFIsReady":
                setSWFIsReady();
                return null;
            case "newMessage":
                newMessage((string) e.FunctionCall.Arguments[0]);
                return null;
            case "statusChange":
                statusChange();
                return null;
            default:
                return null;
        }
    }
    ...

이 메소드는 ExternalInterfaceCallEventArgs 인스턴스에게 건네집니다. 이 예에서는 인스턴스명이 e 입니다. 이것에 의해, 이 오브젝트가 ExternalInterfaceCall 클래스의 인스턴스인 FunctionCall properties 를 취득합니다.

ExternalInterfaceCall 인스턴스가, 2 개의 properties 를 가지는 단순한 값오브젝트입니다. FunctionName properties 에는, ActionScript ExternalInterface.Call() 명령문(statement)로 지정된 함수명이 포함되고 있습니다. ActionScript 에 어떠한 파라미터가 추가되면, 그 파라미터는 ExternalInterfaceCall 오브젝트의 Arguments properties 에 포함됩니다. 이 경우, 이벤트를 처리하는 메소드는, 트래픽 매니저와 같이 기능하는 switch 명령문(statement)입니다. FunctionName properties 의 값 (e.FunctionCall.FunctionName)에 의해, AppForm 클래스의 어느 메소드가 불려 갈지가 정해집니다.

전술의 코드의 switch 명령문(statement)의 브랜치(branch)는, 일반적인 메소드 호출 시나리오를 나타내고 있습니다. 예를 들어, 모든 메소드는 값을 ActionScript 에 돌려줄까 (isReady() 메소드 호출 등),null 를 돌려줄 (다른 메소드 호출의 경우) 필요가 있습니다. ActionScript 로부터 건네받은 파라미터의 액세스는,newMessage() 메소드 호출에 나타나고 있습니다 (Arguments 배열의 제 1 엘리먼트인 파라미터 e.FunctionCall.Arguments[0] 으로 건네받습니다).

ExternalInterfaceProxy 클래스를 사용한 C# 로부터의 ActionScript 함수의 호출은, ActionScript 로부터의 함수 호출의 수신보다 훨씬 단순합니다. ActionScript 함수를 호출하려면 , 다음과 같이 ExternalInterfaceProxy 인스턴스의 Call() 메소드를 사용합니다.

    /// <summary>
    /// [송신] 버튼이 밀리면 불려 가
    /// MessageText 텍스트 필드의 값이 파라미터로서 건네받는다
    /// </summary>
    /// <param name="message">송신하는 메세지 </param>
    private void sendMessage(string message)
    {
        if (swfReady)
        {
            ...
            // ActionScript 의 newMessage 함수를 호출한다
            proxy.Call("newMessage", message);
        }
    }
    ...
    /// <summary>
    /// ActionScript 함수를 호출해 현재의 "availability" 스테이터스를
    /// 취득해, 그것을 텍스트 필드에 기입한다
    /// </summary>
    private void updateStatus()
    {
        Status.Text = (string) proxy.Call("getStatus");
    }
    ...
}

이 예로 나타나고 있도록(듯이), ExternalInterfaceProxy 클래스의 Call() 메소드는, ActionScript 로 거기에 상당하는 ExternalInterface.Call() 에 매우 자주(잘) 닮았습니다. 제 1 파라미터는 string로, 호출하는 함수의 이름이 됩니다. 그 외의 파라미터 (여기에는 나타나고 있지 않습니다)도 ActionScript 함수에게 건네집니다. ActionScript 함수로부터 값이 돌려주어졌을 경우, 그 값은 Call() 메소드로 돌려주어집니다 (전술의 예).

ExternalInterfaceProxy 클래스의 내부

ActiveX 컨트롤의 프록시 래퍼를 사용하는 것은 반드시 중요하지 않고, 독자적인 프록시 class (예를 들어, 다른 프로그램 언어나 다른 플랫폼용)를 작성할 수도 있습니다. 프록시의 작성에 대해서는 여기서 자세하게 설명합니다만, 이 예에 있어서의 프록시 클래스의 내부 처리를 이해하는 것은 유익합니다.

Shockwave Flash ActiveX 컨트롤의 CallFunction() 메소드를 사용하면, External API 를 사용해 ActiveX 컨테이너로부터 ActionScript 함수를 호출할 수가 있습니다. 다음의 ExternalInterfaceProxy 클래스의 Call() 메소드의 일부는, 이것을 나타내고 있습니다.

/* Shockwave Flash ActiveX 컨트롤의 "_flashControl" 로,
    SWF 의 ActionScript 함수를 호출한다 */
string response = _flashControl.CallFunction(request);

이 코드 부분에서,_flashControl 은 Shockwave Flash ActiveX 컨트롤입니다. ActionScript 함수 호출은,CallFunction() 메소드를 사용해 행해집니다. 이 메소드에는 파라미터가 1 개 있어 (이 예에서는 request), 이 파라미터는 XML 포맷 된 인스트럭션이 포함된 string입니다. 불려 가는 ActionScript 함수의 이름 및 임의의 파라미터가 포함되어 있습니다. ActionScript 로부터 돌려주어진 모든 값은 XML 포맷 string에 encode 되어CallFunction() 호출의 반환값으로서 돌려 보내집니다. 이 예에서는, 이 XML string가 response 변수에 포함됩니다.

ActionScript 로부터의 함수 호출의 수신은, 단계적인 순서로 행해집니다. ActionScript 로부터 함수 호출이 있으면, Shockwave Flash ActiveX 컨트롤은 FlashCall 이벤트를 송출(Dispatch)하기 위해(때문에), SWF 파일로부터의 호출을 수신하기 위한 class (ExternalInterfaceProxy 클래스등)에서는 그 이벤트용의 핸들러를 정의해 둘 필요가 있습니다. ExternalInterfaceProxy 클래스에서는, 이 이벤트 핸들러 함수의 이름은 _flashControl_FlashCall() 로, class constructor　 　 내의 이벤트를 기다리도록(듯이) 등록되어 있습니다.

private AxShockwaveFlash _flashControl;

public ExternalInterfaceProxy(AxShockwaveFlash flashControl)
{
    _flashControl = flashControl;
    _flashControl.FlashCall += new _IShockwaveFlashEvents_FlashCallEventHandler(_flashControl_FlashCall);
}
...
private void _flashControl_FlashCall(object sender, _IShockwaveFlashEvents_FlashCallEvent e)
{
    /* 이벤트 오브젝트의 request  properties  ("e.request")를 사용해
        액션을 실행한다 */
    ...
    /* 값을 ActionScript 에 돌려준다
        돌려주어진 값은, XML 포맷 string로서 encode 할 필요가 있다 */
    _flashControl.SetReturnValue(encodedResponse);
}

이벤트 오브젝트 (e)에는 request properties (e.request)가 있어, 이 properties 는 함수명이나 파라미터 등, 함수 호출해에 관한 정보가 XML 포맷으로 포함된 캐릭터 라인이 되어 있습니다. 이 정보를 컨테이너로 사용하면, 실행하는 코드를 판별할 수 있습니다. ExternalInterfaceProxy 클래스에서는, 요구가 XML 포맷화등 ExternalInterfaceCall 오브젝트에 변환되어 같은 정보가 액세스 하기 쉬운 형식에서 제공됩니다. ActiveX 컨트롤의 SetReturnValue() 메소드를 사용하면, 함수의 결과를 ActionScript 의 호출 측에 돌려줄 수가 있습니다. 이 경우도, 얻을 수 있던 파라미터를 External API 로 사용되는 XML 포맷에 encode 할 필요가 있습니다.

External API 의 XML 포맷

전술과 같이, Shockwave Flash ActiveX 를 호스트 하는 어플리케이션과 ActionScript 와의 사이의 통신에서는, 함수 호출과 값을 encode 하기 위해서 전용의 XML 포맷이 사용됩니다. 샘플의 Introvert IM C# 에서는, ExternalInterfaceProxy 클래스에 의해, 어플리케이션 폼내의 코드로 이 포맷을 무시해, 값을 직접 조작할 수 있게 되어 있습니다. 이것을 실현하기 (위해)때문에, ExternalInterfaceProxy 클래스에서는 ExternalInterfaceSerializer 클래스의 메소드를 사용해, 실제로 XML 메세지를 . NET 오브젝트로 변환하고 있습니다. ExternalInterfaceSerializer 클래스에는, 다음의 4 개의 public 메소드가 있습니다.

• EncodeInvoke() 인수의 함수명과 C# ArrayList 를 적절한 XML 포맷에 encode 합니다.
• EncodeResult() 결과치를 적절한 XML 포맷에 encode 합니다.
• DecodeInvoke() ActionScript 로부터의 함수 호출을 디코드합니다. FlashCall 이벤트 오브젝트의 request properties 는 DecodeInvoke() 메소드에게 건네져 이 메소드로 호출이 ExternalInterfaceCall 오브젝트에 변환됩니다.
• DecodeResult() ActionScript 함수의 호출의 결과로서 수신한 XML 를 디코드합니다.

External API 로 사용되는 XML 포맷에는 2 개의 부분이 있습니다. 1 개의 포맷은, 함수 호출을 나타내기 위해서(때문에) 사용됩니다. 이제(벌써) 1 개의 포맷은 개개의 값을 나타내고 있습니다. 이 포맷은, 함수의 파라미터 및 함수의 반환값에 사용됩니다. 함수 호출용의 XML 포맷은, ActionScript 와의 사이의 호출에 사용됩니다. ActionScript 로부터의 함수 호출에 대해서, Flash Player 는 XML 를 컨테이너에 건네줍니다. 컨테이너로부터의 호출에 대해서는, Flash Player 는 이 포맷으로 XML string를 건네주는 컨테이너 어플리케이션이 필요하게 됩니다. 다음의 XML 는, XML 포맷 된 함수 호출의 예를 나타내고 있습니다.

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

루트 노드는 <invoke> 노드입니다. 여기에는 2 개의 속성이 있어,name 는 함수 호출의 이름을 나타내,returntype 는 항상 xml 가 됩니다. 함수 호출에 파라미터가 포함되어 있는 경우,<invoke> 노드에는 <arguments> 자 노드가 생깁니다. 한층 더 그 자식 (child) 노드는, 다음에 설명하는 개별의 값포맷을 사용해 포맷 된 파라미터가 됩니다.

함수의 파라미터나 함수의 반환값등의 개개의 값으로는, 실제의 값에 가세해 데이터형 정보를 포함한 formatting 스킴이 사용됩니다.