BiXmlRpc

This is a class that implements an XML-RPC client. The XML-RPC specifcation can be found at http://www.xmlrpc.com/spec. For more info and XML-RPC server implementations see http://www.xmlrpc.com/.

This class extends BiEventTarget and therefore all methods and fields available for BiEventTarget are also available for BiXmlRpc .

Constructor

new BiXmlRpc ( [ oUri ] )

Parameters

Name	Type	Optional	Default	Descripton
oUri	BiUri/String			Optional URI where the XMP-RPC server resides

Properties

Name	Type	get	set	Descripton
async	Boolean			Whether to use asynchronous method call. If this is true then the call to callMethod returns instantly. When using asynchronous calling use the result event for the call back
loaded	Boolean			Returns true if the XMP-RPC has finished loading the reply from the server
loading	Boolean			Returns true if the XMP-RPC is currently loading the reply from the server
password	String			The password to pass to the server when calling the remote procedure
result	Object			Returns the result value. This is only available during the load event. If there was an error receiving the result from the server an exception is thrown.
uri	BiUri			The URI where to find the remote procedure
user	String			The user name to pass to the server when calling the remote procedure
xmlLoader	BiXmlLoader			This returns the XML loader that was used in the last method call

Methods

Name	Description
asyncInvoke	Calls the method with the given name and arguments. This uses asynchronous loading and to get the result listen to the callcomplete event. Arguments 1 to n are passed to the XML-RPC method. If a method call is already in progress it will be aborted before this new call is invoked.
callMethod	Calls the method with the given name and arguments. If the XML-RPC client is using synchronous loading the thread is halted until a response is received from the server. If using async loading use the load event to get the result. Arguments 1 to n are passed to the XML-RPC method. If a method call is already in progress it will be aborted before this new call is invoked.
syncInvoke	Calls the method with the given name and arguments. This uses synchronous loading and will therefore lock the js thread while it is waiting for the reply from the server. Arguments 1 to n are passed to the XML-RPC method. If the server generated an error a BiXmlRpcError is thrown. If a method call is already in progress it will be aborted before this new call is invoked.
useService	Tells the XLM-RPC client where the server is located

Events

Name	Type	Bubbles	Descripton
callcomplete	BiXmlRpcCallCompleteEvent		This event is fired when a method call is complete.
load	BiEvent		This event is fired when a method call response is received from the server.

Static Methods

Name	Description
getJsType	This takes a javascript value and returns the XML-RPC type name. Possible return valuse are: string boolean int double dateTime.iso8601 array base64 struct
iso8601ToJsDate	This takes a date string formatted according to ISO 8601 and returns a javascript Date object to ISO 8601
jsDateToIso8601	This takes a javascript Date object and returns a string formatted according to ISO 8601
jsFieldToXmlMemberNode	This creates a <member> element that is used with XML-RPC structs
jsToXmlNode	This encodes a javascript value as an XML node.
jsToXmlValueNode	This creates a <value> element that contains the XML-RPC value
makeXmlRpcMessage	This returns an XML document containing the XML-RPC method call body
parseXmlRpcResponse	This takes an XML document and returns a javascript value. If there was an error a BiXmlRpcError is thrown
xmlNodeToJs	Returns the javascript value that the XML node describes
xmlValueNodeToJs	Decodes an RPC XML <value> element to a javascript value

Static Fields

Name	Type	Descripton
MAX_INT	Number	The max value for a 4 byte integer

Remarks

The struct type is represented by the Object type The base64 type is represented by the BiBase64 class. To ensure that a number is encoded as a double you can use BiXmlRpcDouble. If you want to ensure that a number is encoded as an int you can either use BiXmlRpcInt or make sure that the the number does not have any decimals (using Math.floor, Math.ceil or Math.round). The XML-RPC client only supports one call at a time. If a call is in progress and another call is made the first one is aborted.

Method Details

asyncInvoke

Calls the method with the given name and arguments. This uses asynchronous loading and to get the result listen to the callcomplete event. Arguments 1 to n are passed to the XML-RPC method. If a method call is already in progress it will be aborted before this new call is invoked.

Syntax

object.asyncInvoke
 (
 sMethodName
 [
 ,oArg
 ]
 
 )
 

Parameters

Name	Type	Optional	Default	Descripton
sMethodName	String			The name of the method to call
oArg	Object			One or more arguments that are passed to to the method.

Return Type

void

callMethod

Calls the method with the given name and arguments. If the XML-RPC client is using synchronous loading the thread is halted until a response is received from the server. If using async loading use the load event to get the result. Arguments 1 to n are passed to the XML-RPC method. If a method call is already in progress it will be aborted before this new call is invoked.

