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.

See also

removeVHostAlias()

addVHostAlias() 15

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

See also

getActiveInstances(), getAppStats(), getInstanceStats()

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

Property Description

total_instances_unloaded

up_time

Number; total number of instances that have been unloaded since the application started.

Number; time, in seconds, the application has been running.

If the call fails, the server sends a reply information object with a level property of error 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

Gets aggregate performance data for all instances of the specified application.

See also

getApps(), getInstanceStats()

getConfig()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getConfig(key [,scope])

Parameters

key A string that specifies the configuration key for which information is retrieved.

A key is specified as a list of subkeys that are delimited by slashes (

/). The first subkey specifies

24 Server Management ActionScript Language Reference

Flash Media Server has four server configuration files: Server.xml, Adaptor.xml, Vhost.xml, and Application.xml. Depending on your permissions, you can get configuration keys for all these files, as described in the following list:

■ For the Server.xml file, specify Admin or Server as the first subkey. All subsequent keys

correspond to tags that are relative to the

You must be a server administrator to view configuration keys in the

Virtual host administrators can view configuration keys in the

Admin or Server tag in the Server.xml file.

Server tag.

Admin tag for their own

virtual host only. They might not be able to view certain kinds of sensitive information; for example, they can view the names of other administrators for their own virtual host, but they cannot view those administrators’ passwords or permission settings.

■ For the Adaptor.xml file, specify as the first subkey Adaptor:adaptor_name, where

adaptor_name is the name of the adaptor. All subsequent keys correspond to tags that are

relative to the

■ For the Vhost.xml file, specify as the first subkey Adaptor:adaptor_name/

VirtualHost:vhost_name vhost_name is the name of the virtual host. All subsequent keys correspond to tags that

are relative to the

■ For the Application.xml file of an application that is running on the same virtual host to

Adaptor tag in the Adaptor.xml file.

, where adaptor_name is the name of the adaptor and

VirtualHost tag in the Vhost.xml file.

which you connected when you logged on to the administration server, specify as the first subkey

Application:app_name, where app_name is the name of the application.

To get a key in the Application.xml file for an application that is running on a different virtual host, specify the full key

Application:app_name

To get the default Application.xml file, specify the

app_name attribute.

scope String; to get a configuration key in the Server.xml file, Adaptor.xml file, or

Vhost.xml file, specify a slash (

Adaptor:adaptor_name/VirtualHost:vhost_name/

. You must also specify the scope parameter.

Application without the colon (:) and

/).

To get a configuration key in the Application.xml file for an application that is running on the same virtual host to which you connected when you logged on to Flash Media Server, omit this parameter.

TIP

To determine the adaptor or virtual host to which you’re connected, use the

getAdminContext method.

getConfig() 25

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

XML string for the specified tag.

If the call fails (that is, if the specified configuration key isn’t found), the server returns an empty string.

Description

This API has been deprecated; use getConfig2() instead. Gets information for the specified configuration key in a specified configuration file. Flash Media Server has four configuration files: Server.xml, Adaptor.xml, Vhost.xml, and Application.xml.

Virtual host administrators can view configuration keys in the Vhost.xml file and Application.xml files for their own virtual hosts.

You must be a server administrator to view most of the configuration keys for the Server.xml and Adaptor.xml files.

For a description of the XML configuration files, see Managing Flash Media Server.

TIP

It is possible to have more than one XML tag with the same name at the same level in the XML tree. In the configuration file, you should distinguish such tags by using a name attribute in the XML tag (for example, if you have more than one

<VirtualHost name="www.redpin.com"></VirtualHost>). When you call the getConfig

command and specify the configuration subkeys, you can indicate which tag you want by specifying the tag name, followed by a colon and the correct example,

Admin/Adaptor:_defaultRoot_/VirtualHost:www.redpin.com.

VirtualHost tag:

name attribute, for

Examples

The following examples show how to get configuration keys in each of the four XML files:

// Establish connection to server. nc = newNetConnection(); nc.connect("rtmp://localhost:1111/admin", "JLee", "xm1472dy");

// For a virtual host administrator, find key in Server.xml. key = "Admin/Server/UserList/User:JLee/Password"; nc.call("getConfig", new onGetConfig(), key, "/");

// For a server administrator; find key in Server.xml. key = "Server/LicenseInfo"; nc.call("getConfig", new onGetConfig(), key, "/");

// Find key in Adaptor.xml. key = "Adaptor:_defaultRoot_/HostPortList/HostPort"; nc.call("getConfig", new onGetConfig(), key, "/");

26 Server Management ActionScript Language Reference

// Find key in Vhost.xml. key = "Adaptor:_defaultRoot_/VirtualHost:_defaultVhost_/RecordAccessLog"; nc.call("getConfig", new onGetConfig(), key, "/");

// Find key in Application.xml for an application on the virtual host you // connected to when you logged on to the administration server. // Note that the previous subkeys and the second parameter "/" are not

necessary.

key = "Application:FinanceApp/RecordAppLog"; nc.call("getConfig", new onGetConfig(), key);

// Find key in Application.xml for an application on a different virtual

host.

key = "Adaptor:_defaultRoot_/VirtualHost:www.redpin.com/

Application:ChatApp/ ¬ RecordAppLog";

nc.call("getConfig', new onGetConfig(), key, "/");

See also

getAdminContext(), setConfig()

getConfig2()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getConfig2(key ,scope)

Parameters

key A string that specifies the configuration key for which information is retrieved.

A key is specified as a list of subkeys that are delimited by slashes (

/). The first subkey specifies

the XML configuration file that contains the desired configuration key. Subsequent subkeys correspond to tags that are relative to the XML configuration file; the hierarchy and names of the subkeys match the tags in the XML file. If multiple tags exist with the same name and same parent, they can be distinguished by specifying a "name" attribute and appending the "name" attribute to the tag name separated by a colon in the

key parameter. If the specified

tag is a leaf node, then its tag data is returned. If the specified tag is not a leaf node, the whole tag is returned as an XML string.

scope String; this parameter specifies which configuration file to search for the

configuration tag specified in the

key parameter.

getConfig2() 27

Flash Media Server has six server configuration files: Server.xml, Users.xml, Logger.xml, Adaptor.xml, Vhost.xml, and Application.xml. Depending on your permissions, you can get configuration keys for all these files, as described in the following list:

■ "/" specifies Server.xml.

■ "Users" specifies Users.xml for server administrators.

■ "Logger" specifies Logger.xml.

■ "Adaptor:<adaptor_name>" specifies Adaptor.xml. The <adaptor_name> is the name of

the adaptor. You must have server administrator privileges to access this file. If <adaptor_name> is not the name of the adaptor the caller is connected to, the call fails.

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>" specifies VHost.xml. <vhost_name>

is the name of the vhost of interest. If <adaptor_name> is not the name of the adaptor the caller is connected to, or <vhost_name> is not the name of the vhost that the caller is connected to, the call fails.

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>/Users.xml" specifies Users.xml for

vhost administrators.

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>/App[:<app_name>]" specifies

Application.xml. If no <app_name> is specified, the default Application.xml file is assumed. Otherwise, the application-specific Application.xml for the specified application is used. If the specified application is not defined, or the application does not have an application-specific Application.xml file, the call fails.

TIP

To determine the adaptor or virtual host to which you’re connected, call the

getAdminContext() method.

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

XML string for the specified tag.

If the specified tag is a leaf node, returns the tag data. Otherwise, returns the tag itself. For example, if the desired tag is contains child tags such as "

<foo><bar>foobar</bar></foo>".

<foo>bar</foo>, returns "bar". However, if the desired tag

<foo><bar>foobar</bar></foo>, returns

If the call fails (that is, if the specified configuration key isn’t found), the server returns an empty string.

28 Server Management ActionScript Language Reference

Description

Gets information for the specified configuration key in a specified configuration file. Flash Media Server has six server configuration files: Server.xml, Users.xml, Logger.xml, Adaptor.xml, Vhost.xml, and Application.xml.

Virtual host administrators can view configuration keys in the Vhost.xml file and Application.xml files for their own virtual hosts.

You must be a server administrator to view most of the configuration keys for the Server.xml and Adaptor.xml files.

For a description of the XML configuration files, see Managing Flash Media Server.

TIP

<VirtualHost name="www.redpin.com"></VirtualHost>). When you call the getConfig

command and specify the configuration subkeys, you can indicate which tag you want by specifying the tag name, followed by a colon and the correct example,

Admin/Adaptor:_defaultRoot_/VirtualHost:www.redpin.com.

VirtualHost tag:

name attribute, for

Examples

The following examples get XML data from various configuration files:

tSocket = new NetConnection(); tSocket.connect("rtmp://localhost/admin", "user", "password");

// find key in Server.xml key = "Server/LicenseInfo"; tSocket.call("getConfig2", new onGetConfig(), key, "/");

// find key in Adaptor.xml key = "HostPortList/HostPort"; scope = "Adaptor:_defaultRoot_"; tSocket.call("getConfig2", new onGetConfig(), key, scope);

// find key in Vhost.xml key = "AppsDir"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_"; tSocket.call("getConfig2", new onGetConfig(), key, scope);

// find key in Application.xml for app "foo" key = "Process/Scope"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_/App:foo"; tSocket.call("getConfig2", new onGetConfig(), key, scope);

// find key in default Application.xml key = "Process/Scope"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_/App";

getConfig2() 29

tSocket.call("getConfig2", new onGetConfig(), key, scope);

// return the whole Vhost.xml key = ""; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_"; tSocket.call("getConfig2", new onGetConfig(), key, scope);

See also

getAdminContext(), setConfig2()

getGroupMembers()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getGroupMembers(app_instance, groupNumber)

Parameters

app_instance A string that contains the name of the instance of the application on which

the group resides, in the form the application name and the instance name, separated by a slash ( performance statistics for the default instance of the application.

For example, to specify the default instance for an application named

ChatApp/_defInst_.

groupNumber A number that contains the group’s client ID.

application_name/instance_name. You must specify both

/), even if you want

ChatApp, specify

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 containing the client IDs of all the individual clients connected through this group.

Description

Returns a list of the group members for a particular group. Groups are multiplexed connections from a remote edge server to an origin server. Each group connection represents at least one individual connection to another Flash Media Server that is acting as proxy for this server.

See also

getGroups(), getGroupStats()

30 Server Management ActionScript Language Reference

getGroupStats()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getGroupStats(app_instance, groupNumber)

Parameters

app_instance A string that contains the name of the instance of the application on which

the group resides, in the form the application name and the instance name, separated by a slash ( performance statistics for the default instance of the application.

For example, to specify the default instance for an application named

ChatApp/_defInst_.

groupNumber A number that contains the group’s client ID.

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 containing the client performance data. The

Property Description

connect_time

protocol

msg_in

msg_out

msg_dropped

bytes_in

bytes_out

msg_queue

total_queues

audio

video

other

ActionScript Date object; time the application connected to the server.

String; protocol used by the client to connect to the server (rtmp or rtmpt).

Number; total number of messages processed by this application.

Number; total number of messages sent by this application.

Number; total number of messages dropped by this application.

Number; total number of bytes read by this application.

Number; total number of bytes written by this application.

Object; client message queue statistics.

Number; total number of queues for this client.

Number; total number of audio messages in all audio queues.

Number; total number of video messages in all video queues.

Number; total number of cmd/data messages in the “other” queue.

application_name/instance_name. You must specify both

/), even if you want

ChatApp, specify

data object has the following properties:

getGroupStats() 31

Property Description

stream_ids

members_count

Array; an array of numbers (stream IDs).

Number; the number of clients multiplexing on this group connection.

Description

Gets statistics for a particular group connection. This connection is special because it multiplexes for more than one connection and contains a unique statistic called

members_count. Group connections are established from one server to another as proxies.

See also

getGroups(), getGroupMembers()

