== The Cocoa XML-RPC Framework

The  Cocoa  XML-RPC  Framework is a lightweight, simple, and easy-to-use XML-RPC
client  written  in Objective-C for use in OS X applications. An XML-RPC request
can  be  sent  asynchronously  or  synchronously over the wire, depending on the
intentions of its use.

== Requirements

The  Cocoa XML-RPC Framework will run on any recent version of OS X. Any version
prior  to  OS X 10.3 has not been tested, and probably will not work. A majority
of  the  framework relies heavily on two Foundation classes, NSURLConnection and
NSURLRequest.  These  two  classes  are  responsible  for  HTTP  transport, both
asynchronously and synchronously.
 
== Usage

= Asynchronous

- (void)sendRequest
{
	NSURL *URL = [NSURL URLWithString: @"http://www.foo.com/bar/"];
	XMLRPCRequest *request = [[[XMLRPCRequest alloc] initWithHost: URL]];
	
	[request setMethod: @"service.getFooBar" setObject: @"foo"];
	[request setUserAgent: @"myApplication"];
	
	XMLRPCConnection *connection = [[XMLRPCConnection alloc];
	
	initWithXMLRPCRequest: request delegate: self];
	
	if (connection == nil)
	{
		NSLog(@"Connection failed.");
	}
}

NOTE:  It is very important to understand that you are responsible for releasing
the  connection  and  response objects at the end of the connection response and
connection  failure  delegate  methods. Do not attempt to release the connection
object anywhere but within these two delegate methods.

- (void)connection: (XMLRPCConnection *)connection didReceiveResponse:
		(XMLRPCResponse *)response forMethod: (NSString *)method
{
	if (response != nil)
	{
		if ([response isFault])
		{
			NSLog(@"Fault: %@", [response fault]);
		}
		else
		{
			NSLog(@"Response object: %@", [response object]);
		}
		
		NSLog(@"Response source: %@", [response source]);
	}
	else
	{
		NSLog(@"Unable to parse response.");
	}
	
	[response autorelease];
	[connection autorelease];
}

- (void)connection: (XMLRPCConnection *)connection didFailWithError:
		(NSError *)response forMethod: (NSString *)method
{
	NSLog(@"An error occurred while making the HTTP request.");
	
	[connection release];
}

= Synchronous

- (void)sendRequest
{
	NSURL *URL = [NSURL URLWithString: @"http://www.foo.com/bar/"];
	XMLRPCRequest *request = [[[XMLRPCRequest alloc] initWithHost: URL]];
	
	[request setMethod: @"service.getFooBar" setObject: @"foo"];
	[request setUserAgent: @"myApplication"];
	
	XMLRPCResponse *response = [XMLRPCConnection
			sendSynchronousXMLRPCRequest: request];
	
	if (response != nil)
	{
		if ([response isFault])
		{
			NSLog(@"Fault: %@", [response fault]);
		}
		else
		{
			NSLog(@"Response object: %@", [response object]);
		}
		
		NSLog(@"Response source: %@", [response source]);
	}
	else
	{
		NSLog(@"Unable to parse response.");
	}
}

A response will always return nil upon creation if it is unable to parse the XML
data.  However,  in the case of a synchronous request, a nil response can either
mean  the  response  could  not  be parsed, or the connection failed to send the
request.

An  asynchronous connection will return nil if it fails to send the request. The
response   passed   to   the  connection:didReceiveResponse:forMethod:  delegate
method  will  be  nil if the response object is unable to parse the XML response
data.

Also  note  that you may have access to the raw XML source to either the request
and/or  response.  Though you may be able to extract the source from the request
at  any  moment  in the object's life, it is always best to get the source after
invoking the setMethod:withObjects: or setMethod:withObject: methods. If you ask
for  the  source  too  early,  you  wont  receive the fully created XML request
source.

== What if I find a bug?

The  Cocoa  XML-RPC  Framework has been developed on my free time. Any comments,
questions,  bug  reports and/or suggestions can be sent to eczarny@gmail.com. If
you find this framework useful I would appreciate receiving the necessary credit
where ever due.

== Acknowledgments

The  Base64  encoder/decoder found in NSStringAdditions and NSDataAdditions have
been  adapted  from  code  released  by Dave Winer and Brent Simmons. Dave Winer
wrote  the original Base64 encoding and decoding routines. Brent Simmons adapted
Dave Winer's code for use with Objective-C.

== License

Copyright (c) 2007 Eric Czarny.

The Cocoa XML-RPC Framework  should  be  accompanied  by  a  LICENSE  file, this
file  contains  the license relevant to this distribution. If no LICENSE exists,
please contact Eric Czarny <eczarny@gmail.com>.
