/*
 *	qwiRemoting.as
 *
 *	General Flash Remoting NetServices client-side utility functions
 *
 *	Copyright: Dave Yang / Quantumwave Interactive Inc.
 *
 *	Website: http://www.quantumwave.com/
 *
 * Version: 2.01
 *
 * Globals defined (place in namespace if needed):
 *		_global.gatewayURL
 *		_global.servicePath
 *		_global.NetServices.Responder
 *		_global.invokeService
*/
//===========================================================================

#include "NetServices.as"

//===========================================================================

// URL to the Flash Remoting gateway
// The following sets the gatewayURL to the default domain gateway.
// Override in the main application if needed: e.g. gatewayURL = "http://subdomain.domain.com/flashservices/gateway";
_global.gatewayURL = "http://localhost/flashservices/gateway";

// path to the .cfc or .asr folder from the webroot (include . at the end)
// e.g. servicePath = "cfc.";  // cfc folder is at the webroot
_global.servicePath = "";

//===========================================================================

/**
 *	NetServices.Responder Class
 *
 *	@param	r [function] - reference to the function to invoke when getService is successful.
 *	@param	s [function] - optional: reference to the function to invoke when error occurred.
 * @param	ref [function] - optional: reference to the calling object instance. Creates a _self property.
 *
 *	@usage	new NetServices.Responder(responder [,errorHandler|null], [ref]);
 */
if (NetServices.Responder == undefined) {
	NetServices.Responder = function(r, s, ref) {
		this.onResult = r;
		if (s != undefined) this.onStatus = s;
		if (ref != undefined) this._self = ref;
	};

	// Default error handler to standardize error handling.
	// Override by supplying the optional errorHandler to the constructor for individual service calls when needed.
	NetServices.Responder.prototype.onStatus = function(e) {
		//trace("onStatus: " + e.description);
		for (var p in e) trace("onStatus: " + p +": "+ e[p]);
		// optional: pop an alert box [alert code not part of this include library]
		// alert("Net service error encountered:\n"+ e.description);
	};
}

//===========================================================================

/**
 * Invoke a method of a service (.cfc, .asr ...etc.)
 *
 * @param	srvName [string] - name of the service or component.
 *	@param	srvMethod [string] - name of the method.
 * @param	argsObj [object|null] - arguments object (or null).
 * @param	responder [function] - reference to the result handler function.
 * @param	errorHandler [function] - optional: reference to the error handler function.
 * @param	ref [function] - optional: reference to the object instance invoking the service.
 * @param	baseURL [string] - optional: the gatewayURL to override the default gatewayURL
 *
 * @return	reference to the remoting service object, or null if error occurred.
 *
 * @example	invokeService("customers", "getRegistered", {userID:id, password:pswd}, onGetRegistered);
 */
_global.invokeService = function(srvName, srvMethod, argsObj, responder, errorHandler, ref, baseURL) {
	if ((NetServices._nc == undefined) || (baseURL != undefined)) {
		if (baseURL == undefined) baseURL = gatewayURL;
		NetServices._nc = NetServices.createGatewayConnection(baseURL);
	}

	var r = new NetServices.Responder(responder, errorHandler, ref);
	var srv = NetServices._nc.getService(servicePath+srvName, r);
	srv[srvMethod](argsObj);

	return {responder:r, service:srv};
};

//===========================================================================

/**
 *	Example usage of invokeService():
 *
 *	#include "qwiRemoting.as"
 *
 *	// CFCs are located at the <webroot>/customers/cfc/ folder
 *	servicePath = "customers.cfc.";
 *
 *	onGetRegistered = function() {
 *		// handle successful getService result
 *	};
 *
 *	// invoke the method 'getRegistered()' in file 'customers.cfc' (or .asr)
 *	// assume id & pswd are already defined
 *	invokeService("customers", "getRegistered", {userID:id, password:pswd}, onGetRegistered);
 */