getGroups()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getGroups(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application for which

you want performance statistics, in the form specify both the application name and the instance name, separated by a slash ( want performance statistics for the default instance of the application.

For example, to specify the default instance for an application named

ChatApp/_defInst_.

application_name/instance_name. You must

/), even if you

ChatApp, specify

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 the client IDs of all groups connected to this application.

32 Server Management ActionScript Language Reference

Description

Returns a list of the group connections for a particular application instance. Groups are multiplexed connections from a remote edge server to an origin server. Each group connection represents at least one individual connection to another Flash Media Server server that is acting as proxy for this server.

See also

getGroupMembers(), getGroupStats()

getInstanceStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getInstanceStats(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application for which

you want performance statistics, in the form specify both the application name and the instance name, separated by a slash ( want performance statistics for the default instance of the application.

For example, to specify the default instance for an application named

ChatApp/_defInst_.

application_name/instance_name. You must

/), even if you

ChatApp, specify

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

launch_time

up_time

msg_in

msg_out

data object has the following properties:

ActionScript Date object; time the instance was launched.

Number; length of time, in seconds, the instance has been running.

Number; total number of messages processed by this instance of the application.

Number; total number of messages sent by this instance of the application.

getInstanceStats() 33

Property Description

msg_dropped

bytes_in

bytes_out

accepted

rejected

connected

total_connects

total_disconnects

script

normal_connects

virtual_connects

group_connects

service_connects

service_requests

admin_connects

debug_connects

Number; total number of messages dropped by this instance of the application.

Number; total number of bytes read by this instance of the application.

Number; total number of bytes written by this instance of the application.

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

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

Number; total number of connections currently active.

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

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

Object that contains script engine performance data. The following are properties of the script object:

time_high_water_mark: Number; maximum amount of time, in

seconds, that the script has taken to execute an event.

queue_size: Number; total number of events currently in the script

engine queue.

total_processed: Number; total number of events processed by the

script engine.

total_process_time: Number; number of seconds taken to process

the number of events in

queue_high_water_mark: Number; maximum number of events in the

queue.

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 administrator connections.

Number; total number of debug connections.

total_processed.

34 Server Management ActionScript Language Reference

If the call fails, the server sends a reply information object with a level property of error 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

Gets the performance data for a specified instance of an application.

If you only need information about the performance of a specific script, use the

getScriptStats method.

See also

getActiveInstances(), getAppStats(), getScriptStats()

getIOStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getIOStats()

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

object. The

Property Description

msg_in

msg_out

bytes_in

bytes_out

reads

writes

data object has the following properties:

Number; total number of messages processed by the adaptor.

Number; total number of messages sent by the adaptor.

Number; total number of bytes read by the adaptor.

Number; total number of bytes written by the adaptor.

Number; total number of system read calls.

Number; total number of system writes.

getIOStats() 35

Property Description

connected

total_connects

total_disconnects

msg_dropped

tunnel_bytes_in

tunnel_bytes_out

tunnel_requests

tunnel_responses

tunnel_idle_requests

tunnel_idle_responses

normal_connects

virtual_connects

group_connects

service_connects

service_requests

admin_connects

debug_connects

Number; number of currently active socket connections to the adaptor.

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

Number; total number of socket disconnections from the adaptor.

Number; total number of messages dropped.

Number; tunneling header bytes in (this is the overhead over and above RTMP payload).

Number; tunneling header bytes out (overhead in the other direction).

Number; number of tunneling requests thus far.

Number; number of tunneling responses thus far.

Number; number of tunneling requests that had no payload (network chatter overhead).

Number; number of tunneling responses that had no payload (network chatter overhead).

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.

If the call fails, the server sends a reply information object with a level property of error 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 detailed information about the network I/O characteristics of the connected adaptor.

You must be a server administrator to perform this operation.

36 Server Management ActionScript Language Reference

getLicenseInfo()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getLicenseInfo()

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

object. The

Property Description

name

version

build

key

type

family

edition

data object has the following properties:

String; product name, for example, Flash Media Server.

String; version number, for example, 1.0.

String; build number.

String; copyright information.

String; license key that is set in the Server.xml file. If you have more than one license key, this string is a concatenation of all your valid license keys, delimited by semicolons (;).

Number; type of license. If you have multiple licenses, they must have the same type number. Possible values are shown here: 0=Commercial 1=Educational

Number; license family, which determines the value of other properties. If you have multiple licenses, they must have the same family number. Possible values are shown here: 0=Personal 1=Professional

Number; edition, for example, single, trial, beta, unlimited, and so on. If you have multiple licenses, they must have the same edition number.

getLicenseInfo() 37

Property Description

max_connections

max_adaptors

max_vhosts

max_cpu

max_bandwidth

key_details

Number; maximum number of socket connections allowed, which is determined by license family. If you have more than one license, this number is the sum of the

max_connections values of all your licenses.

Number; maximum number of adaptors (network cards) that you can configure for the server, which is determined by license family. If the license family is Personal, the value of

Number; maximum number of virtual hosts allowed, which is determined by license family. If the license family is Personal, the value

max_vhosts is 1.

Number; maximum number of CPUs allowed, which is determined by license family. If this number is greater than 1, you can run the server on multiprocessor computers.

Number; maximum bandwidth, in megabits per second. If you have multiple licenses, this number is the sum of the all your licenses.

Array; contains the information for each license key. If you have more than one license key, there is one array element for each license key. Each array element is an object that contains the following properties:

key: String; license key as set in Server.xml. type: Number; 0=Commercial, 1=Educational. family: Number; 0=Personal, 1=Professional. edition: Number. max_connections: Number; maximum socket connections allowed for

this license.

max_adaptors: Number; maximum adaptors (network cards) allowed for

this license. If the license family is Adaptor, this value is 1.

max_vhosts: Number; maximum number of virtual hosts for each

adaptor, for this license. If the license family is Personal, this value is 1.

max_cpu: Number; maximum number of CPUs allowed. If this number is

greater than 1, you can run the server on multiprocessor computers.

max_bandwidth: Number; maximum bandwidth, in megabits per second. product_code: Number; determined by license family. valid: A Boolean value; 1=true, license is valid; 0=false, license is

invalid.

max_adaptors is 1.

max_bandwidth values of

If the call fails, the server sends a reply information object with a level property of error 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.

38 Server Management ActionScript Language Reference

Description

Retrieves complete license information including information on the maximum bandwidth and maximum number of connections, adaptors, virtual hosts, and CPUs that are allowed by the license. License information for all your licenses is first summarized, followed by specific information about each license.

getLiveStreams()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getLiveStreams(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

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 live streams that are currently publishing to the specified instance of an application.

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.

level property of error

Description

Gets an array of strings that contains the names of all the live streams that are currently publishing to the specified instance of an application.

See also

getLiveStreamStats()

getLiveStreams() 39

getLiveStreamStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getLiveStreamStats(app_instance, stream_name)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

stream_name A string that contains the name of the stream.

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

publisher

subscribers

data object has the following properties:

Object; publisher statistics. The object has the following properties:

name: String; the name of the published live stream. time: Date object; time that the stream was published. This property is a

duplicate of

type: String; the type of stream for the publisher. The value is "publishing". client: Number; the client ID of the publisher. stream_id: Number; the stream ID of the publisher. publish_time: Date object; time that the stream was published. client_type: String; the string type of the publishing client. publish_time: Date object; time that the stream was published.

Array of subscriber statistics. The array contains a subscriber property that is an object containing the following properties:

client: Number; user ID. subscribe_time: Date object; the time that the user subscribed to the stream.

publish_time and exists for backwards compatibility.

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

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

and a Some objects might also have a

description property that contains a string describing the

level property of error

cause of the failure.

40 Server Management ActionScript Language Reference

Description

Returns detailed information about a live stream.

See also

getLiveStreams()

getMsgCacheStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getMsgCacheStats()

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

object. The

data object has the following message cache statistics:

Property Description

allocated

reused

size

Number; total number of message objects allocated.

Number; total number of objects used.

Number; current size.

Description

Returns server TCMessage cache statistics. You must have server administrative privileges to perform this operation.

getMsgCacheStats() 41

getNetStreams()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getNetStreams(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

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 numbers. The numbers represent the server-assigned IDs of all network streams that are currently connected to the specified instance of the application.

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 numbers that represent the server-assigned IDs of all the network streams that are currently connected to the specified instance of the application.

level property of error

See also

getNetStreamStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getNetStreamStats(app_instance, netstream_ID)

42 Server Management ActionScript Language Reference

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

netstream_ID A number that represents the ID of the network stream or an array of

numbers that represents the network stream ID.

To get information for all the network streams that are currently connected, specify a value of

-1 for the

Returns

netstream_ID parameter.

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 statistics for the network stream. Each element in the array is an object that has the following properties:

Property Name

stream_id

name

type

client

time

Number; stream ID.

String; stream name or empty if the stream is idle.

String; stream type. Possible values are shown in the following list:

idle publishing playing live play recorded

Number; user ID.

ActionScript Date object; possible values are shown in the following list: If

type = idle, value is 0.

type = publishing, value is the time the stream was published. type = playing live, value is the time the playback of the stream started.

If If

type = play recorded, value is the time the playback of the stream started.

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

level property of error

cause of the failure.

Description

Gets detailed information for one or more network streams that are connecting to the specified instance of an application.

See also

getNetStreams()

getNetStreamStats() 43

getRecordedStreams()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getRecordedStreams(app_name)

Parameters

app_name A string that contains the name of the application or instance of the application,

in the form

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 all the recorded stream names. The extended name of a recorded stream is used. The name is encoded with the stream type (for example: flv, or mp3), and

The properties are defined in the following table:

Property Name

streamName

type

keyName

application_name[/instance_name].

keyName*type:streamName, where keyName is the virtual key, type is

streamName is the text name of the stream.

String; name of the recorded stream.

String; type of the recorded stream.

String; virtual key of this recorded stream.

Description

Returns an array containing the names of all the recorded streams currently playing from a particular instance of an application.

See also

getRecordedStreamStats()

44 Server Management ActionScript Language Reference

getRecordedStreamStats()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getRecordedStreamStats(app_instance, stream_name)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

stream_name A string that contains the name of the stream. If the stream has a non-default

virtual key or type, these items should be encoded into the stream name. The following is an example of how to encode key and type:

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 that contains the following properties:

Property Name

cache_bytes

cache_segments

cache_hits

cache_misses

modified_time

size

length

Number; total number of cached bytes of this recorded stream.

Number; number of segments cached for this recorded stream.

Number; number of hits on this stream within the cache.

Number; number of misses on the cache for this stream.

ActionScript Date object; date when this file was last modified.

Number; number of bytes in this recorded file.

Number; length of this file in seconds.

key?type:name and on2key?flv:myStream.

Description

Returns detailed information about a recorded stream.

See also

getRecordedStreams()

getRecordedStreamStats() 45

getScriptStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getScriptStats(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

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

time_high_water_mark

queue_size

total_processed

total_process_time

queue_high_water_mark

data object has the following properties:

Number; maximum amount of time, in seconds, the script has taken to execute an event.

Number; total number of events currently in the script engine queue.

Number; total number of events processed by the script engine.

Number; number of seconds taken to process the number of events in

Number; maximum number of events in the queue.

total_processed.

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

level property of error

cause of the failure.

Description

Gets the performance data for a script running on the specified instance of an application.

46 Server Management ActionScript Language Reference

getServerStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getServerStats()

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

object. The

Property Description

launchTime

up_time

msg_cache

data object has the following properties:

ActionScript Date object; time the server was started.

Number; length of time, in seconds, that the server has been running.

I/O statistics, returned as an object with the following properties:

msg_in: Number; total number of messages processed by the server. msg_out: Number; total number of messages sent by the server. bytes_in: Number; total number of bytes read by the server. bytes_out: Number; total number of bytes written by the server. reads: Number; total number of system read calls. writes: Number; total number of system writes. connected: Number; total number of active socket connections to the

server.

total_connects: Number; total number of socket connections to the server. total_disconnects: Number; total number of socket disconnections from

the server.

Flash Media Server message packet cache statistics, returned as an object with the following properties:

allocated: Number; total number of message objects allocated. reused: Number; total number of objects reused. size: Number; size of the cache, in number of message packets.

getServerStats() 47

Property Description

memory_Usage

cpu_Usage

Number. On Microsoft Windows NT 4.0, the approximate percentage of the last 1000 pages of physical memory in use. On Windows 2000 or Windows XP, the approximate percentage of total physical memory in use.

Number; approximate percentage of CPU in use by the Flash Media Server processes—not by the entire system.

If the call fails, the server sends a reply information object with a level property of error 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

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.

You must be a server administrator to perform this operation.

If you only need information about the I/O characteristics of the server, use the

getIOStats

method instead.

See also

getIOStats()

getServices()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

getServices()

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 service names.

48 Server Management ActionScript Language Reference

Description

Returns an array containing the names of all the services currently connected to Flash Media Server.

Special applications may connect and offer themselves as services to the Flash Media Server. These connections can currently only come through the Java or C SDK for Flash Media Server, as normal connections cannot register as a service. Each application may request the use of these services, and the requested service will offer itself to the application.

getSharedObjects()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getSharedObjects(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

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

data object has the following properties:

Property Description

persistent

volatile

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

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

and a Some objects might also have a

Array of strings that contain persistent shared object names.

Array of strings that contain shared object names that are not persistent.

level property of error

description property that contains a string describing the

cause of the failure.

This call fails if you supply an application or instance name that does not exist.

Description

Gets the names of all the shared objects that are currently active.

getSharedObjects() 49

See also

getSharedObjectStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getSharedObjectStats(app_instance, object_name, persistence)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

object_name A string that contains the name of the shared object. You can get the names of

all active shared objects by using the

persistence A Boolean value: true (1) for persistent; false (0) for nonpersistent.

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

data object has the following properties:

getSharedObjects command.

Property Description

version

num_properties

msg_in

msg_out

total_connects

total_disconnects

connected

resync_depth

50 Server Management ActionScript Language Reference

Number; version number of the shared object.

Number; total number of properties in the shared object.

Number; total messages in to the shared object.

Number; total messages out from the shared object.

Number; total number of connections to the shared object.

Number; total number of disconnections from the shared object.

Number; number of active subscribers.

Number; maximum version retained before resynchronization. If the difference between the server version number and the client version number is greater than the sends only changes between versions.

resync_depth value, Flash Media Server

If the call fails, the server sends a reply information object with a level property of error 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

Gets detailed information about a shared object.

See also

getSharedObjects()

getUsers()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getUsers(app_instance)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

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 that represent the IDs of users who are connected to the specified instance of an application. The user IDs are assigned by the server.

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

level property of error

cause of the failure.

Description

Gets an array of strings that represent the server-assigned IDs of all users who are connected to the specified instance of an application.

getUsers() 51

See also

getUserStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getUserStats(app_instance, user_ID)

Parameters

app_instance A string that contains the name of the instance of the application, in the

form

application_name/instance_name.

user_ID A string that contains the user ID, as assigned by the server. You can retrieve a user

ID with the

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

getUsers command.

data object has the following properties:

Property Description

connect_time

msg_in

msg_out

msg_dropped

bytes_in

bytes_out

msg_queue

52 Server Management ActionScript Language Reference

ActionScript Date object; time, in seconds, that the user has been connected to the specified instance of the application.

Number; total number of messages processed by this user.

Number; total number of messages sent by this user.

Number; total number of messages dropped by this user.

Number; total number of bytes read by this user.

Number; total number of bytes written by this user.

Object that contains the client message queue statistics. The

msg_queue object contains the following properties: total_queues: Total number of queues for this client. audio: Total number of audio messages in all audio queues. video: Total number of video messages in all video queues. other: Total number of command/data messages in the other

queue.

Property Description

protocol

stream_ids

String; protocol used by the client to connect to the server ("rtmp", "rtmpt" or "rtmps".)

Array of numbers that represent the stream IDs.

If the call fails, the server sends a reply information object with a level property of error 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

Gets the performance data for the connection of a specified user.

See also

getUsers()

getVHosts()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getVHosts([adaptorName])

Parameters

adaptorName Optional string that contains the user name of the adaptor. If not specified, it

is assumed to be

"_defaultRoot_".

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 virtual hosts.

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

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

and a Some objects might also have a

description property that contains a string describing the

level property of error

cause of the failure.

getVHosts() 53

Description

Returns an array of vhosts defined for the specified adaptor. You must be a server administrator to perform this command.

getVHostStats()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

getVHostStats([adaptorName, vhostName])

Parameters

adaptorName Optional string that contains the user name of the adaptor. If not specified, it

is assumed to be

vhostName Optional string that contains the user name of the virtual host. If not specified,

it is assumed to be

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 containing the virtual host performance data. The properties:

"_defaultRoot_".

"_defaultVHost_".

data object has the following

Property Description

msg_in

msg_out

msg_dropped

bytes_in

bytes_out

accepted

rejected

connected

total_apps

total_connects

54 Server Management ActionScript Language Reference

Number; total number of messages processed by this vhost.

Number; total number of messages sent by this vhost.

Number; total number of messages dropped by this vhost.

Number; total number of bytes read by this vhost.

Number; total number of bytes written by this vhost.

Number; total number connections accepted by this vhost.

Number; total number of connections rejected by this vhost.

Number; total number of connections currently active.

Number; total number of applications that have been created.

Number; total number of connections to the server.

Property Description

total_disconnects

total_instances_loaded

total_instances_unloaded

bw_in

bw_out

tunnel_bytes_in

tunnel_bytes_out

tunnel_requests

tunnel_idle_requests

tunnel_idle_responses

normal_connects

virtual_connects

group_connects

service_connects

service_requests

admin_connects

debug_connects

Number; total number of disconnections from the server.

Number; total number of instances that have been loaded. 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.

Number; total number of instances that have been unloaded.

Number; current bandwidth in, in bytes per second.

Number; current bandwidth out, in bytes per second.

Number; total number of bytes read through the tunnel.

Number; total number of bytes written through the tunnel.

Number; number of current requests.

Number; number of currently idle requests.

Number; number of currently idle responses.

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 administrator connections.

Number; total number of debug connections.

total_instances_unloaded from

If the call fails, the server sends a reply information object with a level property of error 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 aggregate performance data for all instances for all applications for the specified vhost. You must be a server administrator to perform this command.

getVHostStats() 55

ping()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

ping()

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 timestamp property that

is a Date object. The Date object indicates the time that the command was executed.

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

Verifies that the server is running; the server responds with a status message. You can use this command to check the status of the server.

level property of error

reloadApp()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

reloadApp(app_name)

Parameters

app_name A string that contains the name of the application or instance of the application,

in the form application, specify only the name of the application.

56 Server Management ActionScript Language Reference

application_name[/instance_name]. To reload the default instance of an

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.Command.Failed 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.

Description

Shuts down the specified application or instance of the application, if running, and reloads it. All users are disconnected.

After this command runs, users must reconnect to the application or instance of the application.

You can use this command to preload an instance of an application or reload it when application configuration changes are made or the script that is associated with the application has been changed.

See also

unloadApp()

removeAdmin()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

removeAdmin(admin_name [,scope])

Parameters

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

scope Optional; string that specifies which administrator you want to remove.

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

To remove a server administrator, specify

adaptor_name/virtual_hostname.

server.

removeAdmin() 57

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.Command.Failed 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, the call fails.

Description

Removes an administrator from the system. Depending on the parameters you specify, you can remove server administrators or virtual host administrators.

You must be a server administrator to remove an administrator from the system.

Example

The following examples show the removeAdmin method:

/* Remove a server administrator named "DYoung" */ nc.call("removeAdmin", new onRemoveAdmin(), "DYoung", "server");

/* Remove a virtual host administrator named "LPark" */ nc.call("removeAdmin", new onRemoveAdmin(), "LPark");

/* Remove a virtual host administrator "JGarcia" from vhost tree.oak.com */ nc.call("removeAdmin", new onRemoveAdmin(), "JGarcia", "_defaultRoot_/ ¬ tree.oak.com");

See also

addAdmin()

removeApp()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

removeApp(app_name)

58 Server Management ActionScript Language Reference

Parameters

app_name A string that contains the name of the application or instance of the application

you want to remove, in the form

application_name[/instance_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.

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

code property of NetConnection.Admin.Command.Failed 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.

Description

Removes the specified application or instance of an application from the virtual host. First, all instances of the specified application are unloaded. Then the application directory is removed from the virtual host. If you specify an instance of an application, only that instance is unloaded and removed, and all streams and shared objects for that instance are deleted.

Example

The following example shows how you remove the entire application ChatApp and then shows how you remove a specific instance

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

Instance1 of an application ChatApp.

/* Removes the application along with all instances of the application */

nc.call("removeApp", new onRemoveApp(), "ChatApp");

/* Removes only the specified instance */

nc.call("removeApp", new onRemoveApp(), "ChatApp/Instance1");

See also

addApp()

removeVHostAlias()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

removeVHostAlias() 59

Usage

removeVHostAlias(VHostName, AliasName)

Parameters

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

AliasName A string indicating the alias name to remove from the specified vhost.

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

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

See also

addVHostAlias()

restartVHost()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

restartVHost([scope])

Parameters

scope Optional; string that specifies which virtual host you want to restart.

To restart the virtual host to which you’re connected, omit this parameter.

To restart a different virtual host, specify the virtual host as

virtual_hostname

Returns

adaptor_name/

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.

60 Server Management ActionScript Language Reference

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

code property of NetConnection.Admin.Command.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

Restarts a virtual host that is currently running. Restarting a virtual host disconnects all connected users, unloads all currently loaded applications, and reloads the configuration files for that virtual host.

If you make changes to the configuration files for a virtual host, you can use this command to restart the virtual host without restarting the server.

Users must reconnect each time you restart a virtual host. Before using this command, you might want to take steps to notify connected users.

Virtual host administrators can only restart the virtual hosts to which they are connected. You must be a server administrator to start a virtual host other than the one to which you’re connected.

TIP

To start a virtual host that is stopped, use the startVHost() command. You must be a server administrator to perform this command.

Example

The following example shows a call to restart the connected virtual host and then a call to restart a specified virtual host

/* Restart the connected virtual host */ nc.call("restartVHost", new onRestartVHost());

tree.oak.com on the default adaptor:

/* Restart the virtual host tree.oak.com on the default adaptor. */ nc.call("restartVHost", new onRestartVHost(), "_defaultRoot_/

tree.oak.com");

See also

reloadApp(), startVHost(), stopVHost()

restartVHost() 61

setConfig()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

setConfig(key, key_value, [,scope])

Parameters

key A string that specifies the configuration key for which you want to change the value.

A key is specified as a list of subkeys delimited by slashes ( XML configuration file that contains the desired configuration key. Subsequent subkeys correspond to tags that are relative to that XML configuration file; the hierarchy and names of the subkeys match the tags in the XML file.

Flash Media Server has four server configuration files: Server.xml, Adaptor.xml, Vhost.xml, and Application.xml. Depending on your permissions, you can change the values of configuration keys for all these files:

■ For the Server.xml file, specify Admin or Server as the first subkey. All subsequent keys

correspond to tags that are relative to the

<Admin> or <Server> tag in the Server.xml file.

You must be a server administrator to set configuration keys in the

Virtual host administrators can set configuration keys for their own virtual host only. They might not be able to set certain kinds of sensitive information; for example, they can set their own password, but they cannot set other virtual host administrators’ passwords or permission settings.

■ For the Adaptor.xml file, specify as the first subkey Adaptor:adaptor_name, where

adaptor_name is the name of the adaptor. All subsequent keys correspond to tags relative

<Adaptor> tag in the Adaptor.xml file.

to the

■ For the Vhost.xml file, specify as the first subkey Adaptor:adaptor_name/

VirtualHost:vhost_name

, where vhost_name is the name of the virtual host. All subsequent keys correspond to tags relative to the file.

/). The first subkey specifies the

<Server> tag.

<VirtualHost> tag in the Vhost.xml

62 Server Management ActionScript Language Reference

■ For the Application.xml file of an application that is running on the same virtual host to

which you connected when you logged on to the administration server, specify as the first subkey

Application:app_name, where app_name is the name of the application.

To get a key in the Application.xml file for an application that is running on a different virtual host, specify the full key:

Application:app_name

Adaptor:adaptor_name/VirtualHost:vhost_name/

. You must also specify the scope parameter; see the code

example later in this entry.

To get the default Application.xml file, specify

app_name attribute.

NOTE

If a subkey is specified but a corresponding tag doesn’t exist in the XML file, a new tag is created in the XML file.

key_value String; the value to set for the specified configuration key.

scope String; to change a configuration key in the Server.xml file, Adaptor.xml file, or

Vhost.xml files, you must specify a slash (

/) for this parameter.

Application without the colon (:) and the

To change a configuration key in the Application.xml file for an application that is running on the same virtual host to which you connected when you logged on to Flash Media Server, omit this parameter.

TIP

To determine the adaptor or virtual host to which you’re connected, use the

getAdminContext method.

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 value of the

configuration key is changed.

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

code property of NetConnection.Call.BadValue, and a description property that

level property of error, a

contains a string describing the cause of the failure.

This call fails if the specified configuration key cannot be found or if you do not have permissions to change its value.

Description

This API has been deprecated; use setConfig2() instead. Changes the value of the specified configuration key in a specified configuration file. Flash Media Server has four server configuration files: Server.xml, Adaptor.xml, Vhost.xml, and Application.xml.

Virtual host administrators can change the values of configuration keys in the Vhost.xml file and Application.xml files for their own virtual hosts.

setConfig() 63

You must be a server administrator to change the values of most configuration keys in the Server.xml and Adaptor.xml files.

For a description of the XML configuration files, see Managing Flash Media Server.

TIP

<VirtualHost name="www.redpin.com"></VirtualHost>.) When you call the setConfig

command and specify the configuration subkeys, you can indicate which tag you want by specifying the tag name, followed by a colon and the correct name attribute, for example:

Adaptor:_defaultRoot_/VirtualHost:www.redpin.com.

Examples

The following examples show how to set new values for configuration keys in each of the four XML files:

// Establish connection to server nc = newNetConnection(); nc.connect("rtmp://localhost:1111/admin", "LGreen", "123jn098");

// For a virtual host administrator, change key in Server.xml // Set Password for user LGreen to "strawman28" key = "Admin/Server/UserList/User:LGreen/Password"; val = "strawman28" nc.call("setConfig", new onSetConfig(), key, val, "/");

// For a server administrator, change key in Server.xml // Set LicenseInfo to "Helloworld" key = "Server/LicenseInfo"; val = "Helloworld"; nc.call("setConfig", new onSetConfig(), key, val, "/");

// Change key in Adaptor.xml // Set HostPort to 128.0.0.1:1938 key = "Adaptor:_defaultRoot_/HostPortList/HostPort"; val = "128.0.0.1:1938"; nc.call("setConfig", new onSetConfig(), key, val, "/");

// Change key in Vhost.xml // Set RecordAccessLog to true key = "Adaptor:_defaultRoot_/VirtualHost:_defaultVHost_/RecordAccessLog"; val = "true"; nc.call("setConfig", new onSetConfig(), key, val, "/");

// Change key in Application.xml for an application on the virtual host // you connected to when you logged on to the administration server. // Note that the previous subkeys and the final parameter "/" are not // necessary. key = "Application:FinanceApp/RecordAppLog";

64 Server Management ActionScript Language Reference

val = "true"; nc.call("setConfig", new onSetConfig(), key, val);

// Change key in Application.xml for a different virtual host. // The adaptor and virtual host names and the second parameter are

necessary.

key = "Adaptor:_defaultRoot_/VirtualHost:www.redpin.com/

Application:ChatApp/ ¬ RecordAppLog"; val = "true"; nc.call("setConfig', new onSetConfig(), key, val, "/");

See also

getAdminContext(), getConfig()

setConfig2()

Availability

■ Flash Player 6.

■ Flash Media Server 2.

Usage

setConfig2(key, key_value, ,scope)

Parameters

key A string that specifies the configuration key for which you want to change the value.

Flash Media Server has six server configuration files: Server.xml, Users.xml, Logger.xml, Adaptor.xml, Vhost.xml, and Application.xml. Depending on your permissions, you can change the values of configuration keys for all these files:

key_value String; the value to set for the specified configuration key. If the value specified

is a simple string, it is set as the tag data for the specified tag. If the value is valid XML, for example, <foo>bar</foo>, the XML is added as a child tag to the specified tag. If the value is an empty string, the specified tag is removed.

/). The first subkey specifies the

setConfig2() 65

scope String; specifies the value to set for the tag specified by the key parameter. If the

value specified is a simple string, it is set as the tag data for the specified tag. If the value is valid XML, for example, <foo>bar</foo>, the XML is added as a child tag to the specified tag. If the value is an empty string, the specified tag is removed.

■ "/" specifies Server.xml. You must have server administrator privileges to access most parts

of this file. The only section that does not require server administrator privileges is the <VirtualHost> section that contains administrators for the vhost that the caller belongs to.

■ "Users" specifies Users.xml for server administrators.

■ "Logger" specifies Logger.xml.

■ "Adaptor:<adaptor_name>" specifies Adaptor.xml. The <adaptor_name> is the name of

the adaptor of interest. You must have server administrator privileges to access this file. If <adaptor_name> is not the name of the adaptor the caller is connected to, the call fails.

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>" specifies VHost.xml. <vhost_name>

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>/Users" specifies Users.xml for vhost

administrators.

■ "Adaptor:<adaptor_name>/VHost:<vhost_name>/App[:<app_name>] specifies

Application.xml. If no <app_name> is specified, then the default Application.xml is assumed. Otherwise, the application specific application.xml for the specified application is used. If the specified application is not defined, or the application does not have an application specific application.xml, the call fails.

TIP

To determine the adaptor or virtual host to which you’re connected, use the

getAdminContext() method.

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 value of the

configuration key is changed.

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

code property of NetConnection.Call.BadValue, and a description property that

level property of error, a

contains a string describing the cause of the failure.

This call fails if the specified configuration key cannot be found or if you do not have permissions to change its value.

66 Server Management ActionScript Language Reference

Description

Changes the value of the specified configuration key in a specified configuration file. Flash Media Server has six server configuration files: Server.xml, Users.xml, Logger.xml, Adaptor.xml, Vhost.xml, and Application.xml.

Virtual host administrators can change the values of configuration keys in the Vhost.xml file and Application.xml files for their own virtual hosts.

You must be a server administrator to change the values of most configuration keys in the Server.xml and Adaptor.xml files.

For a description of the XML configuration files, see Managing Flash Media Server.

TIP

<VirtualHost name="www.redpin.com"></VirtualHost>.) When you call the setConfig

command and specify the configuration subkeys, you can indicate which tag you want by specifying the tag name, followed by a colon and the correct name attribute, for example:

Adaptor:_defaultRoot_/VirtualHost:www.redpin.com.

Examples

The following examples show how to set new values for configuration keys:

tSocket = new NetConnection(); tSocket.connect("rtmp://localhost/admin", "user", "password");

// set tag data in Server.xml key = "Server/LicenseInfo"; val = "SFD150-XXXXX-XXXXX-XXXXX"; tSocket.call("setConfig2", new onSetConfig(), key, val, "/");

// set tag data in Adaptor.xml key = "HostPortList/HostPort"; val = ":1935, 80, 443"; scope = "Adaptor:_defaultRoot_"; tSocket.call("setConfig2", new onSetConfig(), key, val, scope);

// set tag data in Vhost.xml key = "AppsDir"; val = "c:\\applications"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_"; tSocket.call("setConfig2", new onSetConfig(), key, val, scope);

// set tag data in Application.xml for app "foo" key = "Process/Scope"; val = "inst"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_/App:foo"; tSocket.call("setConfig2", new onSetConfig(), key, val, scope);

setConfig2() 67

// add child tag to a tag in default Application.xml key = "Process"; val = "<Scope>inst</Scope>"; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_/App"; tSocket.call("setConfig2", new onSetConfig(), key, val, scope);

// delete tag in default Application.xml key = "Process"; val = ""; scope = "Adaptor:_defaultRoot_/VHost:_defaultVHost_/App"; tSocket.call("setConfig2", new onSetConfig(), key, val, scope);

See also

getAdminContext(), getConfig2()

startServer()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

startServer([start_type])

Parameters

start_type Optional; string that specifies how you want to restart the server.

If the server is not running and you want to start it, omit this parameter. If the server is already running and you want to stop it and then restart it, you must specify parameter. (If the server is running and you omit this parameter, this command does nothing.)

restart for this

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.Admin.Command.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.

68 Server Management ActionScript Language Reference

Description

Starts the Flash Media Server service or stops it and restarts it.

You must be a server administrator to perform this operation.

See also

stopServer()

startVHost()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

startVHost(vhost_name)

Parameters

vhost_name A string that contains the name of the virtual host you want to start or the new

virtual host you want to enable, in the form

If you are enabling a new virtual host on the adaptor to which you’re connected, omit

adaptor/.

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.Command.Failed or a more specific value, if

available. Some objects might also have a describing the cause of the failure.

[adaptor/]vhost.

level property of error

description property that contains a string

Description

Starts a stopped virtual host or enables a new virtual host.

This command lets you enable a new virtual host at runtime without restarting the server. The new virtual host directory and configuration files must already be present in the server’s conf directory; the

startVHost command does not create or copy any directories or

configuration files. For information on adding virtual hosts, see Managing Flash Media Server.

You must be a server administrator to use the

startVHost() command.

startVHost() 69

Example

The following example starts a virtual host named diamond.world.com on the currently connected adaptor and then starts a virtual host named

diamond.world.com on the gem

adaptor.

/* Starts a virtual host named diamond.world.com */ nc.call("startVHost", new onStartVHost(), "diamond.world.com");

/* Starts a virtual host named diamond.world.com on the adaptor, gem */ nc.call("startVHost", new onStartVHost(), "gem/diamond.world.com");

See also

restartVHost()

stopServer()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

stopServer(stop_type)

Parameters

stop_type String; possible values are normal or abort.

If you use the value normally.

If you use the value not be allowed to stop normally.

Use the value

normal, the server shuts down, allowing running applications to end

abort, the server immediately shuts down and running applications will

abort only in an emergency or if specifying normal does not work.

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.Admin.Command.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.

70 Server Management ActionScript Language Reference

Description

Shuts down the Flash Media Server. If you use this command while users are connected, you should take steps to notify users of an imminent server shutdown so that they do not lose their work.

You must be a server administrator to perform this operation.

See also

startServer()

stopVHost()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

stopVHost([vhost_name])

Parameters

vhost_name Optional; string that contains the virtual host that you want to stop. To stop

the virtual host to which you’re connected, omit this parameter.

To stop a different virtual host, specify

You must be a server administrator to stop a virtual host other than the one to which you’re connected.

vhost_name in the form adaptor_name/vhost_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.

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

code property of NetConnection.Admin.Command.Failed 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.

Description

Stops a running virtual host. After the virtual host stops, all applications are unloaded and all users are disconnected. The virtual host does not accept any requests until it has been restarted by means of the

startVHost command or until the server is restarted.

stopVHost() 71

Example

The following example stops the virtual host tree.oak.com and then stops the virtual host

tree.oak.com on the default adaptor.

/* Stop the vhost named tree.oak.com */ nc.call("stopVHost", new onStopVHost(), "tree.oak.com");

/* Stop the vhost named tree.oak.com on the default adaptor */ nc.call("stopVHost", new onStopVHost(), "_defaultRoot_/tree.oak.com");

See also

restartVHost(), startVHost()

unloadApp()

Availability

■ Flash Player 6.

■ Flash Communication Server MX 1.0.

Usage

unloadApp(app_instance)

Parameters

app_instance A string that contains the name of the application or instance of the

application, in the form

application_name[/instance_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.

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

code property of NetConnection.Admin.Command.Failed 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.

72 Server Management ActionScript Language Reference

Description

Shuts down all instances of the specified application or instance of an application. If an application name is specified, all instances of the application are shut down and all the users who are connected to any instance of the application are immediately disconnected. If an instance of an application is specified, only that instance is shut down, and all the users who are connected to that instance are immediately disconnected.

NOTE

Before using this command, take steps to notify users of the imminent shutdown of an application.

See also

reloadApp()

unloadApp() 73

74 Server Management ActionScript Language Reference

Macromedia FLASH MEDIA SERVER 2 User Manual

Specifications and Main Features

Frequently Asked Questions

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()

getConfig()

getConfig2()

getGroupMembers()

getGroupStats()

getGroups()

getInstanceStats()

getIOStats()

getLicenseInfo()

getLiveStreams()

getLiveStreamStats()

getMsgCacheStats()

getNetStreams()

getNetStreamStats()

getRecordedStreams()

getRecordedStreamStats()

getScriptStats()

getServerStats()

getServices()

getSharedObjects()

getSharedObjectStats()

getUsers()

getUserStats()

getVHosts()

getVHostStats()

ping()

reloadApp()

removeAdmin()

removeApp()

removeVHostAlias()

restartVHost()

setConfig()

setConfig2()

startServer()

startVHost()

stopServer()

stopVHost()

unloadApp()