Macromedia FLASH MEDIA SERVER 2 User Manual

Server Management ActionScript Language Reference

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, 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.

Sorenson™ Spark™ video compression and decompression technology licensed from

Sorenson Media, Inc.

Copyright © 2002-2005 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, 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: Jody Bleyle

Managing Editor: Rosana Francescato

Editing: Geta Carlson

Production Manager: Adam Barnett

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

Special thanks to Erick Vera and the Flash Media Server engineering and QA teams.

First Edition: October 2005

Macromedia, Inc. 601 Townsend St.

San Francisco, CA 94103

Server Management ActionScript Language Reference . . . . . . . . 5

Using the Server Management ActionScript API . . . . . . . . . . . . . . . . . . . 5

Establishing the connection to the server . . . . . . . . . . . . . . . . . . . . . . . . . .5

A simple application example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Information objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Method summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

addAdmin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

addApp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

addVHostAlias() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

approveDebugSession(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

changePswd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

gc(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

getActiveInstances() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

getAdaptors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

getAdminContext(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

getAdmins() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

getApps() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

getAppStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

getConfig2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

getGroupMembers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

getGroupStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

getGroups() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

getInstanceStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

getIOStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

getLicenseInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

getLiveStreams() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

getLiveStreamStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

getMsgCacheStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

getNetStreams(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

getNetStreamStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

getRecordedStreams() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

getRecordedStreamStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

getScriptStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

getServerStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

getServices() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

getSharedObjects() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

getSharedObjectStats(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

getUsers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

getUserStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

getVHosts(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

getVHostStats(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

ping() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

reloadApp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

removeAdmin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

removeApp(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

removeVHostAlias() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

restartVHost(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

setConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

setConfig2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

startServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

startVHost() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

stopServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

stopVHost() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

unloadApp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Server Management ActionScript Language Reference

Macromedia Flash Media Server includes a set of advanced methods, the Server Management ActionScript application programming interface (API), that lets you extend the management console or make your own administration and monitoring tools by creating Macromedia Flash applications.

This document describes the Server Management ActionScript API. For information about ActionScript, see the ActionScript 2.0 Language Reference. For information about Flash Media Server, see the Client-Side ActionScript Language Reference for Flash Media Server 2, the Server-Side ActionScript Language Reference, and Managing Flash Media Server.

Using the Server Management ActionScript API

To use the Server Management ActionScript API, you need to have Flash and Flash Media Server installed, and you need to have administrative access to Flash Media Server. You should be fluent in ActionScript and in creating Flash applications.

Establishing the connection to the server

Flash Media Server communicates on port 1935 (the default port). However, to use the Server Management ActionScript API, you must connect to Flash Media Server through the administration server on port 1111.

NOTE

This document assumes that you have not changed the default port number for the administration server; if you have, use your valid port number instead of port 1111.

You establish a connection using the parameters: the URI of the host administration server, an administrator user name, and an administrator password.

NetConnection.connect() method, passing in three

When the administration server host to which you want to connect is a virtual host (one of several services on the same machine), make sure to specify the virtual host’s domain name, or IP Address, as part of the URI—for example,

rtmp://www.myVhost.com/admin:1111. That

way, when you connect to the host machine, you connect to an instance of the server running on your specified virtual host.

Only valid administrators, as defined in the Users.xml configuration file, can connect to the server. You must specify two administrative parameters, the user name and the password for a valid administrator, to the

The following example shows the call that lets the administrator

635xjh27 connect to the server on localhost:

nc = new NetConnection(); nc.connect("rtmp://localhost:1111/admin", "MHill", "635xjh27");

NetConnection.connect method.

MHill with password

To prevent unauthorized users from accessing the administration server, you should use a firewall and limit access to the administration server port (port 1111). For more information about security for Flash Media Server, see the security white papers at www.macromedia.com/

go/flashmediaserver_security_en.

Syntax example

To make a Server Management ActionScript API call, you’ll want to include a callback handler and any required parameters in your code.

In the following example, the of a running application; the callback handler the call; and the value application:

nc = new NetConnection(); nc.connect("rtmp://localhost:1111/admin", "MHill", "635xjh27");

getAppStats method is called to retrieve the performance data

new receiveAppStats captures the result of

ChatApp is a required parameter that specifies the name of the

// Call getAppStats nc.call("getAppStats", new receiveAppStats(), "ChatApp");

6 Server Management ActionScript Language Reference

A simple application example

This section contains the code for a simple Flash application that calls the getAppStats method. You can copy and paste this code into Flash to see how a simple call works.

In Flash, create an application with the following elements:

■ An input field named Application Name with a border

■ A button that calls the doGetAppStats() method (shown in the code sample that

follows)

■ A multiline, dynamic text field called outputBox that has a border

■ A scroll component next to the text field

This simple interface lets you test the Server Management ActionScript API.

Next, in the Actions panel, enter the sample ActionScript code that follows. Be sure to replace

admin_name and admin_pass with your valid administrator name and password.

NOTE

The continuation character (¬) indicates that the code continues to the next line; this character should not appear in code.

/** Establishes the connection to Flash Media Server **/

nc = new NetConnection(); nc.connect("rtmp://localhost:1111/admin","admin_name","admin_pass");

/** Makes the API call, for example, "GetAppStats" **/ function doGetAppStats() {

function onGetAppStats() {

this.onResult = function(info) {

if (info.code != "NetConnection.Call.Success")

else {

newline;

}

} } nc.call("getAppStats", new onGetAppStats(), appName.text);

}

outputBox.text = "Call failed: " + info.description;

outputBox.text = "Info for "+appName.text+ " returned:" + ¬

printObj(info, outputBox);

// This function proceeds through an object, printing all values to the // destination, including recursively printing objects within objects. // The tabLevel parameter is used for cosmetic purposes. function printObj(obj, destination, tabLevel)

A simple application example 7

{

if (arguments.length < 2) {

trace("ERROR! you need to supply a text object to output to");

return; } if (arguments.length < 3)

tabLevel = 0;

for (var prop in obj) {

for (var i = 0; i < tabLevel; i++) // insert requested # of tab

characters

destination.text += "\t";

destination.text += prop + " = " + obj[prop] + newline;

if (typeof (obj[prop]) == "object") { // recursively call printObj

printObj(obj[prop], destination, tabLevel+1 );

}

// Alerts you if there are errors connecting to the server.nc.onStatus =

function(info) { if (info.code == "NetConnection.Connect.Success") {

trace("Connected! The call should work")

} else {

// Use nc.isConnected to test condition of server if (! nc.isConnected)

trace("NO netConnection to server. Call will not work");

} }

8 Server Management ActionScript Language Reference

Information objects

All Server Management ActionScript API methods return data in an information object with the following properties: information objects have

data property, which contains return data (often in an object or array), and the description

and

details properties, which typically provide information about errors.

In addition to the information objects that are documented in the Client-Side ActionScript Language Reference for Flash Media Server 2, the NetConnection class has information objects

that are specific to the Server Management ActionScript API. The following table lists the

code and level properties, as well as the meaning of commonly returned information

objects.

Code Level Meaning

NetConnection.Call.Success Status

NetConnection.Admin.CommandFailed Error

NetConnection.Call.Failed Error

NetConnection.Call.BadValue Error

* This information object contains description and detail properties, which are strings that

provide a more specific reason for the failure.

level, code, timestamp, data, description, and details. All

level, code, and timestamp properties. Some methods have the

The call is successful. This information object includes a property, which returns detailed information in an object or array.

The method called is nonexistent.*

A general failure has occurred.*

The value of a parameter is invalid.*

data

Method summary

The Server Management ActionScript API contains the following three types of methods:

■ Queries let you monitor Flash Media Server, its applications, and specific instances of its

applications.

■ Administrative commands let you perform administrative tasks for Flash Media Server,

such as adding administrative users and starting and stopping the server, virtual hosts, and applications.

■ Configuration commands: the getConfig2() command lets you view server

configuration keys, and the

setConfig2() command lets you set values for the keys.

Method summary 9

Some methods are available only to server administrators, as indicated by an asterisk (*) in the description of each method; virtual host administrators cannot use these methods. In some cases, virtual administrators can use a method with restrictions; these restrictions are described in the dictionary entry for the method.

NOTE

Parameters in square brackets ([]) are optional; all other parameters are required. If you don’t specify an optional parameter, a default value might be used, depending on the method. For example, if you don’t specify a virtual host in the

scope parameter, it is

assumed that you want to perform the command on the virtual host to which you connected when you logged on to Flash Media Server.

Queries for monitoring the server

The following table lists the methods you can use to monitor the server.

Method Description

approveDebugSession() Approves a pending debug session’s request to connect to a

selected application.

getActiveInstances() Returns an array of strings that contains the names of all running

application instances on the connected virtual host.

getAdaptors() Returns an array of adaptor names.

getAdminContext() Returns the administrative context for the administrator

(administrator type, name of adaptor, and name of the virtual host).

getAdmins() Returns all the administrators on the Flash Media Server.

getApps() Returns an array of strings that contains the names of all the

applications that are installed.

getAppStats() Returns aggregate information of all instances for an application.

getGroupMembers() Returns a list of the group members for a particular group.

getGroupStats() Returns statistics for a particular group connection.

getGroups() Returns a list of the group connections for a particular application

instance.

getInstanceStats() Returns detailed information about a single running instance of

an application.

getIOStats() Returns the I/O information: bytes in, bytes out, and so on.*

getLicenseInfo() Returns license key information.

getLiveStreams() Returns a list of all live streams currently publishing to a particular

application.

10 Server Management ActionScript Language Reference

Method Description

getLiveStreamStats() Returns detailed information about a live stream.

getMsgCacheStats() Returns server TCMessage cache statistics.

getNetStreams() Returns a list of all network streams that are currently connected

to the application.

getNetStreamStats() Returns detailed information about a specific network stream.

getRecordedStreamStats() Returns detailed information about a recorded stream.

getRecordedStreams() Returns an Array containing the name of all the recorded streams

currently playing from a particular instance of an application.

getScriptStats() Gets the performance data for a script running on the specified

instance of an application.

getServerStats() Retrieves the server status and statistics about the operation of

the server, including the length of time the server has been running and I/O and message cache statistics.*

getServices() Returns an array containing the names of all the services

currently connected to Flash Media Server.

getSharedObjects() Returns a list of all persistent and nonpersistent shared objects

that are currently in use by the specified instance of an application.

getSharedObjectStats() Returns detailed information about a shared object.

getUsers() Returns a list of all users who are currently connected to the

specified instance of an application.

getUserStats() Returns detailed information about a specified user.

getVHosts() Returns an array of vhosts defined for the specified adaptor.

getVHostStats() Returns statistics for a vhost.

ping() Returns a status string indicating the condition of the server.

* Only server administrators can use this method.

Method summary 11

Commands for managing the server

The following table lists the methods you can use to manage the server.

Method Brief description

addAdmin() Adds an administrator to the system.*

addApp() Adds a new application.

addVHostAlias() Adds an alias to a virtual host.

changePswd() Changes the password for an administrator in the system.

gc() Forces garbage collection of server resources.*

reloadApp() Unloads an instance of an application if it is loaded, and then reloads the

instance.

removeAdmin() Removes an administrator from the system.*

removeApp() Removes an application or an instance of an application.

removeVHostAlias() Removes an alias from a virtual host.

restartVHost() Restarts a virtual host.

startServer() Starts or restarts Flash Media Server.*

startVHost() Starts the specified virtual host if it stops. Enables a new virtual host if

the virtual host directories have been created in the file system.*

stopServer() Shuts down the Flash Media Server.*

stopVHost() Stops a virtual host.

unloadApp() Unloads all instances of an application or one instance of an application.

Disconnects all users.

* Only server administrators can use this command.

Commands for configuring the server

The following table lists the methods you can use to configure the server.

Method Description

getConfig2() Returns configuration information for the specified configuration key.

setConfig2() Sets a value for a specified configuration key.

Entries in this document are listed alphabetically.

12 Server Management ActionScript Language Reference

addAdmin()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

addAdmin(admin_name, password [,scope])

Parameters

admin_name A string that contains the user name of the administrator being added.

password Password of that administrator. The password is encoded before it is written to

the Server.xml configuration file.

scope Optional; string that specifies whether the administrator is a server administrator or a

virtual host administrator, and for which virtual host. To add a server administrator, specify

server.

To add a virtual host administrator to the virtual host to which you’re connected, omit this parameter. To add a virtual host administrator to a different virtual host, specify the virtual host as

adaptor_name/virtual_host_name.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status and a code property of NetConnection.Call.Success. The Server.xml

configuration file is updated with the new administrator.

If the call fails, the server sends a reply information object with a and a

code property of NetConnection.Admin.CommandFailed or a more specific value, if

available. Some objects might also have a

description property that contains a string

describing the cause of the failure.

If the specified administrator already exists in the system, this command fails.

level property of error

Description

Adds an administrator to the system. You can add a server administrator or a virtual host administrator, depending on the parameters you specify.

You must be a server administrator to add an administrator to the system.

addAdmin() 13

Example

The following three examples show how you can specify parameters in a call to the addAdmin command:

/* Adds a server administrator named "GLee" with password "boat4907" */ nc.call("addAdmin", new onAddAdmin(), "GLee", "boat4907", "server");

/* Adds a virtual host administrator named "ChrisM" with password "tree2981"

nc.call("addAdmin", new onAddAdmin(), "ChrisM", "tree2981");

/* Adds a virtual host administrator "DHong" with password "wate3235" */ /* for vhost tree.oak.com */ nc.call("addAdmin", new onAddAdmin(), "DHong", "wate3235", "_defaultRoot_/¬

tree.oak.com");

addApp()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

addApp(app_name)

Parameters

app_name A string that contains the name of the application to be added.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status and a code property of NetConnection.Call.Success.

If the call fails, the server sends a reply information object with a level property of error and a

code property of NetConnection.Call.BadValue or a more specific value, if available.

Some objects might also have a

description property that contains a string describing the

cause of the failure.

Description

Adds a new application to the virtual host by creating the required directory for the new application in the directory tree. Once the directory for the new application is created, you (or another administrator with file system access) can put any required server-side scripts in the directory. The client-side code uses the new application directory in the URI parameter of the

NetConnection.Connect call.

14 Server Management ActionScript Language Reference

Example

The following example shows a call to add the ChatApp application to the connected virtual host:

nc = new NetConnection(); nc.connect("rtmp://localhost:1111/admin", "JLee", "x52z49ab");

nc.call("addApp", new onAddApp(), "ChatApp");

addVHostAlias()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

addVHostAlias(VHostName, AliasName, PersistValue)

Parameters

VHostName A string indicating the virtual host to which to add an alias.

AliasName A string indicating the alias name to add to the specified vhost.

PersistValue A Boolean value indicating whether the alias change will be written to the

configuration file to last beyond the vhost's next restart (true), or whether this alias will be lost on vhost restart (false).

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, and a code property of NetConnection.Call.Success.

Description

Adds an alias to a virtual host. Aliases are alternative names for vhosts that are used as targets by incoming Flash Media Server connections. When you remove an alias, that name is no longer available for incoming connections.

Before this API was available, alias names had to be added to the configuration files manually.

approveDebugSession()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

approveDebugSession(appInst, PIN)

Parameters

appInst A string indicating the application and instance name that has a pending debug

connection to approve.

PIN A number indicating the debug session Personal Identification Number. Each debug

connection issues a debug number when queueing to connect to an application. This same number is included on this API. When this API is processed, the PIN numbers are matched and the corresponding connection is allowed to connect. This is a security measure to prevent unauthorized users from using the debug connection.

Keep in mind that 0 is not a valid be able to be easily guessed. PIN numbers must be non-zero and must be within the range of +/- (2^31 - 1) that is between positive or negative 2147483648. If there is a pending connection with a given PIN, and another connection arrives with the same PIN while the original is still waiting, the second connection with the same PIN will be rejected as a security measure.

PIN value. To maintain security, PIN numbers should not

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success.

Description

Approves a pending debug session’s request to connect to a selected application. Once approved and permitted, the debug session may connect to its application through the

Services.onDebugConnect gateway and act as a regular client.

Connecting to an application with a debug session allows you to view the streams and shared objects for an application through the management console.

Example

The following is an example of a Debug connection:

nc.connect("rtmp://serverName/appName%3F%5Ffcs%5Fdebugreq%5F%3D1234"); // The original string is _fcs_debugreq_=1234.

16 Server Management ActionScript Language Reference

The following is an example of a Debug approval request:

nc_admin.call("approveDebugSession", null, appName/instName", 1234);

changePswd()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

changePswd(admin_name, password [, scope])

Parameters

admin_name A string that contains the name of the administrator whose password is being

changed.

password A string that contains that administrator’s new password.

scope Optional; a string that specifies whether the administrator is a server administrator or

virtual host administrator, and for which virtual host.

To change the password for the specified administrator on the virtual host to which you’re connected, omit this parameter. To change the password for the specified administrator on a different virtual host, specify

To change a server administrator’s password, specify

adaptor_name/virtual_hostname.

server.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status and a code property of NetConnection.Call.Success.

If the call fails, the server sends a reply information object with a and a

code property of NetConnection.Admin.CommandFailed or a more specific value, if

available. Some objects might also have a

description property that contains a string

level property of error

describing the cause of the failure.

If the specified administrator does not exist, this command fails.

Description

Changes the password for the specified administrator. The password is encoded before it is written to the Server.xml configuration file.

Virtual host administrators can change only their own password.

changePswd() 17

Example

/* Change password for server administrator named "ASilva" to "cbx5978y" */ nc.call("changePswd", new onChangePswd(), "ASilva", "cbx5978y", "server");

/* Change password for virtual host administrator named "JLee" to "kbat3786"

nc.call("changePswd", new onChangePswd(), "JLee", "kbat3786");

/* Change password for virtual host administrator "JLee" to "kbat3786" on */ /* virtual host "tree.oak.com" */ nc.call("changePswd", new onChangePswd(), "JLee", "kbat3786",

"_defaultRoot_/¬ tree.oak.com");

gc()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

gc()

Parameters

None.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status and a code property of NetConnection.Call.Success.

If the call fails, the server sends a reply information object with a and a

code property of NetConnection.Admin.CommandFailed or a more specific value, if

available. Some objects might also have a

description property that contains a string

describing the cause of the failure.

level property of error

Description

Forces collection and elimination of all server resources that are no longer used, such as closed streams, instances of applications, and nonpersistent shared objects. This operation is performed within about one second of the call.

You must be a server administrator to perform this operation.

18 Server Management ActionScript Language Reference

getActiveInstances()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getActiveInstances([processID])

Parameters

processID A number; the process identifier of a Flash Media Server core process. This

parameter is optional.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

array of strings containing the names of all running instances of an application on the server or on a specified process.

If the call fails, the server sends a reply information object with a and a

code property of NetConnection.Call.Failed or a more specific value, if available.

Some objects might also have a

description property that contains a string describing the

cause of the failure.

Description

Returns an array of strings that contains the names of all running application instances on the entire server (if no

processID parameter.

processID parameter is passed), or on the process specified by the

level property of error

getAdaptors()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getAdaptors()

Parameters

None.

getAdaptors() 19

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

array of strings containing the names of all the adaptors.

Description

Returns an array of adaptors that are defined. You must be a server administrator to perform this command.

getAdminContext()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getAdminContext([adminName][, adaptorName][, vhostName])

Parameters

adminName The name of an administrator.

adaptorName An alternate adaptor, other than _defaultRoot_, on which to find

administrators. If not specified,

vhostName An alternate vhost, other than _defaultVHost_, on which to find vhost

administrators. If not specified, server level admin is used.

_defaultRoot_ is used

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

object. The

Property Description

admin_type

adaptor

vhost

connected

20 Server Management ActionScript Language Reference

data object has the following properties:

String; the type of administrator, either server or vhost.

String; name of the adaptor for which the user is an administrator.

String; name of the virtual host for which the user is an administrator.

String; this property is deprecated and always returns true.

Description

Gets the administrative context for an administrator, including information about the specified user’s administrative permissions, the name of the adaptor and virtual host to which the user is connected, and whether the user is currently connected to Flash Media Server.

getAdmins()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getAdmins(adaptorName)

Parameters

adaptorName Alternate adaptor, other than _defaultRoot_, on which to find vhost

administrators. If not specified,

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

array. The

data object has the following properties:

_defaultRoot_ is used.

Property Description

server_admins

admin name

vhost_admins

vhost

Array; an array of admin names.

String; name of an administrator.

Array; an array of vhost names.

String; name of the virtual host for which the user is an administrator.

Description

Returns an array of all administrators on Flash Media Server. The returned data has two top-level groups: server level administrators and vhost-level administrators. The server-level administrators group is a simple list of names. The vhost administrators are subdivided by vhost and each vhost contains a list of administrators names.

getAdmins() 21

getApps()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getApps()

Parameters

None.

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

array of strings containing the names of all the applications that are installed.

If the call fails, the server sends a reply information object with a and a

code property of NetConnection.Call.Failed or a more specific value, if available.

Some objects might also have a

description property that contains a string describing the

cause of the failure.

Description

Returns an array of strings that contains the names of all the applications that are installed.

level property of error

getAppStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getAppStats(app_name)

Parameters

app_name A string that contains the name of the application for which you want

performance data.

22 Server Management ActionScript Language Reference

Returns

If the call succeeds, the server sends a reply information object with a level property of

status, a code property of NetConnection.Call.Success, and a data property that is an

object. The

Property Description

accepted

bytes_in

bytes_out

connected

launch_time

msg_dropped

msg_in

msg_out

normal_connects

virtual_connects

group_connects

service_connects

service_requests

admin_connects

debug_connects

rejected

total_connects

total_disconnects

total_instances_loaded

data object has the following properties:

Number; total number of connection attempts accepted by this application.

Number; total number of bytes read by this application.

Number; total number of bytes written by this application.

Number; total number of connections currently active.

ActionScript Date object; time the application started.

Number; total number of messages dropped by this application.

Number; total number of messages processed by this application.

Number; total number of messages sent by this application.

Number; total number of normal connections.

Number; total number of connections through a remote edge.

Number; total number of remote edges that are connected.

Number; total number of service connections.

Number; total number of services requested.

Number; total number of admin connections.

Number; total number of debug connections.

Number; total number of connection attempts rejected by this application.

Number; total number of socket connections to the application since the application was started.

Number; total number of disconnections from the application since the application was started.

Number; total number of instances that have been loaded since the application started. This property does not represent the total number of active instances loaded. To get the number of active instances loaded, subtract the value of

total_instances_loaded.

total_instances_unloaded from

getAppStats() 23

+ 51 hidden pages

Macromedia FLASH MEDIA SERVER 2 User Manual

Contents

Server Management ActionScript Language Reference

Using the Server Management ActionScript API

Establishing the connection to the server

Syntax example

A simple application example

Information objects

Method summary

Queries for monitoring the server

Commands for managing the server

Commands for configuring the server

addAdmin()

addApp()

addVHostAlias()

approveDebugSession()

changePswd()

gc()

getActiveInstances()

getAdaptors()

getAdminContext()

getAdmins()

getApps()

getAppStats()