package com.natejc.utils.communication
{
	

// **********************************************************************************
// **********************************************************************************


	/**
	 * Allow any function to be "registered," which, by doing so, allows direct global access to the function. 
	 * 
	 * Note: This class is open source. See http://blog.natejc.com for more details.
	 * 
	 * @author Nate Chatellier
	 */
	public class RegisteredSocketFunctions
	{
		protected static var _aFuncList:Array;			// a mapped array of Function references
		protected static var _aThisObjectList:Array;	// a mapped array of "this" references
		protected static var _bInited:Boolean;			// true if this class as been initialized
		
		
		/**
		 * There's no constructor. RegisteredSocketFunctions is a static class and should not be instantiated.
		 */
		public function RegisteredSocketFunctions()
		{
			trace("RegisteredSocketFunctions is a static class and should not be instantiated.")
		} // END CONSTRUCTOR

		
	// **********************************************************************************

	
		/**
		 * Initializes this class.
		 */
		protected static function init():void
		{
			if (!_bInited)
			{
				_bInited = true;
				_aFuncList = new Array();
				_aThisObjectList = new Array();
			} // END IF
			
		} // END FUNCTION init
		
		
	// **********************************************************************************

	
		/**
		 * Adds a new function to the list of available socket function calls.
		 * 
		 * @param	sFName			Socket function call string reference name.
		 * @param	funcReference	A Function reference to the actual function.
		 * @param	thisObject		A reference to the object that should be the "this" object when this function is executed.
		 * 
		 * @usage	RegisteredSocketFunctions.registerFunction("myTestFunction", myTestFunction, this);
		 * 
		 * @see		unregisterFunction
		 */
		public static function registerFunction(sFName:String, funcReference:Function, thisObject:Object):void
		{
			init();
			
			if (_aFuncList[sFName]) _aFuncList[sFName] = null;
			_aFuncList[sFName] = funcReference;
			_aThisObjectList[sFName] = thisObject;
			trace("registerFunction(sFName:"+sFName+/*", funcReference:"+funcReference+*/", thisObject:"+thisObject+") -> registration successful");
			
		} // END FUNCTION registerFunction
		
		
	// **********************************************************************************

	
		/**
		 * Removes a function from the list of registered socket function calls.
		 * 
		 * @param	sFName	The socket function call that should be removed.
		 * 
		 * @usage	RegisteredSocketFunctions.unregisterFunction("myTestFunction");
		 * 
		 * @see		registerFunction
		 */
		public static function unregisterFunction(sFName:String):void
		{
			if (_bInited && _aFuncList[sFName])
				_aFuncList[sFName] = null;
			else
				trace(" *** WARNING in RegisteredSocketFunctions.unregisterFunction(sFName:"+sFName+") -> "+sFName+" is not a registered function");
			
		} // END FUNCTION unregisterFunction
		
		
	// **********************************************************************************

	
		/**
		 * Executes a Function that was previously registered using <code>registerFunction</code> with the name <code>sFName</code>.
		 *
		 * @param	sFName		The string reference name of the function that is to be executed.
		 * @param	argArray	The optional list of parameters that should be executed with the function.
		 * @param	thisObject	The optional object to which the Function referenced by sFName is applied. The "this" operator   
		 * 						for the executed function will be <code>thisObject</code> if <code>thisObject</code> is non-null; 
		 * 						Otherwise, it will be the <code>thisObject</code> specified when registerFunction was called.
		 * 
		 * @return	Returns whatever value (if any) is returned by the function being called.
		 * 
		 * @usage	RegisteredSocketFunctions.registerFunction("myTestFunction", [var1, var2]);
		 * 
		 * @see		registerFunction
		 */
		public static function executeFunction(sFName:String, argArray:Array = null, thisObject:Object = null):*
		{
			if (!_bInited)
			{
				trace(" *** ERROR in RegisteredSocketFunctions.executeFunction(sFName:"+sFName+", argArray:["+argArray+"]) -> RegisteredSocketFunctions has not been initialized");
			}
			else if (_aFuncList[sFName])
			{
				if (!thisObject)
					thisObject = _aThisObjectList[sFName];
				
				var returnObj:* = null;
				try
				{
					returnObj = _aFuncList[sFName].apply(thisObject, argArray);
				}
				catch (e:Error)
				{
					trace(" *** ERROR in RegisteredSocketFunctions.executeFunction(sFName:"+sFName+", argArray:["+argArray+"]) -> could not execute function: "+e);
				}
				finally
				{
					return returnObj;
				} // END TRY
			}
			else
			{
				trace(" *** WARNING in RegisteredSocketFunctions.executeFunction(sFName:"+sFName+", argArray:["+argArray+"]) -> "+sFName+" is not a registered function");
			} // END IF
			
			return null;
			
		} // END FUNCTION executeFunction
	
		
// **********************************************************************************
// **********************************************************************************

	} // END CLASS RegisteredSocketFunctions
} // END PACKAGE