Syntax

object.callMethod
 (
 sMethodName
 [
 ,oArg
 ]
 
 )
 

Parameters

Name	Type	Optional	Default	Descripton
sMethodName	String			The name of the method to call
oArg	Object			One or more arguments that are passed to to the method.

Return Type

Object

syncInvoke

Calls the method with the given name and arguments. This uses synchronous loading and will therefore lock the js thread while it is waiting for the reply from the server. Arguments 1 to n are passed to the XML-RPC method. If the server generated an error a BiXmlRpcError is thrown. If a method call is already in progress it will be aborted before this new call is invoked.

Syntax

object.syncInvoke
 (
 sMethodName
 [
 ,oArg
 ]
 
 )
 

Parameters

Name	Type	Optional	Default	Descripton
sMethodName	String			The name of the method to call
oArg	Object			One or more arguments that are passed to to the method.

Return Type

Object

useService

Tells the XLM-RPC client where the server is located

Syntax

object.useService
 (
 oUri
 )
 

Parameters

Name	Type	Optional	Default	Descripton
oUri	BiUri			The URI where to find the remote procedure

Return Type

void

Static Method Details

getJsType

This takes a javascript value and returns the XML-RPC type name.

Possible return valuse are:

string
boolean
int
double
dateTime.iso8601
array
base64
struct

Syntax

BiXmlRpc
 .
 getJsType
 (
 v
 )
 

Parameters

Name	Type	Optional	Default	Descripton
v	Object			The js value to get the type name for

Return Type

String

iso8601ToJsDate

This takes a date string formatted according to ISO 8601 and returns a javascript Date object to ISO 8601

Syntax

BiXmlRpc
 .
 iso8601ToJsDate
 (
 s
 )
 

Parameters

Name	Type	Optional	Default	Descripton
s	String			The string representing the date

Return Type

Date

jsDateToIso8601

This takes a javascript Date object and returns a string formatted according to ISO 8601

Syntax

BiXmlRpc
 .
 jsDateToIso8601
 (
 d
 )
 

Parameters

Name	Type	Optional	Default	Descripton
d	Date			The javascript date object

Return Type

String

jsFieldToXmlMemberNode

This creates a <member> element that is used with XML-RPC structs

Syntax

BiXmlRpc
 .
 jsFieldToXmlMemberNode
 (
 sName,v,doc
 )
 

Parameters

Name	Type	Optional	Default	Descripton
sName	String			The field name
v	Object			The javascript value
doc	BiXmlDocument			The document that will contain the complete XML-RPC message

Return Type

Node

jsToXmlNode

This encodes a javascript value as an XML node.

Syntax

BiXmlRpc
 .
 jsToXmlNode
 (
 v,doc
 )
 

Parameters

Name	Type	Optional	Default	Descripton
v	Object			The javascript value
doc	BiXmlDocument			The document that will contain the complete XML-RPC message

Return Type

Node

jsToXmlValueNode

This creates a <value> element that contains the XML-RPC value

Syntax

BiXmlRpc
 .
 jsToXmlValueNode
 (
 v,doc
 )
 

Parameters

Name	Type	Optional	Default	Descripton
v	Object			The javascript value
doc	BiXmlDocument			The document that will contain the complete XML-RPC message

Return Type

Node

makeXmlRpcMessage

This returns an XML document containing the XML-RPC method call body

Syntax

BiXmlRpc
 .
 makeXmlRpcMessage
 (
 sMethodName,args
 )
 

Parameters

Name	Type	Optional	Default	Descripton
sMethodName	String			The name of the method to call
args	Array			An array containing the arguments

Return Type

BiXmlDocument

parseXmlRpcResponse

This takes an XML document and returns a javascript value. If there was an error a BiXmlRpcError is thrown

Syntax

BiXmlRpc
 .
 parseXmlRpcResponse
 (
 doc
 )
 

Parameters

Name	Type	Optional	Default	Descripton
doc	BiXmlDocument			The xml document containing the method response

Return Type

Object

xmlNodeToJs

Returns the javascript value that the XML node describes

Syntax

BiXmlRpc
 .
 xmlNodeToJs
 (
 n
 )
 

Parameters

Name	Type	Optional	Default	Descripton
n	Node			The XML node

Return Type

Object

xmlValueNodeToJs

Decodes an RPC XML <value> element to a javascript value

Syntax

BiXmlRpc
 .
 xmlValueNodeToJs
 (
 n
 )
 

Parameters

Name	Type	Optional	Default	Descripton
n	Node			The XML element that describes the value

Return Type

Object