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

NameTypeOptionalDefaultDescripton
oUriBiUri/StringOptional URI where the XMP-RPC server resides

Properties

NameTypegetsetDescripton
asyncBooleancheckedcheckedWhether 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
loadedBooleancheckedReturns true if the XMP-RPC has finished loading the reply from the server
loadingBooleancheckedReturns true if the XMP-RPC is currently loading the reply from the server
passwordStringcheckedcheckedThe password to pass to the server when calling the remote procedure
resultObjectcheckedReturns 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.
uriBiUricheckedcheckedThe URI where to find the remote procedure
userStringcheckedcheckedThe user name to pass to the server when calling the remote procedure
xmlLoaderBiXmlLoadercheckedThis returns the XML loader that was used in the last method call

Methods

NameDescription
asyncInvokeCalls 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.
callMethodCalls 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.
syncInvokeCalls 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.
useServiceTells the XLM-RPC client where the server is located

Events

NameTypeBubblesDescripton
callcompleteBiXmlRpcCallCompleteEventThis event is fired when a method call is complete.
loadBiEventThis event is fired when a method call response is received from the server.

Static Methods

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

Possible return valuse are:

string
boolean
int
double
dateTime.iso8601
array
base64
struct
iso8601ToJsDateThis takes a date string formatted according to ISO 8601 and returns a javascript Date object to ISO 8601
jsDateToIso8601This takes a javascript Date object and returns a string formatted according to ISO 8601
jsFieldToXmlMemberNodeThis creates a <member> element that is used with XML-RPC structs
jsToXmlNodeThis encodes a javascript value as an XML node.
jsToXmlValueNodeThis creates a <value> element that contains the XML-RPC value
makeXmlRpcMessageThis returns an XML document containing the XML-RPC method call body
parseXmlRpcResponseThis takes an XML document and returns a javascript value. If there was an error a BiXmlRpcError is thrown
xmlNodeToJsReturns the javascript value that the XML node describes
xmlValueNodeToJsDecodes an RPC XML <value> element to a javascript value

Static Fields

NameTypeDescripton
MAX_INTNumberThe 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

NameTypeOptionalDefaultDescripton
sMethodNameStringThe name of the method to call
oArgObjectcheckedOne 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

NameTypeOptionalDefaultDescripton
sMethodNameStringThe name of the method to call
oArgObjectcheckedOne 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

NameTypeOptionalDefaultDescripton
sMethodNameStringThe name of the method to call
oArgObjectcheckedOne 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

NameTypeOptionalDefaultDescripton
oUriBiUriThe 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

NameTypeOptionalDefaultDescripton
vObjectThe 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

NameTypeOptionalDefaultDescripton
sStringThe 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

NameTypeOptionalDefaultDescripton
dDateThe 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

NameTypeOptionalDefaultDescripton
sNameStringThe field name
vObjectThe javascript value
docBiXmlDocumentThe 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

NameTypeOptionalDefaultDescripton
vObjectThe javascript value
docBiXmlDocumentThe 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

NameTypeOptionalDefaultDescripton
vObjectThe javascript value
docBiXmlDocumentThe 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

NameTypeOptionalDefaultDescripton
sMethodNameStringThe name of the method to call
argsArrayAn 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

NameTypeOptionalDefaultDescripton
docBiXmlDocumentThe xml document containing the method response

Return Type

Object

xmlNodeToJs

Returns the javascript value that the XML node describes

Syntax

BiXmlRpc . xmlNodeToJs ( n )

Parameters

NameTypeOptionalDefaultDescripton
nNodeThe XML node

Return Type

Object

xmlValueNodeToJs

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

Syntax

BiXmlRpc . xmlValueNodeToJs ( n )

Parameters

NameTypeOptionalDefaultDescripton
nNodeThe XML element that describes the value

Return Type

Object