Class XmlRpcClient

Allows applications to send remote procedure calls by using the Extensible Markup Language Remote Procedure Call (XML-RPC) protocol.

Inheritance

System.Object

XmlRpcClient

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Argotic.Net

Assembly: Argotic.Core.dll

Syntax

public class XmlRpcClient

Remarks

This implementation of XML-RPC is based on the XML-RPC 1.0 specification which can be found at http://www.xmlrpc.com/spec.

XML-RPC is a Remote Procedure Calling protocol that works over the Internet.

An XML-RPC message is an HTTP-POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML.

Procedure parameters can be scalars, numbers, strings, dates and other simple types; and can also be complex record and list structures.

Examples

Constructors

XmlRpcClient()

Initializes a new instance of the XmlRpcClient class.

Declaration

public XmlRpcClient()

XmlRpcClient(Uri)

Initializes a new instance of the XmlRpcClient class that sends remote procedure calls using the specified XML-RPC server.

Declaration

public XmlRpcClient(Uri host)

Parameters

Type	Name	Description
System.Uri	host	A System.Uri that represents the URL of the host computer used for XML-RPC transactions.

Exceptions

Type	Condition
System.ArgumentNullException	The host is a null reference (Nothing in Visual Basic).

XmlRpcClient(Uri, String)

Initializes a new instance of the XmlRpcClient class that sends remote procedure calls using the specified XML-RPC server and user agent.

Declaration

public XmlRpcClient(Uri host, string userAgent)

Parameters

Type	Name	Description
System.Uri	host	A System.Uri that represents the URL of the host computer used for XML-RPC transactions.
System.String	userAgent	Information such as the application name, version, host operating system, and language.

Exceptions

Type	Condition
System.ArgumentNullException	The host is a null reference (Nothing in Visual Basic).
System.ArgumentNullException	The userAgent is a null reference (Nothing in Visual Basic).
System.ArgumentNullException	The userAgent is an empty string.

Properties

Credentials

Gets or sets the authentication credentials utilized by this client when making remote procedure calls.

Declaration

public ICredentials Credentials { get; set; }

Property Value

Type	Description
System.Net.ICredentials	A System.Net.ICredentials object that represents the authentication credentials provided by this client when making remote procedure calls. The default is a null reference (Nothing in Visual Basic), which indicates no authentication information will be supplied to identify the maker of the request.

Host

Gets or sets the location of the host computer that client remote procedure calls will be sent to.

Declaration

public Uri Host { get; set; }

Property Value

Type	Description
System.Uri	A System.Uri that represents the URL of the host computer used for XML-RPC transactions.

Remarks

If Host is a null reference (Nothing in Visual Basic), Host is initialized using the settings in the application or machine configuration files.

Exceptions

Type	Condition
System.ArgumentNullException	The value is a null reference (Nothing in Visual Basic).

Proxy

Gets or sets the web proxy utilized by this client to proxy remote procedure calls.

Declaration

public IWebProxy Proxy { get; set; }

Property Value

Type	Description
System.Net.IWebProxy	A System.Net.IWebProxy object that represents the web proxy utilized by this client to proxy remote procedure calls. The default is a null reference (Nothing in Visual Basic), which indicates no proxy will be used to proxy the request.

Timeout

Gets or sets a value that specifies the amount of time after which asynchronous send operations will time out.

Declaration

public TimeSpan Timeout { get; set; }

Property Value

Type	Description
System.TimeSpan	A System.TimeSpan that specifies the time-out period. The default value is 15 seconds.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The time out period is less than zero.
System.ArgumentOutOfRangeException	The time out period is greater than a year.

UseDefaultCredentials

Gets or sets a System.Boolean value that controls whether the System.Net.CredentialCache.DefaultCredentials are sent when making remote procedure calls.

Declaration

public bool UseDefaultCredentials { get; set; }

Property Value

Type	Description
System.Boolean	true if the default credentials are used; otherwise false. The default value is false.

Remarks

Some XML-RPC servers require that the client be authenticated before the server executes remote procedures on its behalf. Set this property to true when this XmlRpcClient object should, if requested by the server, authenticate using the default credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios.

Credentials information can also be specified using the application and machine configuration files. For more information, see XmlRpcClientNetworkElement Element (Network Settings).

If the UseDefaultCredentials property is set to false, then the value set in the Credentials property will be used for the credentials when connecting to the server. If the UseDefaultCredentials property is set to false and the Credentials property has not been set, then remote procedure calls are sent to the server anonymously.

UserAgent

Gets or sets information such as the client application name, version, host operating system, and language.

Declaration

public string UserAgent { get; set; }

Property Value

Type	Description
System.String	Information such as the client application name, version, host operating system, and language. The default value is an agent that describes this syndication framework.

Exceptions

Type	Condition
System.ArgumentNullException	The value is a null reference (Nothing in Visual Basic).
System.ArgumentNullException	The value is an empty string.

Methods

OnMessageSent(XmlRpcMessageSentEventArgs)

Raises the SendCompleted event.

Declaration

protected virtual void OnMessageSent(XmlRpcMessageSentEventArgs e)

Parameters

