TechNote (Archived)

Troubleshooting communications applications

Introduction

When developing applications with Macromedia Flash Communication Server, troubleshooting can involve using a number of different tools and errors can occur in a number of different places. This document provides some troubleshooting tips for locating and resolving errors on both the client and the server platform. This information is targeted for developers who are relatively new to ActionScript Flash Communication Application Development. For more advanced information on ActionScript and Communications ActionScript please see ActionScript coding standards and Writing Flash Communication Server Applications.

Server installation
Troubleshooting cameras and microphones
Debugging Client-Side Communications ActionScript
Debugging Server-Side Communications ActionScript
Using the Admin API
General troubleshooting tips
Additional information

Server installation

If your applications are not able to connect to the Macromedia Flash Communication Server, then check to see if the service is running. You can do this by going to the Services control panel (Start > Programs > Administrative Tools > Services).

For additional information on troubleshooting an installation of Flash Communication Server, please see Installing Macromedia Flash Communication Server (TechNote 16446).

Troubleshooting cameras and microphones

For configuring a microphone before using it with Macromedia Flash Player 6, follow steps in Configuring a microphone (TechNote 16451).

You can test your camera and microphone in the Macromedia Flash player by right-clicking and selecting "settings". Click the camera and microphone icons to change the setting for each. Sometimes a camera or microphone will not work with the Flash Player until you test it in the settings dialog.

For more information on using audio in your applications, seeMacromedia Flash Communication and Audio (TechNote 16447).

If your camera feed is not showing up, make sure it is not in use by another application. The player used for testing in the Macromedia Flash authoring environment is considered a different application than the player that runs in a browser window. For a complete description of this issue, please see Possible problems displaying local camera feed (TechNote 16440).

It is important to remember that a given device can only be captured once. You cannot create two references to a given camera or microphone feed and then try and adjust the settings independently. What you do to one, you do to the other. For a more complete description of this issue, see Problems using multiple settings for one capture source (TechNote 16457).

Debugging Client-Side Communications ActionScript

The NetConnection object can be a common source of problems when writing Client-Side Communications ActionScript.

Using a lot of informative trace statements in your code can help troubleshooting the problem. Just be sure to remove all of them when you are ready to deploy your application.

Always define the onStatus handler for a NetConnection before using the connect() method. A typical NetConnection might look like this:

 connection_nc = new NetConnection();  connection_nc.onStatus = function(info){    trace("level is: " + info.level + "\n" + "code is: " + info.code);  }
		

	 connection_nc.connect("rtmp:/myAppName");

Make sure you have correctly spelled the name of the application you are connecting to in the URI.
Make sure you are using the right kind of URI as well. For more information on the difference between a relative and an absolute URI, please see Relative vs. Absolute URI's (TechNote 16439). Also read the entry for NetConnection.connect in the Client-Side Communications ActionScript Dictionary.
If you are using an absolute URI, make sure you are connecting to the right server and that the Flash Communication Server service is up and running when you look at the Services Control Panel in Windows.
One of the most important troubleshooting tools is the NetConnection Debugger. To use the NetConnection Debugger, you must have the include directive on the first line of frame 1 of your movie:
```
 #include "NetDebug.as" 
```
This will allow NetConnection related errors to be written to the events window of the NetConnection Debugger.

For information on troubleshooting the NetConnection Debugger, see Errors reported when using the NetConnection Debugger (TechNote 16459).

For information on Using the NetConnection Debugger with multiple NetConnections, see (TechNote 16441)

The NetStream Object can also be tested in various ways:

Use the onStatus handler for the NetStream Object to check status and error messages for a given NetStream. A list of the info objects can be found in the appendix of the Client-Side Communications ActionScript Dictionary. An onStatus handler for a NetStream object might look like this:
```
 mystream_ns.onStatus = function(info){  trace("level is: " + info.level);
		

	      trace("code is: " + info.code);
		

	      trace("description is: " + info.description);
		

	      trace("details are: " + info.details");
		

	 } 
```
If you are having problems with streams not playing or not stopping when you attempt to close them, then check the syntax of your NetStream.play() and NetStream.close() commands. If you omit the parentheses, the syntax checker in Macromedia Flash will not catch it, but the method will not be executed and will be mistaken for an object property.
Be sure to use NetStream.close() before you delete a video object or movie clip that is using audio or video from that NetStream. If the NetStream is not terminated properly using the close() method, you can end up with "ghost" streams that hang around until garbage collection comes along. Until that happens data can be needlessly sent and received. It is always best to close a NetStream.

