eczarny / xmlrpc

The Cocoa XML-RPC Framework is a lightweight XML-RPC client framework written in Objective-C for use on Mac OS X and iPhone OS.

This URL has Read+Write access

xmlrpc / README
raw normal view history
9ae54ee5 » eczarny 2008-10-10 Initial commit. 1 # The Cocoa XML-RPC Framework
2
3 The Cocoa XML-RPC Framework is a simple, and lightweight, XML-RPC client
4 framework written in Objective-C.
5
6 # Requirements
7
8 The Cocoa XML-RPC Framework has been built, and designed, for Mac OS X 10.4 or
9 later. This release should provide basic iPhone and iPod touch support.
10
11 This version of the Cocoa XML-RPC Framework includes a new event-based XML
12 parser. The previous tree-based XML parser still exists, but is no longer the
13 default XML-RPC response parser nor included in the Xcode build. This should
14 hopefully provide better compatibility with the iPhone SDK.
15
16 # Usage
17
18 The following example of the Cocoa XML-RPC Framework assumes that the included
19 XML-RPC test server is available. More information on the test server can be
20 found in the README under:
21
22 XMLRPC\Tools\test-server
23
24 Please review this document before moving forward.
25
26 ## Invoking XML-RPC requests through the XML-RPC connection manager
27
28 Invoking an XML-RPC request through the XML-RPC connection manager is easy:
29
30 NSURL *URL = [NSURL URLWithString: @"http://127.0.0.1:8080/"];
31 XMLRPCRequest *request = [[XMLRPCRequest alloc] initWithURL: URL];
32 XMLRPCConnectionManager *manager = [XMLRPCConnectionManager sharedManager];
33
34 [request setMethod: @"Echo.echo" withParameter: @"Hello World!"];
35
36 NSLog(@"Request body: %@", [request body]);
37
38 [manager spawnConnectionWithXMLRPCRequest: request delegate: self];
39
40 [request release];
41
42 This spawns a new XML-RPC connection, assigning that connection with a unique
43 identifer and returning it to the sender. This unique identifier, a UUID
44 expressed as an NSString, can then be used to obtain the XML-RPC connection from
45 the XML-RPC connection manager, as long as it is still active.
46
47 The XML-RPC connection manager has been designed to ease the management of
48 active XML-RPC connections. For example, the following method obtains an NSArray
49 of active XML-RPC connection identifiers:
50
51 - (NSArray *)activeConnectionIdentifiers;
52
53 The NSArray returned by this method contains a list of each active connection
54 identifier. Provided with a connection identifier, the following method will
55 return an instance of the requested XML-RPC connection:
56
57 - (XMLRPCConnection *)connectionForIdentifier: (NSString *)connectionIdentifier;
58
59 Finally, for a delegate to receive XML-RPC responses, authentication challenges,
60 or errors, the XMLRPCConnectionDelegate protocol must be implemented. For
61 example, the following will handle successful XML-RPC responses:
62
63 - (void)request: (XMLRPCRequest *)request didReceiveResponse: (XMLRPCResponse *)response {
64 if ([response isFault]) {
65 NSLog(@"Fault code: %@", [response faultCode]);
66
67 NSLog(@"Fault string: %@", [response faultString]);
68 } else {
69 NSLog(@"Parsed response: %@", [response object]);
70 }
71
72 NSLog(@"Response body: %@", [response body]);
73 }
74
75 Refer to XMLRPCConnectionDelegate.h for a full list of methods a delegate must
76 implement. Each of these delegate methods plays a role in the life of an active
77 XML-RPC connection.
78
79 # What if I find a bug, or what if I want to help?
80
81 Please, contact me with any questions, comments, suggestions, or problems. I try
82 to make the time to answer every request. If you find a bug, it would be
83 helpful to also provide steps to reproduce the problem.
84
85 Those wishing to contribute to the project should begin by obtaining the
86 latest source with Git:
87
88 $ git clone git://github.com/eczarny/xmlrpc.git XMLRPC
89
90 Now that you have a copy of the project, create a new local branch:
91
ad796b5d » eczarny 2008-12-17 Minor documentation update. 92 $ git checkout -b my-bug-fix
9ae54ee5 » eczarny 2008-10-10 Initial commit. 93
ad796b5d » eczarny 2008-12-17 Minor documentation update. 94 This new branch, my-bug-fix, is where all of your changes should go.
9ae54ee5 » eczarny 2008-10-10 Initial commit. 95
96 There is always the possibility that new changes will be pushed to the remote
ad796b5d » eczarny 2008-12-17 Minor documentation update. 97 repository while you make your changes in the my-bug-fix branch. The best way to
9ae54ee5 » eczarny 2008-10-10 Initial commit. 98 keep up-to-date with these changes is to pull them from the remote repository
ad796b5d » eczarny 2008-12-17 Minor documentation update. 99 and use them as the new base for the my-bug-fix branch:
9ae54ee5 » eczarny 2008-10-10 Initial commit. 100
101 $ git checkout master
102 $ git pull
ad796b5d » eczarny 2008-12-17 Minor documentation update. 103 $ git rebase master my-bug-fix
9ae54ee5 » eczarny 2008-10-10 Initial commit. 104
105 The changes from the remote repository are pulled into your local master branch,
106 providing you with the most recent base to apply your changes. The changes from
ad796b5d » eczarny 2008-12-17 Minor documentation update. 107 your my-bug-fix branch will then use the most recent changes you pulled from the
9ae54ee5 » eczarny 2008-10-10 Initial commit. 108 remote repository as their base.
109
110 Finally, create the patch that you plan on submitting:
111
ad796b5d » eczarny 2008-12-17 Minor documentation update. 112 $ git format-patch master --stdout > my-bug-fix.diff
9ae54ee5 » eczarny 2008-10-10 Initial commit. 113
ad796b5d » eczarny 2008-12-17 Minor documentation update. 114 This patch, my-bug-fix.diff, now contains all of your changes. Please, be sure
9ae54ee5 » eczarny 2008-10-10 Initial commit. 115 to provide your patch with a detailed description of your changes.
116
117 # Acknowledgments
118
119 The Base64 encoder/decoder found in NSStringAdditions and NSDataAdditions have
120 been adapted from code provided by Dave Winer.
121
122 The idea for this framework came from examples provided by Brent Simmons, the
123 creator of NetNewsWire.
124
125 # License
126
127 Copyright (c) 2008 Eric Czarny.
128
129 The Cocoa XML-RPC Framework should be accompanied by a LICENSE file, this
130 file contains the license relevant to this distribution. If no LICENSE exists
131 please contact Eric Czarny <eczarny@gmail.com>.