Getting Started with Flash Communication Server Macromedia Flash Communication Server MX ™ ™ macromedia ®
Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fonto
CONTENTS CHAPTER 1 Introducing Flash Communication Server .............................5 Flash Communication Server editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About this manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guide to instructional media. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using additional resources . . . . . . . . . . . . . . . . .
Contents
CHAPTER 1 Introducing Flash Communication Server Welcome to Macromedia Flash Communication Server MX—the easiest way to create rich communication applications in Macromedia Flash MX. Flash Communication Server lets two or more people participate in a real-time conversation using text, audio, or video. For example, you can use Flash Communication Server for meetings, online communities, customer support, sales support, training, remote presence, or instant messaging.
The Flash Communication Server instructional media includes the following documentation: • This manual, Getting Started with Flash Communication Server, explains how to install the server and provides an overview of the software architecture. You can find the PDF version of this manual on the Flash Communication Server CD (FlashCom_GetStarted.pdf ).
Using additional resources The Flash Communication Server Support Center website at www.macromedia.com/go/ flashcom_support is updated regularly with the latest information on Flash Communication Server, plus advice from expert users, advanced topics, examples, tips, and other updates. Check the website often for the latest news on Flash Communication Server and how to get the most out of the program. The Flash Communication Server Designer & Developer Center at http:// www.macromedia.
Chapter 1
CHAPTER 2 Installation and Workflow Macromedia Flash Communication Server MX is a development framework and a deployment environment for rich communication applications. A developer uses Macromedia Flash MX and Flash Communication Server MX to write a communication application, and then uses Flash Communication Server to deploy the application and its scripts. Flash Player 6 is the end user’s interface. The server is available only for Microsoft® Windows.
System requirements for the Flash Player Because the client side of a Flash Communication Server application runs in Flash Player 6, you (and your users) need to run one of the following operating systems and browsers. Platform Browser Microsoft Windows 95, 98, ME Microsoft Internet Explorer 4.0 or later Netscape Navigator 4 or later Netscape 6.2 or later, default installation America Online 7 Opera 6 Microsoft Windows NT, 2000, XP, or later Microsoft Internet Explorer 4.
If you choose Production Install, you can specify both the location of your client-side application files (SWFs and HTMLs) and the location of your server-side application files (ASCs, FLVs, and FLAs). The server will look for your client-side files under \flashcom\applications in the Web server’s root directory and will look for your server-side application files under \applications under the directory you specify.
Click Finish. The Flash Communication Server service starts up. The server runs as a service, which means it runs in the background and starts automatically when the computer is started up. The installation is complete. If you choose not to start the Flash Communication Server service right away, you can start it later. See “Starting and stopping the server” in Managing Flash Communication Server.
To install the authoring components: 1 Locate the FlashComInstaller file. This file is on your installation CD, or you may have downloaded it. 2 Double-click the installer icon. The installer launches. The installer locates your existing copy of Flash MX automatically. 3 Click Install to install the authoring components and help. The installer copies files to your hard disk. When the installation is complete you can launch Flash MX and begin using the new windows to create communication applications.
How Flash Communication Server works The Flash Communication Server platform comprises the server that provides the means of communication and a Flash application (a SWF file that runs in Macromedia Flash Player) that provides the end user’s interface. You use the Flash MX authoring tool as your development environment to create applications that use Flash Communication Server services. You can also use server-side scripting to add functionality to your application.
Client connections to Flash Communication Server use the Real-Time Messaging Protocol (RTMP), which, unlike HTTP, provides a persistent socket connection for two-way communication between Flash Player clients and the Flash Communication Server.
The NetConnection object tells the Flash Player to connect to an application on the server. You can use NetConnection objects to create powerful Flash Communication Server applications. For example, you could get weather information from an application server, or share an application load with other Flash Communication Servers or application instances. The Stream object lets you handle each stream in a Flash Communication Server application.
Developer workflow If you’re a developer, you can create a Flash Communication Server application that has a client component and, if needed, a server component. The client component is a Flash MX movie (SWF) that you develop using Client-Side Communication ActionScript, and the server component is a program you write using Server-Side Communication ActionScript.
The following resources will help you develop Flash Communication Server applications. To get started in the development process, begin with Developing Communication Applications. This manual describes how to connect to the Flash Communication Server. It also supplies samples that you can use as templates for creating, testing, and debugging applications. To use these samples, open the directory where Flash MX is installed, and go to \flashcom_help\help_collateral\.
Administrator workflow If you’re an administrator, you’ll use the Administration Console to configure Flash Communication Server, set up system security, monitor usage, start and stop the server, and add users.
Chapter 2
GLOSSARY Flash Communication Server Terms Software that helps a web server process web pages that contain server-side scripts or tags. When such a page is requested, the web server sends the page to the application server for processing before sending the page to the browser. application server Common application servers include Macromedia ColdFusion MX Server, Macromedia JRun, Microsoft .NET Framework, IBM WebSphere, and Apache Tomcat.
Managing Flash Communication Server Macromedia Flash Communication Server MX ™ ™ macromedia ®
Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fonto
CONTENTS INTRODUCTION Managing Flash Communication Server .............................. 5 Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Flash Communication Server documentation . . . . . . . . . . . . . . . . . . . . . . . . . Typographical conventions . . . . . . . . . . . . . . . . . . . . .
4 Contents
INTRODUCTION Managing Flash Communication Server Macromedia Flash Communication Server MX enables one-to-one, one-to-many, many-to-one, and many-to-many communication in real time between applications created in Macromedia Flash MX. Developers create these applications using Flash MX ActionScript, a scripting language based on the same standard used by the JavaScript language.
About the Flash Communication Server documentation All Flash Communication Server documents are available in PDF format (viewable and printable with Adobe Acrobat Reader) and as HTML help. For document locations, see Getting Started with Flash Communication Server. Typographical conventions The following typographical conventions are used in this book: • Code font indicates ActionScript statements, XML tag and attribute names, and literal text used in examples.
CHAPTER 1 Installing Flash Communication Server Installing Macromedia Flash Communication Server MX is a simple process. This chapter describes the installation procedure and the files that are installed. The Flash Communication Server must be installed on Microsoft Windows 2000 Advanced Server or Windows NT 4.0 Server (SP6 or later). Installing the server Installing the server is easy.
To install Flash Communication Server: 1 Locate the FlashComInstaller.exe file. This file is on your installation CD, or you may have downloaded it. 2 Double-click the installer icon. The installer launches. 3 Enter your name and serial number in the dialog box that appears. Click OK. 4 Read the license agreement and click Yes to accept the agreement. 5 The installer suggests a default location for the server installation.
About the installed files When the server has been installed, you’ll find several other files in the installation directory. If you chose the default directory in the installer, these files are located in C:\Program Files\Macromedia\Flash Communication Server MX\. It’s a good idea to become familiar with the contents of the Flash Communication Server MX directory before continuing with this chapter. The Flash Communication Server MX directory contains these items: • FlashCom.exe is the server application.
Installing Flash authoring components on the Macintosh To install the Communication App inspector, NetConnection Debugger, and related help files into an existing copy of Macromedia Flash MX on a Macintosh computer, you use the Macintosh FlashComInstaller. To install the authoring components: 1 Locate the FlashComInstaller file. This file is on your installation CD, or you may have downloaded it. 2 Double-click the installer icon. The installer launches.
CHAPTER 2 Managing the Server As a Flash Communication Server administrator, you’ll need to perform several administrative tasks after the server is installed. This chapter describes how Macromedia Flash Communication Server MX is configured when you first install it, how to set up additional administrators, and how to monitor the server’s activity. For many of these tasks, you’ll use the Administration Console that was installed with the server. This chapter describes the Administration Console in detail.
An optional Application.xml file in the application’s directory in the flashcom application directory. If present, this file provides specific settings for the application that may be different from the settings in the server’s primary Application.xml file. For more information about the server’s configuration files, see About the configuration files. Some applications may make use of Server-Side Communication ActionScript.
When you install the server, the default flashcom application directory includes sample applications that are provided to illustrate the essential capabilities of the server. Each sample application resides in its self-named directory in the flashcom application directory. However, when you build a Flash MX SWF file of your own, you do not need to place a copy of it in its subdirectory in the flashcom application directory.
Once you have specified the directory where you’ll store your application directories, you must create a directory inside it for each client application you plan to use with that virtual host. Each client application must have a directory with the same name that the client application uses when connecting to the server. Once you have created a subdirectory for each of your applications, you can decide whether to give any of the applications their own Application.xml file. By including an Application.
The Communication App inspector and NetConnection Debugger If you have Flash MX installed, you’ll find two new windows related to Flash Communication Server: the Communication App inspector and the NetConnection Debugger. • The Communication App inspector lets you view information about the applications running on the Flash Communication Server. • The NetConnection Debugger lets you view information about the events that are taking place on the server.
Using the Administration Console You can do common server administration and monitoring tasks using the graphical user interface of the Administration Console and, in Flash MX, the Communication App inspector. These are Flash applications that Macromedia created using public APIs (application programming interfaces). The source files for these applications are available on Macromedia’s Flash MX Support Center (www.macromedia.com/support/flash/).
You are now connected to the server, and the Diagnostics, Maintenance, Admin Users, Live Log, and License panels appear. These panels perform the following functions: • The Diagnostics panel displays information about the applications that are connected to the server and the number of instances and users of each one. • The Maintenance panel allows you to shut down the server, virtual hosts, or an individual application connected to the server.
An application may have more than one instance if its clients connect to the server by using different application instance parameters within their ActionScript NetConnection calls. (For more information on the NetConnection object, see the Client-Side Communication ActionScript Dictionary.) Using the Maintenance panel To restart or stop the server, a virtual host, or a client application or application instance, you use the Maintenance panel.
VHost Restart lets you restart a virtual host. Restarting a virtual host disconnects all users of that virtual host and removes all application instances from memory. If you are a server administrator you can restart any of the server’s virtual hosts except the default virtual host (_defaultVHost_). To restart a virtual host, enter its name in the Adaptor/VHost text box and click Restart. If you are a virtual host administrator, you can only connect to and administer your own virtual host.
Adding and editing administrators To add or edit administrator log-on information, you use the Admin Users panel. The Admin Users panel contains the following items: displays a hierarchical view of the server’s administrators, adaptors, virtual hosts, and virtual host administrators. Virtual host administrators can only see the administrators of their own virtual host.
To add an administrator: 1 Select the server or the virtual host you want to add the administrator to. The server or virtual host name appears in the Scope text box. 2 Enter the new administrator’s user name in the Name text box. 3 Enter the new administrator’s password in the Password text box. 4 Reenter the password in the Confirm text box. 5 Click the Add button. To update an administrator’s password: 1 Select the administrator in the Admins pane.
System lets you view server error messages, such as attempts to connect to nonexistent applications. When you select this option, server messages are displayed in blue. Clear Window lets you clear the log text from the pane. Viewing and editing license information To view or change the server’s license key and its capacity parameters, you use the License panel. This panel is only available to server administrators. To change the license key, enter the new key and click Update.
Configuring the server at runtime Using a special set of ActionScript commands, you can view and edit the server’s configuration settings by building your own customized administration applications. You can add or remove administrators, change their user names and passwords, and change most of the other server settings in all four of the server’s XML files. For detailed information about using these ActionScript commands, see the Flash MX Support Center (http://www.macromedia.com/ support/flash/).
24 Chapter 2
CHAPTER 3 Configuring Flash Communication Server Macromedia Flash Communication Server MX has been designed to accommodate many types of communication applications. After installation, the server’s configuration files contain only simple, generic settings. You’ll need to make some decisions about how to configure it to best suit your needs. This chapter describes the server’s initial configuration and the XML files that define the configuration.
The Web root directory in this scenario would contain all the components of your applications, such as the flashcom application directory and its individual application subdirectories. These subdirectories would contain the application’s FLA, SWF, HTML, script, stream and shared object files. This setup provides a simple working environment for designing and testing your applications. For security reasons, this configuration is not recommended for deployment.
Deployment: two computers In this scenario the Flash Communication Server and application server are on two separate computers. This allows for more separation of files and functions and more processor bandwidth. The web server computer can also host an application server if your situation requires one.
Some scenarios may require authentication of users who want to access information on an application server. In this case you may want to use a separate computer for Flash Communication Server MX, and another for the web server and application server. Your Flash Communication Server can perform the authentication and then retrieve data from the web/application server. This scenario requires the developer to create server-side scripts to perform these functions.
You may decide to have users authenticated before they are allowed to connect to your Flash Communication Server. In this scenario, users connect first to the web/application server. If they are authenticated, the application server creates a ticket that the user then uses to connect to the Flash Communication Server. The Flash MX communication application must be designed to check for these tickets, typically with server-side scripts.
About the configuration hierarchy Flash Communication Server can support several adaptors, virtual hosts, and applications simultaneously. Each adaptor on the server can serve multiple virtual hosts, and each virtual host can host multiple applications. By supporting multiple adaptors and virtual hosts, Flash Communication Server facilitates management of multiple websites that may have different configurations and administrators.
A typical customized server conf directory might look like this: A customized conf directory containing multiple adaptor, virtual host, and application subdirectories and configuration files The conf directory illustrated here contains two adaptor subdirectories: the _defaultRoot_ subdirectory and the _SecondAdaptor_ subdirectory. • The _defaultRoot_ subdirectory contains the _defaultVHost_ subdirectory and another virtual host subdirectory named www.macromedia.com.
In the preceding example, each virtual host directory contains a subdirectory named applications. Each virtual host’s Vhost.xml must define a flashcom application directory in its tag. The flashcom application directory contains subdirectories for each application that can connect to the virtual host. However, you do not need to name the directory “applications” or locate it inside the virtual host directory.
The Server.xml file contains the following tag structure, along with comments that briefly describe each tag.
• The tag inside the tag specifies the user name of a server administrator in its name parameter and is a container for the , , , and tags. To connect with the Administration Console that is installed with the server, a user must be defined in a tag group. For more information about using the Administration Console (admin.swf ), see Using the Administration Console. You define the first administrator when you run the server installer.
• specifies the order in which to evaluate the preceding and tags. It can be set to either Deny,Allow (the default) or Allow,Deny. When Deny,Allow is specified, the server allows the user specified in to connect from any host that is not included in the tag or is included in the tag. Access is denied from any host that is included in the tag and is not included in the tag.
• The tag inside the tag works the same way as the tag inside the earlier tag, but applies only to the tag that contains it. • The tag near the end of the file contains the tag. This tag is distinct from the tag found under the tag earlier in the file. 36 • contains the serial number for the server. The value of this tag is written to the Server.
The following set of Server.xml tags has been customized for real-world use. Two server administrators are defined, root and jsmith. An administrator named panderson is defined for two virtual hosts, _defaultVHost_ and www.macromedia.com. The and tags are set for all four administrators to allow them to connect only from the IP address 12.34.45.678. The server domain is set to www.macromedia.com.
The Adaptor.xml file The Adaptor.xml file defines settings for an adaptor. It determines the number of threads that can be used by the adaptor, the communications ports that adaptor binds to, and the IP addresses or domains from which the adaptor can accept connections. Each adaptor must have its own directory inside the server’s conf directory. The name of the directory is the name of the adaptor. Each adaptor directory must contain an Adaptor.xml file.
• specifies the IP address and one or more port numbers for the adaptor to bind to. The IP address and port number are separated by a colon. If you specify more than one port, separate them with commas. For example, a tag might look like this: 12.34.56.78:1935, 80, 443 You can set up the adaptor to listen on more than one IP address by specifying more than one tag. Flash Communication Server uses port number 1935 by default.
The Vhost.
• specifies the path to the flashcom application directory for this virtual host. The application directory must contain a subdirectory for each application that will run on the server. This tag allows you to locate your application directories outside the virtual host directory if you wish. If no application directory is specified, it defaults to C:\Program Files\Macromedia\Flash Communication Server MX\conf\_defaultRoot_\_defaultVHost_\.
• • • allows you to specify a virtual directory for storing stream resources used by more than one application. By using a virtual directory, you can specify a relative path that points to a shared directory used by multiple applications. The contents of this tag must be in the form virtualDirectory;actualDirectory. specifies the maximum number of shared objects that the virtual host can create.
The following set of Vhost.xml tags has been customized for real-world use. The alias stream is defined for the virtual host. The application directory is set to C:\Inetpub\wwwroot\apps\. The maximum number of simultaneous connections is set to 50. The virtual directory for streams is set to \streamTemp. The domain suffix is set to macromedia.com for reverse DNS lookups. Finally, the virtual host will accept connections from any IP address.
The Application.
• • indicates the maximum number of bytes that a particular application instance can use to run server-side ActionScript on the server before garbage collection is performed— that is, before any unreferenced or unused ActionScript objects are purged from memory. The default is 1024K or 1 MB. If you create a client application that requires more than 1 MB of ActionScript memory, this value must be increased.
• The tag inside the tag indicates the directory where shared objects should be stored. The default is a directory named Sharedobjects in the application’s directory. The default is used if no directory is specified. When specifying a directory, use an absolute path. (For more information about shared objects, see Developing Communication Applications.) • • 46 is a container for the and tags.
The following set of Application.xml tags has been customized for real-world use. The tag is set to TRUE. The runtime size of the JavaScript (JS) engine is increased from the default to 2 MB. The directory for storing server-side scripts is set to C:\FlashComScripts. The storage directory for streams is set to C:\FlashStreams\. The storage directory for shared objects is set to C:\FlashObjs\. The bandwidth limits are set to the defaults.
48 Chapter 3
CHAPTER 4 Understanding Flash Communication Server Security Macromedia Flash Communication Server MX will typically be used in a network environment where many users will have access to it; by changing its configuration, you can make the server accessible from within a private network, from the public Internet, or both. When deploying any server technology, you will want to consider the implications to both the security of your internal network and the accessibility of the server’s host computer.
• Server.xml The tags allow you to specify exactly who can connect to the server with the Administration Console. Only users specified with these tags can connect. The and tags let you specify exactly which domains administrators can connect from. Administrators cannot connect from domains that are not permitted with these tags. The : tag allows you to specify the port of your choice for connecting to the FlashCom Admin Service with the Administration Console.
• Application.xml The : tag lets you limit the amount of memory that can be used by the server-side ActionScript on the virtual host. This can help prevent attacks using very large numbers of scripts. The default is 1024K. The : and : tags let you specify the locations for storing streams and shared objects.
To have the server perform authentication of connecting users other than administrators, use the and tags in the Adaptor.xml and Vhost.xml files. With these tags you can prevent users from connecting from all domains other than those you specify. The server checks incoming connections against the Adaptor.xml file and then the Vhost.xml file when processing non-administrator connection requests. To provide administrator authorization (assigning permissions), the server uses the Server.
Use server-side script precautions. In server-side scripts do not use procedures that can be called by a malicious movie, which could then fill a hard disk, consume the processor, or do other damage. Procedures attached to client objects are particularly vulnerable. Procedures to be aware of include writing to the hard disk without checking the quantity of data being written, procedures that can be infinitely looped, and so on. Send sensitive data via HTTPS.
You can also configure a firewall to provide additional protection against outside attacks. For example, if the server is being flooded by a particular IP or range of IP addresses, you can configure the firewall to ignore messages from those IP addresses. The server allows you to strictly control which users can connect to it and where they can connect from. You can also configure a firewall to control the ports users inside and outside your network can connect to.
INDEX A Adaptor tag (Adaptor.xml file) 38 Adaptor tag (Server.xml file) 35 adaptors, configuring 38 Adaptor.
Application.xml file (continued) StorageDir tag 45, 46 StreamManager tag 45 AppsDir tag 41 authentication 28, 29, 51 authoring components 10 authorization 51 H halting the server 19 HostPort tag (Adaptor.xml file) 39 HostPort tag (Server.
R RecordAccessLog tag 41 RecordAppLog tag 44 reloading applications 18 removing applications 18 ResourceLimits tag (Adaptor.xml file) 38 ResourceLimits tag (Vhost.
Developing Communication Applications Macromedia Flash Communication Server MX ™ ™ macromedia ®
Trademarks Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fonto
CONTENTS INTRODUCTION About This Manual .................................................. 5 Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Flash Communication Server documentation . . . . . . . . . . . . . . . . . . . . . . . . . Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional resources . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 4 Application Development Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Application design and development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Debugging your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Adding a privacy module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Coding conventions . . . . . . . . . . . .
INTRODUCTION About This Manual Welcome to Macromedia Flash Communication Server MX! The Flash Communication Server provides the technology to integrate streaming audio, video, and data into a Macromedia Flash MX application using the Macromedia Real-Time Messaging Protocol (RTMP), without requiring users to have anything but the current Macromedia Flash Player.
Typographical conventions The following typographical conventions are used in this manual: • Code font indicates ActionScript statements, HTML tag and attribute names, and literal text used in examples. • Italic indicates placeholder elements in code or paths. For example, attachAudio(source) means that you should specify your own value for source; \settings\myPrinter\ means that you should specify your own location for myPrinter.
CHAPTER 1 About Flash Communication Server Macromedia Flash Communication Server MX, the new platform for interactive personal communication, integrates Macromedia Flash MX multimedia with live audio, video and data streaming over networks, provides a system for storing recorded audio and video streams and shared data objects, and enables the real-time sharing of synchronized distributed data among multiple clients.
Communications pass through the Flash Communication Server and are delivered to the client— the Flash Player on a user’s computer—by means of the Macromedia Real-Time Messaging Protocol (RTMP). When a Flash movie uses Flash Communication Server, the player connects to the server, which provides a flow of information, called a network stream, to and from the client.
The Flash Communication Server lets you stream live media (audio, video, and data) or record data to be played later, as illustrated below.
To create audio/video applications, you must have audio/video capture devices (such as a camera and microphone), Flash MX authoring software, and access to a Flash Communication Server. You can also write applications that don’t require audio or video devices, as well as applications that enable communication between Flash Communication Server and application servers or external databases.
Flash Communication Server objects As mentioned earlier, Flash Communication Server provides two application program interfaces (APIs): a client-side API and a server-side API. The client-side API provides the following objects: Camera, Microphone, NetConnection, NetStream, SharedObject, and Video. For more information on using these objects, see the Client-Side Communication ActionScript Dictionary.
Local shared object Client-side local shared objects let you store information on a user’s computer, such as the high score in a game, that can be used later by the same application or by a different application running on that computer. For more information about local shared objects, see “Understanding shared objects” on page 14. The client-side Video object lets you display streaming video on the Stage. To display a video feed being played or captured through the use of a NetStream.play or Camera.
Remote shared object. Remote shared objects are created on the client but are also available to the server. They let you share data in real-time between multiple clients, and also store data for later retrieval by the same or different applications. For more information about client-side remote shared objects, see “Understanding shared objects” on page 14. SharedObject object.
Understanding shared objects Shared objects are a means for sharing data among different clients, among different instances of an application running on the Flash Communication Server, and across applications running on multiple Flash Communication Servers. The Flash Communication Server supports three types of shared objects—local, remote, and server-side. These objects are discussed briefly below. For more information on working with shared objects, see “SharedObject object” on page 80.
The flashcom application directory When your Flash application requires the Flash Communication Server, you must place your application data where the server can locate it. During installation, you choose either a Developer Install or a Production Install of the Flash Communication Server.
Using application instances To distinguish among different instances of a single application, pass a value for instanceName to your NetConnection.connect command. For example, you may want to give different groups of people access to the same application without having them interact with each other. To do so, you can open multiple chat rooms at the same time, as shown below. my_nc.connect("rtmp://myServer.myDomain.com/chatApp/room_01") my_nc.connect("rtmp://myServer.myDomain.
Setting up your development environment To write Flash Communication Server applications, you must install the Flash MX authoring software, Flash Communication Server, and the latest Flash Player. If you want to write applications that capture audio or video, you also need to install a microphone or camera. Additionally, if your application requires server-side scripts for your Flash Communication Server applications, you’ll need a UTF-8 JavaScript editor, such as Macromedia Dreamweaver MX.
Starting the service During server installation, you might have chosen to start the service automatically. If you did, the service will be started whenever the server machine is started, and you don’t need to start it manually. If you did not, you can start the server from the Windows Start menu: choose Programs > Macromedia Flash Communication Server MX > Start Service. On Windows, to confirm that the service is running, open the Task Manager and make sure both FlashCom.exe and FlashComAdmin.
Writing your first application The Flash Communication Server installation includes a sample application called doc_connect that transmits text through the server between two clients. By viewing the source file and then recreating the application yourself, you’ll learn how to write a simple Flash Communication Server application. This example is included only to illustrate how easy it is to implement clientserver communication using Flash Communication Server.
Recreating the sample This sample assumes you are using the Flash MX authoring environment on the computer that is running the Flash Communication Server. If you aren’t, substitute your server URL for “localhost” in the following steps. The sample also assumes that the service is running. To create the user interface for this sample: 1 In the Flash authoring environment, select File > New to open a new file. 2 If the Library panel isn’t visible, select Window > Library to display it.
3 Create a connection function that connects to the Flash Communication Server, displays a trace message indicating whether the connection was successful, and opens and instance of the doc_connect application named room_01. Remember, you must specify the Real-Time Messaging Protocol, rtmp. function doConnect() { client_nc = new netConnection(); client_nc.onStatus = function(info) { trace("Level: " + info.level + " Code: " + info.code); } client_nc.
To test your sample application: 1 Choose File > Publish Settings, select Flash and HTML, click Publish, and then click OK. 2 Choose Control > Test movie. You see two video windows on the Stage, each displaying the same image. 3 To see how the movie looks in a browser, choose File > Publish Preview > Default, or press Control+F12 (Windows) or Command+F12 (Macintosh).
CHAPTER 2 About Flash Communication Server Applications With a few lines of code, your Macromedia Flash MX application (SWF) can communicate with another client through the Macromedia Flash Communication Server MX. Using object-oriented programming techniques and sound programming practices, you can write simple ActionScript code to get started right away. This chapter explains some ideas behind Macromedia Flash Communication Server MX and describes the types of files you’ll generate.
Passing data between clients In Chapter 1, the sample connection application (see “Writing your first application” on page 19) connected to the server, opened a stream to publish some video, and opened another stream to receive the data (play back the video). The only thing the server was expected to do was to pass the video data through and back to the client. (In a real-life scenario, of course, the video data would pass through the server to a different client at another location.
You can use server-side ActionScript to collect and display information regarding clients, transform data, moderate the communication, test conditions, notify using e-mail and other means, and provide many other services. For example, later you’ll work through samples that not only rely on the server to route information, but also expect the server to keep track of client information.
While you can use the Flash Communication Server server-side scripting language to implement transactions, either internally or by communicating with an external server or data source, the core use of Flash Communication Server is handling interactions—coordinating the actions of multiple, connected applications and transmitting server-side data. The rest of this section discusses the Flash Communication Server in the context of managing client-server and client-client interactions.
When the user runs your Flash SWF file and the SWF file connects to the server, the server loads the application and creates the application instance if it isn’t already running. The server accepts the connection, creates a new Client object to represent the client application on the server, and executes any server-side scripts that you have provided. The client also does its work, initiating streams, sharing objects, and so on. The following sections describe this sequence of events in more detail.
After a successful connection, the client makes a call on the connection. If the client needs a result returned, the client provides a callback object to hold the result. On the server, the method corresponding to the client call is invoked; and a result is returned to the client. The client has an onResult handler that is called on the callback object passed in. CLIENT call("doThis", callback_obj,a,b) SERVER "doThis",a,b clientObj.
Finally, here’s an overview of the remote shared object flow. A Flash client movie subscribes to a remote shared object by issuing a SharedObject.getRemote command, and provides a SharedObject.onSync method with it. The client then connects the remote shared object to the NetConnection object by issuing a SharedObject.connect command. The server sends out a synchronization message for the shared object, but no method on the server side is invoked. This synchronization message causes the SharedObject.
When designing your application, note the functionality used on both the client and the server. For a description of how to use the client-side and server-side objects to fulfill the requirements on both sides, see the Client-Side Communication ActionScript Dictionary and the Server-Side Communication ActionScript Dictionary.
CHAPTER 3 Sample Applications This chapter provides examples of a number of Macromedia Flash Communication Server MX programming techniques, and illustrates how to use many of the Flash Communication Server objects. These samples are different from the ones provided in the flashcom application directory, although certain concepts are illustrated in both sets of samples.
You should have Flash MX configured to publish both SWF and HTML files. To specify formats to be created during publishing, choose File > Publish Settings in the Flash MX authoring environment. Specifying publishing formats. Unless otherwise noted, your client-side ActionScript code should be attached to a layer on the first keyframe of your FLA file, not to individual objects. Writing client-side ActionScript code. Writing server-side ActionScript code.
Re-creating the sample The doc_record.fla file provides the ActionScript for getting a camera, attaching it to a Video object, creating a network connection to the server, recording the camera data on an outgoing stream to the server, and then playing that recorded stream in a second Video object. When you record a stream in a Flash application, the server creates files with the extensions .flv and .idx. For more information, see “Recorded stream files” on page 68.
4 In the initStreams function, make a connection to the server. Create the output stream for sending the video data to the server, and the input stream for the data coming back from the server. Then attach the input stream to the Replay_video video clip. function initStreams() { // Make a connection to the application on the server client_nc = new NetConnection(); // Note that this call includes the protocol, rtmp, the // app name, doc_record, and the room, room_01 client_nc.
6 Create the event handler for the Play button that plays the stream recorded on the server. function doPlay() { in_ns.play("my_recorded_stream"); } To test your sample application: 1 In the Flash MX authoring environment, after you have saved your work, publish it by selecting File > Publish. 2 Open the SWF file in the application directory or, in the Flash MX authoring environment, choose Control > Test Movie. Sample 2: Shared Text This sample allows users to share text.
2 Open a connection to the server. // Open connection to server client_nc = new NetConnection(); client_nc.connect("rtmp:/doc_text/room_01"); 3 Handle the messages coming from the server. // Handle status message client_nc.onStatus = function(info) { trace("Level: " + info.level + " Code: " + } 4 info.code); Initialize the typing stage. TypingStage.text = ""; 5 Get a remote shared object to hold the text data from the client. // Create a remote shared object. client_nc.
Sample 3: Shared Ball This sample allows users to move a ball around the screen and to watch while other participants move the ball around. About the sample The previous sample shared text, but you can share graphics as well. This sample allows two users to share the same ball on the Stage. When a user opens the doc_sharedball.htm file, there is a ball on the SWF Stage. When any user moves the ball, all other connected users see it move. Re-creating the sample The doc_sharedball.
5 When you get a shared object, make sure you connect it to the NetConnection object. // Connect to the shared object ball_so.connect(client_nc); 6 Create the function that updates the shared object data with the position of the ball. // Manipulate the ball SharedBall_mc.onPress = function() { this.onMouseMove = function() { ball_so.data.x = this._x = _root._xmouse; ball_so.data.y = this._y = _root._ymouse; // Constrain the ball to the stage if (SharedBall_mc._x>=Stage.width) { SharedBall_mc._x = Stage.
To create the user interface for this sample: 1 In the Flash MX authoring environment, select File > New to open a new file. 2 From the toolbox, select the Text tool and draw a text box. In the Property inspector (Window > Properties), select Input Text for the type of text box and give it the instance name User. 3 Add a dynamic text box for a debug window by selecting the Text tool and drawing another text box.
4 Create the event handler for the Connect button. If the user selected the button when the label was Connect, then connect to the server. If the button label is Disconnect, close the connection. // Event handler for Connect_Btn function doConnect() { // If user wants to connect... if (Connect_btn.getLabel() == "Connect") { // Connect to the chat application client_nc.connect("rtmp:/doc_hello/room_01", User.text); // Update button label Connect_btn.setLabel("Disconnect"); // If user wants to disconnect...
To write the server-side ActionScript for this sample: 1 Create a new file using your server-side ActionScript editor, and write an event handler for when the user connects. In it, you’ll receive the name passed in by the client, accept the client connection, create a message that uses the client’s name, and call the client msgFromSrvr function to return the message. application.onConnect = function(newClient, name) { // Give this new client the same name as the user name newClient.
About the sample In a chat room, you want to view current users dynamically. When users log in to a room, the list should be updated; when users log off, they should be removed from the list. It’s best to do this processing work on the server, because keeping data centrally on the server means that any client can come and go, and the data will always be accurate and available.
3 Provide a value for the maximum scrolling of the History text box component. // Set maximum scroll History.maxscroll = 1000; 4 Prevent the user from sending until after the user has connected to the server. // Don’t allow the user to send until after connection _root.Send_btn.setEnabled(false); 5 Create a new network connection. // Open a connection to the server client_nc = new NetConnection(); 6 Provide an onStatus function to handle any status messages.
9 In the same doConnect function, create the onSync method to handle the change in users. // When the list of users_so is updated, refresh the // People list box. users_so.onSync = function(userList) { _root.People.removeAll(); for ( var i in users_so.data) { if (users_so.data[i] != null) { _root.People.addItem(users_so.data[i]); } } // Sort alphabetically, because order returned // is not guaranteed to be consistent. _root.People.
13 Create the setHistory function that the server calls to update the text in the History dynamic text box. // Update the History on the server with the message client_nc.setHistory = function(msg) { _root.History.text = msg; } To write the server-side ActionScript for this sample: 1 Create a new file using your server-side ActionScript editor, and write the event handler onAppStart for initializing the application variables. application.
3 Write the event handler onDisconnect to clean up. application.onDisconnect = function(client) { trace("disconnect: " + client.name); application.users_so.setProperty(client.name, null); } 4 Save the file as main.asc in a doc_textchat directory under the flashcom applications directory. Note: Save this main.asc file where you’ve chosen to store your server-side application files. For more information see Chapter 1, “The flashcom application directory,” on page 15.
6 To add a Video object to your library, open the Library panel (Window > Library) and add an embedded Video object by selecting New Video from the library’s Options menu. 7 To add the Video object for playing back the recording, drag a Video object onto the Stage. In the Property inspector, give it the instance name Replay_video. 8 From the toolbox, select the Text tool and draw a text box.
6 Remember to connect the shared object to the NetConnection object. // Connect to the shared object rec_so.connect(client_nc); 7 Create an event handler for when the user selects Record, which publishes the new recordings and updates the shared object. function doRecord() { if (ListItem.text == undefined || ListItem.text == "") { Status_msg.text="Please enter a title."; } else if (Record_btn.getLabel() == "Record") { Status_msg.text="Recording..."; // Stop any currently playing stream if (Play_btn.
9 Create the event handler for the Play button. If the user selects Play, update the button label, create an input stream, and play the selected recording. // Do Play function doPlay () { if (Play_btn.getLabel() == "Play") { Status_msg.text="Playing..."; Play_btn.setLabel("Stop"); // Get the selected recording var playFileName = Play_list.getSelectedItem().label; // Create input stream and play the recording in_ns = new NetStream(_root.client_nc); in_ns.play(playFileName); in_ns.
50 Chapter 3
CHAPTER 4 Application Development Tips and Tricks This chapter is designed to supplement, not replace, application development and best practices recommendations included in Using Flash MX. For general information on how Macromedia Flash MX streams data and how you can test and improve the performance of your Flash movies, see “Streaming and file optimization techniques for Flash Player” on the Macromedia Flash Support Site (http://www.macromedia.com/go/flash_stream_optimize).
For example, the code below shows how you could create a network connection on the client side, and then make a call to it from the server side: // This is client-side ActionScript in the FLA my_nc = new NetConnection(); my_nc.someClientMethod = function() { // code here } // This is server-side ActionScript in the main.asc file clientObj.call("someClientMethod"); The argument passed to clientObj.call must be a previously defined method of the client-side NetConnection object.
On the server side On the server side, you must implement slightly different code, using global instead of _root. Here, assume you want to include a file called my_file.asc. if (global._my_file_asc == null) { global._my_file_asc = true; // All the code for myfile.asc goes here } Also, instead of using the #include command, the server-side script uses a load command: load("my_file.
Managing bandwidth You can control the amount of data the server sends to each client by providing an approximate bandwidth capacity. There are a few ways to do so. One way is to configure the capacity for the Flash Communication Server in the configuration file (Config.xml). For more information on this technique, see Managing Flash Communication Server. Another way is to use NetStream.
Note: If you are using speakers instead of a headset, you may want to comment out the call to Microphone.get() to avoid audio feedback. For more information, see “Avoiding audio feedback” on page 83. #include "NetDebug.as" stop(); // Initialize movie by getting a camera and microphone, and // Configure the initial camera and microphone settings client_cam = Camera.get(); client_cam.setMode(150,120,5); client_cam.setQuality(0, 90); client_mic = Microphone.get(); client_mic.
cam.setKeyFrameInterval(5); client_mic.setRate(11); // For demonstration purposes, change size of screen Output_mc._height = 130; Output_mc._width = 175; // If "LAN" was selected } else /*if ( b == 3 )*/ { client_cam = Camera.get(); client_cam.setMode(160,120,15); client_cam.setQuality(0, 90); client_cam.setKeyFrameInterval(10); client_mic.setRate(22); // For demonstration purposes, change size of screen Output_mc._height = 150; Output_mc.
Writing double-byte applications If you are using server-side ActionScript in a development environment or language kit that facilitates double-byte text (such as an Asian language character set), your server-side ActionScript must be in an ASC file that has been UTF-8-encoded. This means you’ll need a JavaScript editor, such as Macromedia Dreamweaver MX, that UTF-8-encodes files. (Simple text editors, such as Microsoft Windows Notepad, don’t UTF-8-encode files.
Because shared object and stream names are strings, and both follow the same rules of URIencoded data, you can define access based on the name. The client.readAccess and client.writeAccess commands take string values. These values can contain multiple string tokens, or unique identifiers for the object names you want to control, separated by semicolons (;). Here are two example strings: client.readAccess = "appStream;/appSO/" client.
In addition to the specific onStatus methods provided for the objects listed above, Flash MX also provides a “super function” called System.onStatus. If onStatus is invoked for a particular object in an error condition and there is no function assigned to respond to it, Flash processes a function assigned to System.onStatus if it exists.
Debugging NetConnection.Connect.Failed If a NetConnection.connect command returns an information object with a code value of NetConnection.Connect.Failed, you are unable to establish a connection with the server.
3 From the options menu in the Library panel (Window > Library), select New Symbol, and give it the name warnRec_mc. Click Advanced if necessary, and under Linkage, select Export for ActionScript, and then click OK. 4 On the warnRec_mc stage, select the Text tool and draw a text box. In the Property inspector, select Static Text for the type of text box.
6 Copy and paste the following code to the Actions panel for the first frame of the movie: stop(); var userAnswer = false; function doRecord() { // If user selects button to record... if (Record_btn.getLabel() == "Record") { // Call function to get user’s approval to record. getApproval(); // When user has provided an answer, if the answer’s // yes, begin to record, otherwise, send a status // message WarnNow_mc.onUnload = function () { // If user approved, Record.
// If the user selects the No button, they // do not want to record. So, set userAnswer // to false, unload the movie clip and return // the updated userAnswer value. WarnNow_mc.No_btn.onRelease = function () { userAnswer = false; trace("userAnswer: " + userAnswer); WarnNow_mc.unloadMovie(); trace("Returning: " + userAnswer); return userAnswer; } } 7 Create a directory named doc_approval in your flashcom application directory, and save your file as doc_approval.fla in this directory.
In addition, words that are used by ActionScript should never be used as names. Also avoid using variable names of common programming constructs, even if the Macromedia Flash Player does not currently support those constructs. This helps to ensure that future versions of the Player will not conflict with the application. For example, do not use commands such as MovieClip = "myMovieClip" or case = false.
• // :TRICKY: Notifies developers that the subsequent code has a lot of interactions. Also advises developers that they should think twice before trying to modify it. Keeping actions together Whenever possible, all code should be placed in one location. This makes the code easier to find and debug. One of the primary difficulties in debugging Macromedia Flash MX movies is finding the code. If most of the code is placed in one frame, this problem is eliminated.
This code outputs: 7 7 0 1 2 3 4 5 In this case, the counter variable on the main Timeline is overwritten by the counter variable within the function. Below is the corrected code, which uses the keyword counter to declare both of the variables. Using the counter declaration in the function fixes the bug in the code above.
The following example demonstrates a correct technique for creating an object, but should be used only when you want properties of the object to be instance-based rather than prototypebased: // Less desirable practice for creating an object MyObject = function() { this.name = ""; this.setName = function(name) { this.name = name; } this.getName = function() { return this.name; } } In the first example, each instance of MyObject points to the same functions and properties defined in the object’s prototype.
Recorded stream files When you use methods that record audio, video, or data streams (for example, Flash Communication Server creates two files—filename.flv and filename.idx—where filename is the string that was passed to the method that recorded the stream. These files are the recorded stream and its associated index file. For example, if you issue the command NetStream.publish("me", "record"), files named me.flv and me.idx will be created. NetStream.
Persistent local shared objects You create persistent local shared objects by using the client-side SharedObject.getLocal command. Persistent local shared objects have the extension .sol and are stored on the client machine in a directory associated with the user who created the shared object. On Windows, the default location is C:\Documents and Settings\userName\Application Data\Macromedia\Flash Player\serverSubdomain\pathToMovie\movieName.swf.
Snapshots and thumbnails This section compares the techniques for grabbing single frames of video as pictures to use within your application. You can find the sample files for the code in the flashcom_help\help_collateral\doc_snapshot and \doc_thumbnails directories under the installed Macromedia Flash MX authoring directories. To see these applications in action, create directories named doc_snapshot and doc_thumbnails in your flashcom application directory, then open the corresponding SWF file.
The following client-side ActionScript code in doc_snapshot.fla connects to the server and plays camera output locally. When the user chooses to take a snapshot, the event handler, doRecord, makes a call to out_ns.attachVideo(client_cam, 0). The second parameter, 0, causes just one frame to be recorded. #include "NetDebug.as" stop(); // Recording state variable RecState_box.text = 0; // Number of snapshots numSnaps = 0; // Initialize button label Record_btn.
} else { // Stop publishing recorded stream out_ns.publish(false); // Close the stream so that we can use the same to publish again out_ns.close(); // Set the label to "Record" Record_btn.setLabel("Record"); // Update the recording state RecState_box.
In the following client-side ActionScript code in doc_thumbnails.fla, the server records the incoming stream until the user chooses to stop the recording. Then, with the call to thumb_ns.play("myRecording", 0, 0, true), only the first frame of that recording is returned to the client. #include "NetDebug.as" stop(); // Recording state variable recState = 0; // Initialize button label Record_btn.
out_ns.publish("myRecording", "record"); Record_btn.setLabel("Stop"); recState = 1; } else { out_ns.publish(false); Record_btn.setLabel("Record"); recState = 0; showThumb(); } } // Show the thumbnail by attaching the stream to the ThumbView_vc // video object and playing it function showThumb() { ThumbView_vc.attachVideo(thumb_ns); thumb_ns.
Application object This section includes recommendations to help you optimize your use of the server-side Application object, including tips on how and why to set up application.OnConnect and application.OnDisconnect functions. Application.onConnect Setting up methods in application.onConnect is a good approach when you want to set up different methods based on user login information.
Application.onDisconnect The server calls the application.onDisconnect method when the NetConnection is closed. You cannot use client.call on the object being passed inside onDisconnect. However, you can send a message to all other clients about this event: // On the server side you would have the following application.onConnect = function(newClient, name) { newClient.name = name; return true; } application.onDisconnect = function(client) { for (var i = 0; i < application.clients.length; i++) { application.
Bandwidth Effect Code Higher image quality, lower motion quality my_cam.setQuality(0,90) LAN Lower image quality, higher motion quality my_cam.setQuality(400000,0) Higher image quality, lower motion quality my_cam.setQuality(0,100) Using one camera in multiple applications Multiple applications (SWFs) can use the same camera at the same time, provided that they are running in the same process.
Second, there is a bit of JavaScript you can use in your HTML page to avoid the security problem. Assuming the movie uses a fully qualified domain name URL to access the Flash Communication Server, this JavaScript redirects the web page to an explicitly named full URL, like this:
