MACROMEDIA FLASH MEDIA SERVER 2 Develop Manual

Developing Media Applications

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central,

ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite,

FlashPaper, Flash Video Encoder, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder,

Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit,

Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in

the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases

mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and

may be registered in certain jurisdictions including internationally.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not

responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your

own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia

endorses or accepts any responsibility for the content on those third-party sites.

Jabber is a registered trademark of the Jabber Software Foundation.

Sorenson™ Spark™ video compression and decompression technology licensed from

Sorenson Media, Inc.

translated, or converted to any electronic or machine-readable form in whole or in part without written approval from

Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which

this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole

purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be

printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation,

commercial purposes, such as selling copies of this documentation or providing paid-for support services.

Acknowledgments

Project Management: Suzanne Smith

Writing: John Norton, Suzanne Smith

Editing: Evelyn Eldridge, Mary Ferguson, Lisa Stanziano, Anne Szabla

Production Management: Adam Barnett

Media Design and Production: Aaron Begley, Paul Benkman, John Francis, Mario Reynoso

First Edition: October 2005

Macromedia, Inc.

601 Townsend St.

San Francisco, CA 94103

3

Contents

About This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About the Flash Media Server documentation . . . . . . . . . . . . . . . . . . . . . 8

Support for learning about Flash Media Server . . . . . . . . . . . . . . . . . . 9

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Installation and system requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Setting up the hardware and software. . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Creating a development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Preview of Development Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Deploying applications and application instances . . . . . . . . . . . . . . . . . 15

Storing server-side and client-side files . . . . . . . . . . . . . . . . . . . . . . . . 15

Storing your application’s server-side script files . . . . . . . . . . . . . . . . 16

About application instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

File types used by Flash Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Connecting to the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Starting the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Opening a connection to the server. . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2: Flash Media Server Architecture . . . . . . . . . . . . . . . . . 21

Understanding the Flash Media Server architecture . . . . . . . . . . . . . . 22

About streams and shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About connecting to external data sources . . . . . . . . . . . . . . . . . . . . . . 26

Workflow for creating and deploying applications . . . . . . . . . . . . . . . . .27

Understanding application flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Understanding connection flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Invoking remote methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Understanding shared object flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

4

Chapter 3: Using Media Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

About Flash Media Server classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

About Client-side classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

About Server-side classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

About client-server communication . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Understanding shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

About the Application class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Using the application.onConnect handler . . . . . . . . . . . . . . . . . . . . . . 43

Using the application.onDisconnect handler . . . . . . . . . . . . . . . . . . . 45

Handling events in a component-based application. . . . . . . . . . . . . 46

The Camera class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Turning the camera off. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Suggested settings for different bandwidth speeds . . . . . . . . . . . . . 47

Using one camera in multiple applications . . . . . . . . . . . . . . . . . . . . . 47

The Client class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

The Microphone class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Avoiding audio feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Keeping the microphone on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

The NetConnection class (client-side) . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

The NetStream class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Using multiple data types in a stream . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Getting the stream time length with ActionScript . . . . . . . . . . . . . . . 50

About buffering a stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

About the play status of a stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

The SharedObject class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

About synchronizing shared objects. . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Using shared object slots effectively . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Flushing remote shared objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Avoiding shared object synchronization problems . . . . . . . . . . . . . . 53

The Stream class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

The System class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

About the Video class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

About creating Video objects dynamically . . . . . . . . . . . . . . . . . . . . . 56

Understanding frame rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 4: Working With Media Files . . . . . . . . . . . . . . . . . . . . . . 57

Working with video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

About creating live web events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Customizing stream delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Working with MP3 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5

Chapter 5: Debugging and Monitoring Applications . . . . . . . . . 65

Using the management console to debug and monitor application . 65

Connecting the management console to a server . . . . . . . . . . . . . . 66

About the View Applications panel . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

About the Live Log panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

About the Clients panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

About the Shared Objects panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

About the Streams panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73

About the Performance panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Using a debug connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

About onStatus event handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Where to use onStatus handlers in a script . . . . . . . . . . . . . . . . . . . . . 77

About overriding the onStatus handler . . . . . . . . . . . . . . . . . . . . . . . . . 77

About the System.onStatus handler . . . . . . . . . . . . . . . . . . . . . . . . . . .78

About debugging a NetConnection.Connect.Failed message. . . . . . .78

Tracing the properties of an object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Chapter 6: Application Development Tips and Tricks . . . . . . . . . 81

About file types and paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

About shared object files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Portability across servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Client-server script interdependence. . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Using multiple script files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Archiving and compiling server-side script files . . . . . . . . . . . . . . . . . . 86

Compiling scripts to bytecode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Forcing the Player Settings panel to appear . . . . . . . . . . . . . . . . . . . . . . 91

Managing bandwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Writing double-byte applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

About unloading and reloading applications . . . . . . . . . . . . . . . . . . . . . 94

Implementing dynamic access control . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Developing secure applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Protecting scripts from third-party code . . . . . . . . . . . . . . . . . . . . . . . . . 96

Simple-system call example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Synchronous system calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Asynchronous system calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Coding conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Following naming guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Naming variables to support code hinting . . . . . . . . . . . . . . . . . . . . .102

Commenting your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Initializing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Using var for local variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

6

7

About This Manual

Welcome to Macromedia Flash Media Server 2—a powerful server platform for creating rich

media applications in Macromedia Flash and for streaming audio and video to Flash clients.

Flash Media Server (FMS) can enable two or more people to participate in a real-time

conversation using text, audio, or video. For example, you can use FMS for meetings, online

community interaction, customer support, sales support, or training. FMS is an excellent way

to power video messaging, video chat, or video blogging. FMS is also a platform for streaming

live data and compelling Flash video experiences across networks for delivery to the Internet.

FMS is part of the Macromedia complete solution for database connectivity, directory

systems, and presence services, and is the only server that can deliver audio and video to the

popular Flash Player.

Intended audience

This manual shows you, the Flash developer, the steps involved in setting up a development

environment and creating Flash Media Server applications, including debugging and testing

applications.

You should already be familiar with Flash authoring, ActionScript, and Flash Player. It is very

helpful to be familiar with JavaScript (because it forms the basis of server-side ActionScript),

client-server models, and networking concepts.

The Flash Media Server documentation assumes that you already have Macromedia Flash

installed and know how to use it.

8About This Manual

About the Flash Media Server

documentation

The Flash Media Server documentation is designed to be used with the Flash documentation,

namely Using Flash and the ActionScript 2.0 Language Reference Guide.

All Flash Media Server documents are available in PDF format (viewable and printable with

Adobe Acrobat Reader) on the Flash Media Server CD and on the Macromedia web site and

as Flash Help in the Macromedia Flash application (select Help > Flash Help). Flash Media

Server documentation is also available in LiveDoc format on the Macromedia web site.

■ Installing Flash Media Server describes how to install the server and the Flash authoring

extensions. It also lists the files that are installed during the installation process.

■ Getting Started with Flash Media Server presents a short overview of Flash Media Server

and the new features in version 2. Also included are system requirements and installation

instructions.

You can find a printed version of this manual in the Flash Media Server CD case.

■ This manual, Developing Media Applications, explains how to set up your development

environment, and how to use the Flash authoring environment and the Flash Media

Server application programming interface (API) to create media applications.

■ Managing Flash Media Server explains the details of configuring and maintaining the

server and using the Administration Console.

■ The Client-Side ActionScript Language Reference for Flash Media Server 2 documents the

ActionScript you can use to create client-side functionality.

■ The Server-Side ActionScript Language Reference documents the ActionScript you can use

to create server-side functionality.

■ The Server Management ActionScript Language Reference documents advanced

ActionScript methods that you can use to extend the management console or to make

your own administration and monitoring tools.

Typographical conventions 9

Support for learning about Flash Media Server

You may want to explore these other sources of support for learning about Flash Media Server:

■ The Flash Media Server Support Center provides TechNotes and up-to-date information

about Flash Media Server.

■ The Flash Media Server Developer Center site provides tips and samples for creating Flash

Media Server applications.

■ The Flash Media Server Online Forum provides a place for you to chat with other Flash

Media Server users.

■ For late-breaking information and a complete list of issues that are still outstanding, read

the Flash Media Server release notes.

Macromedia recommends several websites with links to third-party resources on Flash Media

Server, including the following:

■ Macromedia Flash community sites

■ Macromedia Flash books

■ Object-oriented programming concepts

Typographical conventions

The following typographical conventions are used in this manual:

■ Code font indicates ActionScript statements and literal text used in examples.

■ Code font italic indicates placeholder elements in code. For example,

attachAudio(source) means that you should specify your own value for the source

parameter.

■ Italic indicates placeholder elements in paths. For example, /settings/myPrinter/ means

that you should specify your own location for myPrinter.

■ Directory paths are written with forward slashes (/). If you are running Flash Media Server

on a Microsoft Windows operating system, replace the forward slashes with backslashes.

When a path is specific to the Microsoft Windows operating system, backslashes (\) are

used.

10 About This Manual

11

1

CHAPTER 1

Getting Started

This chapter describes initial steps you need to take before you begin developing applications

with Macromedia Flash Media Server 2. It describes how to set up your development

environment, how to deploy your applications, and how to create a simple application to

connect to the server.

Installation and system requirements

For instructions on how to install Flash Media Server and for information on system

requirements, see Installing Flash Media Server.

Setting up the hardware and software

To write Flash Media Server applications, you must install the Macromedia Flash authoring

software, Flash Media Server, and the latest Flash Player. 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 Media Server applications, you’ll need a

UTF-8 JavaScript editor, such as the Script window in Flash Professional. Each of these

elements of the development environment is discussed in this section.

Flash authoring software If you haven’t already installed Macromedia Flash, see the Flash

documentation.

Flash Media Server software If you haven’t already installed the server, see Installing Flash

Media Server, available as a PDF on the product CD.

12 Getting Started

Flash Player Make sure that you are using the latest version of Flash Player. You can

download Flash Player from the Macromedia website at www.macromedia.com/go/

getflashplayer.

Camera and microphone To install a camera or microphone, follow the instructions that

accompany your device. For a list of cameras that are known to be compatible with Flash

Media Server, see the documentation on camera compatibility on the Macromedia website.

Cameras that aren’t on that list may be compatible with Flash Media Server, but haven’t been

tested by Macromedia.

Many cameras contain a built-in microphone. You can also install a separate microphone, or

for best results, a microphone-headset combination.

After you’ve installed your devices, you can specify which camera or microphone Flash should

use by default. Right-click (Windows) or Control-click (Macintosh) while any

Flash application is playing, select Settings from the context menu, click the Microphone or

Camera panel, and select your preferred device from the pop-up menu.

Using a JavaScript editor You can use any text editor to write server-side ActionScript

code, which you’ll store in files with an extension of .asc or .js. You may prefer to use software

specifically designed for writing web-based applications, such as Flash Professional or

Dreamweaver. To create an .asc file in Flash, choose New > ActionScript Communication

File.

To include non-ASCII text in your server-side scripts, such as double-byte characters used in

Asian languages, you must use an editor that supports UTF-8 encoding. Flash Media Server

requires UTF-8-encoded ASC files to pass double-byte characters from one client to another.

For more information, see “Writing double-byte applications” on page 93.

NOTE

If you are running Flash Media Server on Linux, you’ll need a Windows or Macintosh

computer with Flash to create your media applications, and you’ll need to install the

authoring extensions on your authoring computer. You’ll also want to install Flash Player

on your UNIX server computer to use the administration tools.

Creating a development environment 13

Creating a development environment

This section explains what you need to know before you create Flash Media Server

applications.

Make sure the server is running To publish and test your applications, Flash Media Server

must be running. For more information, see “Starting the service” on page 19.

Specifying the server URI Use the Flash authoring environment on the same computer

that is running the Flash Media Server. If that isn’t the case, add your server name to all of the

connect commands documented here. For example, if your server is running at

myServer.myDomain.com, change a line like this:

new_nc.connect("rtmp:/doc_record/room_01");

to this:

new_nc.connect("rtmp://myServer.myDomain.com/doc_record/room_01");

Specifying publishing formats

Configure Flash to publish both SWF and HTML files. To

specify formats to be created during publishing, select File > Publish Settings in the authoring

environment.

Writing client-side ActionScript code 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. Client-side code in files published for Flash Player 7 or later is case-

sensitive.

Writing server-side ActionScript code For applications that use server-side ActionScript

code, place the code in a server-side script file. Name the file main.asc (or it can have a name

such as registered_app_name.asc) and use the Flash ActionScript Editor or the JavaScript editor

to write it. Server-side code is case-sensitive.

Loading components.asc To use media components in any application, you must load the

components.asc file, located in the scriptlib directory. To load this file, create a server-side

script file for your application, if you haven’t already, name it appropriately (such as main.asc),

and add the following code at the top:

load("components.asc");

NOTE

Be sure you use two slashes (//) after rtmp: in the revised code. The use of a single slash

is supported only when the SWF application is served from the same computer where

Flash Media Server is running.

TIP

You might find it sufficient to copy this file into any application directory that uses media

components, but be sure to name it appropriately.

14 Getting Started

Acknowledging the user’s right to privacy Before you record or broadcast anyone’s image

or voice, it’s important to inform that person of your intention and to gain their consent or

agreement.

Monitoring running applications If you have server administration permissions, you can

view details about an application while you are testing it, such as log messages it is generating,

values of shared objects, and so on. To do so, open the management console and connect to

the Flash Media Server. For more information, see Chapter 5, “Debugging and Monitoring

Applications.”

Preview of Development Tasks

The following checklist provides a high-level overview of the tasks you must complete for any

application to work with Flash Media Server. Each of these tasks is discussed in this chapter in

more detail, so you should read this entire chapter.

To create and deploy a Flash Media Server application, complete the

following tasks:

1. Select a name for your new application (for example, my_app) and register the application

with the server: in the Flash Media Server applications directory, create a new directory

with the name of your application.

This name is your registered application name. The directory is your registered application

directory.

2. In Flash, create a FLA file that includes a new NetConnection statement with the registered

application name and, if applicable, the application instance in the URI.

For example:

my_nc = new NetConnection();

my_nc.connect("rtmp://myDomain.com/registered_app_name");

This statement connects the client to the registered_app_name application.

3. Save the FLA file with your registered application name.

You can store the FLA file anywhere; it is a source file used to create the SWF and is not

part of the deployed application.

4. If you have a script file that contains server-side ActionScript, put it in the registered

application directory in the Flash Media Server applications directory or a /scripts

directory, which you create, within the registered application directory.

Your server-side script file can be named main.asc or registered_app_name.asc.

Deploying applications and application instances 15

5. Publish the SWF file for your application in a directory accessible to your clients but that

Flash Media Server does not use.

For example, you could put your SWF file in the web root directory that will serve your

application to your clients, or you could e-mail the SWF file to your clients and store the

SWF file in some other directory.

Depending on your application, additional steps are required; however, these steps are

necessary for all applications, regardless of their functionality.

The rest of this chapter describes what’s involved in setting up your applications, introduces

the objects and files used in Flash Media Server applications, and shows you how to create and

connect to your first Flash Media Server application.

Deploying applications and application

instances

This section discusses where you must place application data that you want the server to find,

and also explains how and why to run application instances.

Storing server-side and client-side files

The default location for server-side application files is C:\Program files\Macromedia\Flash

Media Server 2\applications on Windows or /opt/macromedia/fms/applications on UNIX.

This location is referred to as the applications directory. When you create a media application,

you must create a registered application directory, which is a subdirectory for your application

in the applications directory.

You can store your client-side files (SWF and HTML) in any location; most likely, you will

store them in your web server publishing directory. The FLA files for your applications can

remain with the SWF and HTML files until deployment; at production time, remove the

FLA files and place them in a secure location.

TIP

Macromedia recommends that you use all lowercase letters and no spaces when you

name directories and files used with Flash Media Server and its applications. This

practice helps to ensure that, during development, your applications will work if you

move files to different computers on different platforms.

16 Getting Started

For organizational purposes during your development work, it might be convenient to store

all of our client and server application files (FLA, SWF, HTML, or ASC) in one subdirectory.

When you deploy your application, you can place your SWF and HTML files in any location.

However, the registered application directory must remain on the Flash Media Server server,

along with any ASC, FSO, and FLV files that the application uses. The server-side files (your

ASC, FLV, and FSO files) and your FLA source file should not be in your web root directory

when you deploy the server and applications. Only your SWF and HTML files should remain

inside the web root directory.

In any case, you must create a registered application directory that has the same name as the

application you connect to when you issue the

NetConnection.connect() command.

For example, suppose you have an application called chat_App, as the following example

shows:

NetConnection.connect("rtmp://myServer.myDomain.com/chat_App")

You must create a subdirectory named chat_App in the applications directory. Suppose also

that your application uses some server-side scripting, stored in a file called chat_App.asc. You

must place the chat_App.asc file in this same directory.

Storing your application’s server-side script files

In most of your applications, you’re likely to use server-side scripting. You create the server-

side script file for your application in the Flash ActionScript editor or in a JavaScript text

editor. Name the script file main.asc or main.js or registered_app_name.asc or

registered_app_name.js, where registered_app_name is the name of the registered application

directory and the application itself. Save the script file in your registered application directory.

For example, if you have an /applications/chat_app directory for your chat application, you

could name your server-side script file chat_app.asc and place it in the chat_app directory.

Alternatively, you can place your server-side scripts in a subdirectory named scripts in the

registered application directory (/applications/chat_App/scripts).

NOTE

You must create a registered application directory that matches your application name

even if you have no server-side script files to place there. This is because Flash Media

Server stores in your registered application directory any stream or shared-object files

that your application creates (see “Coding conventions” on page 101). Also, the

existence of this directory tells Flash Media Server that the application is authorized and

that users can connect to instances of this application.

NOTE

To simplify deployment, Flash Media Server includes an archive compiler utility (far.exe)

that you can use to package your server-side script files in a single archive file. To speed

up loading time, the utility also lets you compile script files to binary format. For more

information, see “Archiving and compiling server-side script files” on page 86.

Deploying applications and application instances 17

About application instances

Applications are run by creating application instances. When a client connects to an

application, the client is actually connected to an application instance. For example, a client

connects to an application named chat_app, as the following example shows:

nc.connect(“rtmp://myDomain.com/chat_app”);

In this example, the client is actually connected to the default instance of the application,

named _defInst_, because no instance is specified.

Clients can also connect to specific application instances that the

instanceName value in the

NetConnection.connect command defines, as the following example shows:

nc.connect(“rtmp://myDomain.com/chat_app/instance1”);

In this example, the client is connected to the application instance named instance1.

You might want to use application instances for specific purposes. For example, you may want

to give different groups of people access to the same application without having the groups

interact with each other, such as in a chat application with “rooms” for different topics. To do

this, you can have multiple instances of the chat application at the same time, as follows:

my_nc.connect("rtmp://myServer.myDomain.com/chatApp/room_01")

my_nc.connect("rtmp://myServer.myDomain.com/chatApp/room_02")

Each application instance is uniquely named. Unlike the parent application, an instance does

not require that its own directory be defined on the server. However, application resources,

such as streams and shared objects, are independent for each instance and are stored in their

own directories under the streams and sharedObjects storage directories configured for the

application.

Another reason to use application instances is to avoid collision of recorded streams or shared

objects that are created by the application. In the preceding example, for instance, any streams

or shared objects that

room_01 creates are distinct from those that room_02 creates, and the

reverse, even though both instances are running the same application, chat_App.

For example, although the support application in the following code creates two shared

objects named CustomerInfo, each instance of the support application has access only to its

own CustomerInfo object. Also, the data in CustomerInfo used by session1 is different from

the data in CustomerInfo used by session2, as the following example shows:

// One instance of application "support"

first_nc = new NetConnection();

first_nc.connect("myserver.mydomain.com/support/session1");

first_so = SharedObject.getRemote("CustomerInfo", first_nc.URI, false);

first_so.connect(first_nc.URI);

// Another instance of application "support"

second_nc = new NetConnection();

18 Getting Started

second_nc.connect("myserver.mydomain.com/support/session2");

second_so = SharedObject.getRemote("CustomerInfo", second_nc.URI, false);

second_so.connect(second_nc.URI);

Instance name room_01 is frequently used, but you can use any string for an instance name

that makes sense in your application.

You can configure several settings related to application instances. In the Application.xml file,

you can configure the maximum idle time before the server unloads an instance. In the

Vhost.xml file, you can configure the number of clients that can connect to the virtual host

hosting an application and the number of instances that the virtual host can load.

For more information on using instance names, see the

NetStream.publish() entry in the

Client-Side ActionScript Language Reference for Flash Media Server 2.

For information on making remote shared objects available to multiple applications, see the

SharedObject.getRemote() entry in the Client-Side ActionScript Language Reference for

Flash Media Server 2.

File types used by Flash Media Server

In addition to the file types that Flash creates and uses (FLA, SWF, and SWD), Flash Media

Server uses or creates the following file types:

ASC and JS files Server-side script files that you write or that are provided with Flash

Media Server. When you create server-side scripts, use the Flash ActionScript editor or a

JavaScript editor and place the scripts in the subdirectory you create for your application in

your registered application directory, for example, /applications/chat_app, or in a scripts

subdirectory, for example, /applications/chat_app/scripts.

Flash Media Server provides a script library in the /scriptlib directory that contains server-side

scripts for components and Flash Remoting services. When you use components or Flash

Remoting with Flash Media Server, include, or load, the appropriate scripts from /scriptlib

into your application’s server-side script file. The location of the /scriptlib directory is

specified in the

<ScriptLibPath> tag in your Application.xml configuration file. For

information on loading the components.asc file to use media components, see “Creating a

development environment” on page 13.

ASE files Server-side script files that are compiled as binary files. See “Archiving and

compiling server-side script files” on page 86.

FAR files Server-side script files that are archived into one self-contained file. See

“Archiving and compiling server-side script files” on page 86.

Connecting to the server 19

FLV and IDX files Recorded streams and their associated index files. When the server

generates streams, it also generates a streams directory in the registered application directory

and stores FLV and IDX files in a subdirectory specific to the application instance (for

example, /applications/chat_app/streams/instance2).

SOL, SOR, and FSO files Shared object files. An SOL file is persistent on the client; an

FSO file is persistent only on the server; an SOR files is persistent on the client and has a

matching FSO file that is persistent on the server. The location of shared object files varies

depending on what kind of shared object it is.

For more information on where Flash Media Server stores stream and shared object files, see

“Coding conventions” on page 101.

For more information about shared objects, see “About shared object files” on page 82.

Connecting to the server

To connect to an instance of Flash Media Server, you first start the service and then issue

new NetConnection and NetConnection.connect() commands in your client-side script.

These tasks are discussed in this section.

Starting the service

If the server is not already started, you can start it manually. From the Windows Start menu,

select Programs > Macromedia > Macromedia Flash Media Server 2> Start Flash Media

Admin Server and Flash Media Server. On Windows, to confirm that the service is running,

open the Task Manager and make sure that both FMSAdmin.exe and FMSMaster.exe are

listed in the Processes tab.

On Linux, open a shell window, change to the directory where you installed Flash Media

Server, and, as a root user, type

fmsmgr fms server start.

NOTE

Applications can connect to Flash Media Server by using RTMP (Routing Table

Maintenance Protocol) or RTMPS (Routing Table Maintenance Protocol over SSL

(Secure Socket Layer)).

TIP

Although you can use components to connect to the server, first learn how to connect by

using ActionScript, as described in this section.

20 Getting Started

Opening a connection to the server

Open a new file in the Flash authoring environment, and then add the client-side

ActionScript commands to connect to the server.

To connect to Flash Media Server:

1. In a new Flash application, begin opening a connection by issuing the following command:

my_nc = new NetConnection();

2.

Follow this command with a connect command:

my_nc.connect(targetURI);

In this basic syntax for NetConnection.connect() (omitting optional parameters),

targetURI is the Uniform Resource Identifier (URI) of an application on the Flash Media

Server that should run when the connection is made. To specify

targetURI, use one of

the following formats (items in brackets are optional):

rtmp://localhost[:port]/appName[/instanceName]

The use of localhost indicates that the server is running on your local computer.

rtmp://host[:port]/appName[/instanceName]

To connect to a virtual host other than the default virtual host, specify the virtual host’s

name in

host. If the server is running on your local computer, you can use “localhost”

as the host name in the URI; this is often convenient during application development.

For example, the following code uses the new NetConnection constructor to create a new

connection object. Then, the object is connected to the server with the call to

my_nc.connect().

// Makes a new connection object

my_nc = new NetConnection();

/* Connects to the instance named appInstance

of the application named appName

located on the Flash Media Server

/* that is running on the virtual host myServer.myDomain.com

my_nc.connect("rtmp://myServer.myDomain.com/appName/appInstance");

NOTE

In all syntax examples for targetURI, you must specify rtmp (the Real-Time

Messaging Protocol) as the protocol for the connection. If you omit it, Flash Player

assumes you want to make an HTTP connection to an application server, and your

connection fails.

Page is loading ...

MACROMEDIA FLASH MEDIA SERVER 2 Develop Manual

This manual is also suitable for

MACROMEDIA FLASH MEDIA SERVER 2 Develop Manual

Related papers

Other documents