Shared Objects in Client-Side ActionScript can also be a source of problems and there are a few things to remember:

You must connect to SharedObjects before you can use them. It's easy to forget to actually connect to a SharedObject after defining it. You must have connected to a valid NetConnection before attempting to connect to a SharedObject and you must use that NetConnection reference in the connect method.

If a socket_nc is a defined NetConnection, the connect method for a SharedObject might look like this:
```
 mySharedObject_so.connect(socket_nc); 
```
SharedObjects must use either a hard coded URI or the URI property of some NetConnection as the remotePath parameter. If connection_nc is a NetConnection defined in your ActionScript, then you could define a remote SharedObject like this:
```
 userInfo_so   = SharedObject.getRemote("users", connection_nc.uri, false); 
```
You could hard code a URI, but using the URI property of a NetConnection is better because the URI could potentially change when porting your application from a development environment to a deployment environment.
You must correctly match the name of the SharedObject being connected to. For example, if you define a remote SharedObject on the client like this:
```
 client_so   = SharedObject.getRemote("sharedObjectName", false); 
```
Then you must define that SharedObject on the server using the same name.
```
 application.server_so  = SharedObject.get("sharedObjectName", false); 
```
You must also avoid timing issues with SharedObjects. Make sure you are not trying to access information stored in them before the information is written to them. The onStatus handler is a good place to put code that will either manipulate the contents of the SharedObject or will tell other parts of your application that it is OK to access them.

Debugging Server-Side Communications ActionScript

The best way to troubleshoot Server-Side Communications ActionScript is to use the Communications App Inspector. You can access it in two ways. One is to select it from the Windows menu in Macromedia Flash MX. Another way to access it is through the Administration Console.

The Administration Console runs on a separate port (port 1111) for security reasons, but can be accessed locally with this URL: http://localhost/flashcom/admin/admin.html

Expanding the Server Tools section of the tree menu on the left reveals the link to the Communications App Inspector. If you cannot establish a connection to the Administration Console or the Communications Application Inspector, then make sure the Flash Communication Admin Service is up and running on the Services Control Panel in Windows.

Once the Communications App Inspector is running the Server-Side ActionScript errors are written to the Live Logs tab for a given application instance. To see the Live Logs tab, select an active application instance and click the View Detail button.

Sometimes, however, the application cannot start because of errors in the .asc file. In this case, a will appear near the lower right corner of the main page of the Communications App Inspector which lists all the active application instances. Click this icon and a list of errors encountered in the Server-Side ActionScript will be displayed.

Below is a list of issues you may encounter with Server-Side ActionScript along with some troubleshooting tips.

Problems with SharedObjects can be resolved by keeping in mind the following things.

SharedObjects belong to the application object and they must be referenced like this:
```
 application.users_so.get("users", false); 
```
Without the application prefix, they will not be defined properly.
SharedObjects residing in other applications must use the URI of a NetConnection as the remotePath parameter. There is no connect() method for SharedObjects in Server-Side Communications ActionScript.
There is no data property for SharedObjects in Server-Side Communications ActionScript so the following code will not reference a SharedObject successfully:
```
 application.users_so.data.someProperty = someValue 
```
You must change the values of SharedObject properties using the SharedObject.setProperty() method:
```
 application.users_so.setProperty (someProperty, someValue) 
```

The Stream Object can be approached in much the same way as the NetStream object in Server-Side Communications ActionScript.

