Add btcwallet websocket example.

Reviewed by @jrick who also provided some comment and terminology
improvements.

examples/btcwalletwebsockets/README.md

@@ -0,0 +1,38 @@
+btcwallet Websockets Example
+============================
+
+This example shows how to use the btcrpcclient package to connect to a btcwallet
+RPC server using TLS-secured websockets, register for notifications about
+changes to account balances, and get a list of unspent transaction outputs
+(utxos) the wallet can sign.
+
+This example also sets a timer to shutdown the client after 10 seconds to
+demonstrate clean shutdown.
+
+## Running the Example
+
+The first step is to use `go get` to download and install the btcrpcclient
+package:
+
+```bash
+$ go get github.com/conformal/btcrpcclient
+```
+
+Next, modify the `main.go` source to specify the correct RPC username and
+password for the RPC server:
+
+```Go
+	User: "yourrpcuser",
+	Pass: "yourrpcpass",
+```
+
+Finally, navigate to the example's directory and run it with:
+
+```bash
+$ cd $GOPATH/src/github.com/conformal/btcrpcclient/examples/btcwalletwebsockets
+$ go run *.go
+```
+
+## License
+
+This example is licensed under the [copyfree](http://copyfree.org) ISC License.

examples/btcwalletwebsockets/main.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2014 Conformal Systems LLC.
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"github.com/conformal/btcrpcclient"
+	"github.com/conformal/btcutil"
+	"github.com/davecgh/go-spew/spew"
+	"io/ioutil"
+	"log"
+	"path/filepath"
+	"time"
+)
+
+func main() {
+	// Only override the handlers for notifications you care about.
+	// Also note most of the handlers will only be called if you register
+	// for notifications.  See the documentation of the btcrpcclient
+	// NotificationHandlers type for more details about each handler.
+	ntfnHandlers := btcrpcclient.NotificationHandlers{
+		OnAccountBalance: func(account string, balance btcutil.Amount, confirmed bool) {
+			log.Printf("New balance for account %s: %v", account,
+				balance)
+		},
+	}
+
+	// Connect to local btcwallet RPC server using websockets.
+	certHomeDir := btcutil.AppDataDir("btcwallet", false)
+	certs, err := ioutil.ReadFile(filepath.Join(certHomeDir, "rpc.cert"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	connCfg := &btcrpcclient.ConnConfig{
+		Host:         "localhost:18332",
+		Endpoint:     "frontend",
+		User:         "yourrpcuser",
+		Pass:         "yourrpcpass",
+		Certificates: certs,
+	}
+	client, err := btcrpcclient.New(connCfg, &ntfnHandlers)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Get the list of unspent transaction outputs (utxos) that the
+	// connected wallet has at least one private key for.
+	unspent, err := client.ListUnspent()
+	if err != nil {
+		log.Fatal(err)
+	}
+	log.Printf("Num unspent outputs (utxos): %d", len(unspent))
+	if len(unspent) > 0 {
+		log.Printf("First utxo:\n%v", spew.Sdump(unspent[0]))
+	}
+
+	// For this example gracefully shutdown the client after 10 seconds.
+	// Ordinarily when to shutdown the client is highly application
+	// specific.
+	log.Println("Client shutdown in 10 seconds...")
+	time.AfterFunc(time.Second*10, func() {
+		log.Println("Client shutting down...")
+		client.Shutdown()
+		log.Println("Client shutdown complete.")
+	})
+
+	// Wait until the client either shuts down gracefully (or the user
+	// terminates the process with Ctrl+C).
+	client.WaitForShutdown()
+}