Type	Name	Description
XmlRpcMessageSentEventArgs	e	A XmlRpcMessageSentEventArgs that contains the event data.

Remarks

Classes that inherit from the XmlRpcClient class can override the OnMessageSent(XmlRpcMessageSentEventArgs) method to perform additional tasks when the SendCompleted event occurs.

OnMessageSent(XmlRpcMessageSentEventArgs) also allows derived classes to handle SendCompleted without attaching a delegate. This is the preferred technique for handling SendCompleted in a derived class.

ScalarTypeAsString(XmlRpcScalarValueType)

Returns the scalar type identifier for the supplied XmlRpcScalarValueType.

Declaration

public static string ScalarTypeAsString(XmlRpcScalarValueType type)

Parameters

Type	Name	Description
XmlRpcScalarValueType	type	The XmlRpcScalarValueType to get the scalar type identifier for.

Returns

Type	Description
System.String	The scalar type identifier for the supplied type, otherwise returns an empty string.

Examples

ScalarTypeByName(String)

Returns the XmlRpcScalarValueType enumeration value that corresponds to the specified scalar type name.

Declaration

public static XmlRpcScalarValueType ScalarTypeByName(string name)

Parameters

Type	Name	Description
System.String	name	The name of the scalar type.

Returns

Type	Description
XmlRpcScalarValueType	A XmlRpcScalarValueType enumeration value that corresponds to the specified string, otherwise returns XmlRpcScalarValueType.None.

Remarks

This method disregards case of specified scalar type name.

Examples

Exceptions

Type	Condition
System.ArgumentNullException	The name is a null reference (Nothing in Visual Basic).
System.ArgumentNullException	The name is an empty string.

Send(XmlRpcMessage)

Sends the specified message to an XML-RPC server to execute a remote procedure call.

Declaration

public XmlRpcResponse Send(XmlRpcMessage message)

Parameters

Type	Name	Description
XmlRpcMessage	message	A XmlRpcMessage that represents the information needed to execute the remote procedure call.

Returns

Type	Description
XmlRpcResponse	A XmlRpcResponse that represents the server's response to the remote procedure call.

Exceptions

Type	Condition
System.ArgumentNullException	The message is a null reference (Nothing in Visual Basic).
System.InvalidOperationException	The Host is a null reference (Nothing in Visual Basic).
System.InvalidOperationException	This XmlRpcClient has a SendAsync(XmlRpcMessage, Object) call in progress.

SendAsync(XmlRpcMessage, Object)

Sends the specified message to an XML-RPC server to execute a remote procedure call. This method does not block the calling thread and allows the caller to pass an object to the method that is invoked when the operation completes.

Declaration

public void SendAsync(XmlRpcMessage message, object userToken)

Parameters

Type	Name	Description
XmlRpcMessage	message	A XmlRpcMessage that represents the information needed to execute the remote procedure call.
System.Object	userToken	A user-defined object that is passed to the method invoked when the asynchronous operation completes.

Remarks

To receive notification when the remote procedure call has been sent or the operation has been cancelled, add an event handler to the SendCompleted event. You can cancel a SendAsync(XmlRpcMessage, Object) operation by calling the SendAsyncCancel() method.

Exceptions

Type	Condition
System.ArgumentNullException	The message is a null reference (Nothing in Visual Basic).
System.InvalidOperationException	The Host is a null reference (Nothing in Visual Basic).
System.InvalidOperationException	This XmlRpcClient has a SendAsync(XmlRpcMessage, Object) call in progress.

SendAsyncCancel()

Cancels an asynchronous operation to send a remote procedure call.

Declaration

public void SendAsyncCancel()

Remarks

Use the SendAsyncCancel() method to cancel a pending SendAsync(XmlRpcMessage, Object) operation. If there is a remote procedure call waiting to be sent, this method releases resources used to execute the send operation and cancels the pending operation. If there is no send operation pending, this method does nothing.

TryParseValue(XPathNavigator, out IXmlRpcValue)

Constructs a new IXmlRpcValue object from the specified System.Xml.XPath.XPathNavigator. Parameters specify the XML data source and the variable where the new IXmlRpcValue object is returned.

Declaration

public static bool TryParseValue(XPathNavigator source, out IXmlRpcValue value)

Parameters

Type	Name	Description
System.Xml.XPath.XPathNavigator	source	A System.Xml.XPath.XPathNavigator that represents the XML data source to be parsed.
IXmlRpcValue	value	When this method returns, contains an object that represents the IXmlRpcValue specified by the source, or null if the conversion failed. This parameter is passed uninitialized.

Returns

Type	Description
System.Boolean	true if source was converted successfully; otherwise, false. This operation returns false if the source parameter is a null reference (Nothing in Visual Basic), or represents XML data that is not in the expected format.

Remarks

The source is expected to represent an XML-RPC value node.

Events

SendCompleted

Occurs when an asynchronous remote procedure call send operation completes.

Declaration

public event EventHandler<XmlRpcMessageSentEventArgs> SendCompleted

Event Type

Type	Description
System.EventHandler<XmlRpcMessageSentEventArgs>

See Also

SendAsync(XmlRpcMessage, Object)