MACROMEDIA FLASH MEDIA SERVER 2-SERVER MANAGEMENT ACTIONSCRIPT... Service 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

3
Contents
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

4
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

5
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.
You establish a connection using the NetConnection.connect() method, passing in three
parameters: the URI of the host administration server, an administrator user name, and an
administrator password.
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.

6 Server Management ActionScript Language Reference
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 NetConnection.connect method.
The following example shows the call that lets the administrator MHill with password
635xjh27 connect to the server on localhost:
nc = new NetConnection();
nc.connect("rtmp://localhost:1111/admin", "MHill", "635xjh27");
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 getAppStats method is called to retrieve the performance data
of a running application; the callback handler new receiveAppStats captures the result of
the call; and the value ChatApp is a required parameter that specifies the name of the
application:
nc = new NetConnection();
nc.connect("rtmp://localhost:1111/admin", "MHill", "635xjh27");
// Call getAppStats
nc.call("getAppStats", new receiveAppStats(), "ChatApp");

A simple application example 7
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.
/** 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")
outputBox.text = "Call failed: " + info.description;
else {
outputBox.text = "Info for "+appName.text+ " returned:" + ¬
newline;
printObj(info, outputBox);
}
}
}
nc.call("getAppStats", new onGetAppStats(), appName.text);
}
// 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)
NOTE
The continuation character (¬) indicates that the code continues to the next line; this
character should not appear in code.

8 Server Management ActionScript Language Reference
{
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");
}
}

Method summary 9
Information objects
All Server Management ActionScript API methods return data in an information object with
the following properties: level, code, timestamp, data, description, and details. All
information objects have level, code, and timestamp properties. Some methods have the
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.
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.
Code Level Meaning
NetConnection.Call.Success Status The call is successful.
This information object includes a data
property, which returns detailed information
in an object or array.
NetConnection.Admin.CommandFailed Error The method called is nonexistent.*
NetConnection.Call.Failed Error A general failure has occurred.*
NetConnection.Call.BadValue Error The value of a parameter is invalid.*
* This information object contains description and detail properties, which are strings that
provide a more specific reason for the failure.

10 Server Management ActionScript Language Reference
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.
Queries for monitoring the server
The following table lists the methods you can use to monitor the server.
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.
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.