If you are having problems deleting streams then check to make sure you have used parentheses. The following syntax will not work:
```
 someStream.clear; 
```
This is the correct syntax:
```
 someStream.clear(); 
```
Be sure to set an appropriate value for stream.bufferTime. For higher quality FLV files, the bufferTime should be increased from the default value of 2 seconds especially for low bandwidth networks.

As always, use the onStatus handler to trace information about the stream and why it might be failing.

 myStream.onStatus = function(info){  trace("level is: " + info.level);  trace("code is: " + info.code);  trace("description is: " + info.description);  trace("details are: " + info.details);
		

	 }

Defining functions can be done in several different ways depending on the kind of function. It is important you define functions correctly or they will not be called successfully.

Event handlers are defined differently than regular global functions. For example, the onAppStart handler is defined like this:
```
 application.onAppStart = function (){  //your code here  } 
```

A global function, like one prototyped from the Client object would look like this:

 Client.prototype.myMethodName = Client_myMethodName;
		

	 function Client_myMethodName(someClientObj){  //your code here  }

If parameters are not getting passed to a Server-Side function, there may be an error in your Client-Side Communications ActionScript. When calling a function using NetConnection.call and a return object is not specified, either a value of "false" or"null" must be specified. Otherwise, the Server-Side method will expect the first parameter you send to be a return object. So be sure your NetConnection.call method is of the following form.
```
 connection.nc.call("methodToCall", false, param1, paramN); 
```
If you did specify a return object, it would look something like this:
```
 connection.nc.call("methodToCall", new someReturnObj(), param1, paramN); 
```

The NetConnection Object as implemented in Server-Side Communications ActionScript can approached in much the same manner as it is in Client-Side Communications ActionScript.

During development, use the onStatus handler to trace information about the connection and why it may be failing.

 admin_nc.onStatus = function(info){  trace("level is: " + info.level);  trace("code is: " + info.code);  trace("description is: " + info.description);  trace("rejected because: " + info.application);  }

Be sure to specify a valid URI in the NetConnection.connect() method.
Make sure the Macromedia Flash Communication Server you are connecting to is up and running.
Make sure the server making the connection has an entry in the<ServerDomain> tag in Server.xml. Without this, the referrer header tag will be empty when the NetConnection to a remote server is made. Any attempts to authenticate based on this header information will then fail.

Using the Admin API
The Admin API should be used with some specific things in mind as well.

When using the Admin API in both Client-Side and Server-Side Communications ActionScript, it is important to remember that an onResult handler must be defined for every call made through a NetConnection to the Admin Server. This onResult handler always takes an information object as a parameter. For example, the following code makes a call to the getUsers method of the Admin API, and sets a variable equal to the length of the array returned by the getUsers method:
```
 function getCurrentUsers(){  function onUsers(){  this.onResult = function(info){
		

	                var len = info.data.length;  }  }  adminConnection_nc.call("getUsers", new onUsers(), "someApp/_defInst_");    } 
```
For more information, see the documentation for the Admin API.
Make sure that the Flash Communication Admin Service is up and running on the Services Control Panel in Windows when using the Admin API.
Make sure that you specify the right port number that the Admin Server is using, as well as the correct username and password, when you connect to it.
```
 adminConnection_nc.connect("rtmp://localhost:1111/admin", "adminUserName", "adminPassWord"); 
```
Make sure you are not behind a firewall when trying to access the Admin Server or make sure that your firewall allows traffic on the port number being used by the Admin Server. It's probably best to only connect to the Admin Server from within your firewall. One of the reasons the Admin Server runs on a different port is for the purpose of allowing for firewall based security. You may also use the <Allow> and <Deny> tags in the Server.xml file to restrict access to the Admin Server.

General troubleshooting tips

When writing code for a function, or conditional logic, or anything that requires opening and closing brackets, it is a good idea to type both the opening and closing brackets before typing the body of the function.

For example, start with the syntax below before writing the actual code. This way, if your function gets complex, it will be easier to maintain the proper number of opening and closing brackets.
```
 function doSomeStuff(){
		

	      //code will go here
		

	 } 
```
Remember that Server-Side Communications ActionScript is case sensitive while Client-Side Communications ActionScript is not case sensitive.