README.md
1## Overview
2
3xmlrpc is an implementation of client side part of XMLRPC protocol in Go language.
4
5## Installation
6
7To install xmlrpc package run `go get github.com/kolo/xmlrpc`. To use
8it in application add `"github.com/kolo/xmlrpc"` string to `import`
9statement.
10
11## Usage
12
13 client, _ := xmlrpc.NewClient("https://bugzilla.mozilla.org/xmlrpc.cgi", nil)
14 result := struct{
15 Version string `xmlrpc:"version"`
16 }{}
17 client.Call("Bugzilla.version", nil, &result)
18 fmt.Printf("Version: %s\n", result.Version) // Version: 4.2.7+
19
20Second argument of NewClient function is an object that implements
21[http.RoundTripper](http://golang.org/pkg/net/http/#RoundTripper)
22interface, it can be used to get more control over connection options.
23By default it initialized by http.DefaultTransport object.
24
25### Arguments encoding
26
27xmlrpc package supports encoding of native Go data types to method
28arguments.
29
30Data types encoding rules:
31* int, int8, int16, int32, int64 encoded to int;
32* float32, float64 encoded to double;
33* bool encoded to boolean;
34* string encoded to string;
35* time.Time encoded to datetime.iso8601;
36* xmlrpc.Base64 encoded to base64;
37* slice decoded to array;
38
39Structs decoded to struct by following rules:
40* all public field become struct members;
41* field name become member name;
42* if field has xmlrpc tag, its value become member name.
43
44Server method can accept few arguments, to handle this case there is
45special approach to handle slice of empty interfaces (`[]interface{}`).
46Each value of such slice encoded as separate argument.
47
48### Result decoding
49
50Result of remote function is decoded to native Go data type.
51
52Data types decoding rules:
53* int, i4 decoded to int, int8, int16, int32, int64;
54* double decoded to float32, float64;
55* boolean decoded to bool;
56* string decoded to string;
57* array decoded to slice;
58* structs decoded following the rules described in previous section;
59* datetime.iso8601 decoded as time.Time data type;
60* base64 decoded to string.
61
62## Implementation details
63
64xmlrpc package contains clientCodec type, that implements [rpc.ClientCodec](http://golang.org/pkg/net/rpc/#ClientCodec)
65interface of [net/rpc](http://golang.org/pkg/net/rpc) package.
66
67xmlrpc package works over HTTP protocol, but some internal functions
68and data type were made public to make it easier to create another
69implementation of xmlrpc that works over another protocol. To encode
70request body there is EncodeMethodCall function. To decode server
71response Response data type can be used.
72
73## Contribution
74
75Feel free to fork the project, submit pull requests, ask questions.
76
77## Authors
78
79Dmitry Maksimov (dmtmax@gmail.com)
80