vendor/github.com/btcsuite/btcd/rpcclient/net.go

   1 // Copyright (c) 2014-2017 The btcsuite developers
   2 // Use of this source code is governed by an ISC
   3 // license that can be found in the LICENSE file.
   4
   5 package rpcclient
   6
   7 import (
   8         "encoding/json"
   9
  10         "github.com/btcsuite/btcd/btcjson"
  11 )
  12
  13 // AddNodeCommand enumerates the available commands that the AddNode function
  14 // accepts.
  15 type AddNodeCommand string
  16
  17 // Constants used to indicate the command for the AddNode function.
  18 const (
  19         // ANAdd indicates the specified host should be added as a persistent
  20         // peer.
  21         ANAdd AddNodeCommand = "add"
  22
  23         // ANRemove indicates the specified peer should be removed.
  24         ANRemove AddNodeCommand = "remove"
  25
  26         // ANOneTry indicates the specified host should try to connect once,
  27         // but it should not be made persistent.
  28         ANOneTry AddNodeCommand = "onetry"
  29 )
  30
  31 // String returns the AddNodeCommand in human-readable form.
  32 func (cmd AddNodeCommand) String() string {
  33         return string(cmd)
  34 }
  35
  36 // FutureAddNodeResult is a future promise to deliver the result of an
  37 // AddNodeAsync RPC invocation (or an applicable error).
  38 type FutureAddNodeResult chan *response
  39
  40 // Receive waits for the response promised by the future and returns an error if
  41 // any occurred when performing the specified command.
  42 func (r FutureAddNodeResult) Receive() error {
  43         _, err := receiveFuture(r)
  44         return err
  45 }
  46
  47 // AddNodeAsync returns an instance of a type that can be used to get the result
  48 // of the RPC at some future time by invoking the Receive function on the
  49 // returned instance.
  50 //
  51 // See AddNode for the blocking version and more details.
  52 func (c *Client) AddNodeAsync(host string, command AddNodeCommand) FutureAddNodeResult {
  53         cmd := btcjson.NewAddNodeCmd(host, btcjson.AddNodeSubCmd(command))
  54         return c.sendCmd(cmd)
  55 }
  56
  57 // AddNode attempts to perform the passed command on the passed persistent peer.
  58 // For example, it can be used to add or a remove a persistent peer, or to do
  59 // a one time connection to a peer.
  60 //
  61 // It may not be used to remove non-persistent peers.
  62 func (c *Client) AddNode(host string, command AddNodeCommand) error {
  63         return c.AddNodeAsync(host, command).Receive()
  64 }
  65
  66 // FutureGetAddedNodeInfoResult is a future promise to deliver the result of a
  67 // GetAddedNodeInfoAsync RPC invocation (or an applicable error).
  68 type FutureGetAddedNodeInfoResult chan *response
  69
  70 // Receive waits for the response promised by the future and returns information
  71 // about manually added (persistent) peers.
  72 func (r FutureGetAddedNodeInfoResult) Receive() ([]btcjson.GetAddedNodeInfoResult, error) {
  73         res, err := receiveFuture(r)
  74         if err != nil {
  75                 return nil, err
  76         }
  77
  78         // Unmarshal as an array of getaddednodeinfo result objects.
  79         var nodeInfo []btcjson.GetAddedNodeInfoResult
  80         err = json.Unmarshal(res, &nodeInfo)
  81         if err != nil {
  82                 return nil, err
  83         }
  84
  85         return nodeInfo, nil
  86 }
  87
  88 // GetAddedNodeInfoAsync returns an instance of a type that can be used to get
  89 // the result of the RPC at some future time by invoking the Receive function on
  90 // the returned instance.
  91 //
  92 // See GetAddedNodeInfo for the blocking version and more details.
  93 func (c *Client) GetAddedNodeInfoAsync(peer string) FutureGetAddedNodeInfoResult {
  94         cmd := btcjson.NewGetAddedNodeInfoCmd(true, &peer)
  95         return c.sendCmd(cmd)
  96 }
  97
  98 // GetAddedNodeInfo returns information about manually added (persistent) peers.
  99 //
 100 // See GetAddedNodeInfoNoDNS to retrieve only a list of the added (persistent)
 101 // peers.
 102 func (c *Client) GetAddedNodeInfo(peer string) ([]btcjson.GetAddedNodeInfoResult, error) {
 103         return c.GetAddedNodeInfoAsync(peer).Receive()
 104 }
 105
 106 // FutureGetAddedNodeInfoNoDNSResult is a future promise to deliver the result
 107 // of a GetAddedNodeInfoNoDNSAsync RPC invocation (or an applicable error).
 108 type FutureGetAddedNodeInfoNoDNSResult chan *response
 109
 110 // Receive waits for the response promised by the future and returns a list of
 111 // manually added (persistent) peers.
 112 func (r FutureGetAddedNodeInfoNoDNSResult) Receive() ([]string, error) {
 113         res, err := receiveFuture(r)
 114         if err != nil {
 115                 return nil, err
 116         }
 117
 118         // Unmarshal result as an array of strings.
 119         var nodes []string
 120         err = json.Unmarshal(res, &nodes)
 121         if err != nil {
 122                 return nil, err
 123         }
 124
 125         return nodes, nil
 126 }
 127
 128 // GetAddedNodeInfoNoDNSAsync returns an instance of a type that can be used to
 129 // get the result of the RPC at some future time by invoking the Receive
 130 // function on the returned instance.
 131 //
 132 // See GetAddedNodeInfoNoDNS for the blocking version and more details.
 133 func (c *Client) GetAddedNodeInfoNoDNSAsync(peer string) FutureGetAddedNodeInfoNoDNSResult {
 134         cmd := btcjson.NewGetAddedNodeInfoCmd(false, &peer)
 135         return c.sendCmd(cmd)
 136 }
 137
 138 // GetAddedNodeInfoNoDNS returns a list of manually added (persistent) peers.
 139 // This works by setting the dns flag to false in the underlying RPC.
 140 //
 141 // See GetAddedNodeInfo to obtain more information about each added (persistent)
 142 // peer.
 143 func (c *Client) GetAddedNodeInfoNoDNS(peer string) ([]string, error) {
 144         return c.GetAddedNodeInfoNoDNSAsync(peer).Receive()
 145 }
 146
 147 // FutureGetConnectionCountResult is a future promise to deliver the result
 148 // of a GetConnectionCountAsync RPC invocation (or an applicable error).
 149 type FutureGetConnectionCountResult chan *response
 150
 151 // Receive waits for the response promised by the future and returns the number
 152 // of active connections to other peers.
 153 func (r FutureGetConnectionCountResult) Receive() (int64, error) {
 154         res, err := receiveFuture(r)
 155         if err != nil {
 156                 return 0, err
 157         }
 158
 159         // Unmarshal result as an int64.
 160         var count int64
 161         err = json.Unmarshal(res, &count)
 162         if err != nil {
 163                 return 0, err
 164         }
 165
 166         return count, nil
 167 }
 168
 169 // GetConnectionCountAsync returns an instance of a type that can be used to get
 170 // the result of the RPC at some future time by invoking the Receive function on
 171 // the returned instance.
 172 //
 173 // See GetConnectionCount for the blocking version and more details.
 174 func (c *Client) GetConnectionCountAsync() FutureGetConnectionCountResult {
 175         cmd := btcjson.NewGetConnectionCountCmd()
 176         return c.sendCmd(cmd)
 177 }
 178
 179 // GetConnectionCount returns the number of active connections to other peers.
 180 func (c *Client) GetConnectionCount() (int64, error) {
 181         return c.GetConnectionCountAsync().Receive()
 182 }
 183
 184 // FuturePingResult is a future promise to deliver the result of a PingAsync RPC
 185 // invocation (or an applicable error).
 186 type FuturePingResult chan *response
 187
 188 // Receive waits for the response promised by the future and returns the result
 189 // of queueing a ping to be sent to each connected peer.
 190 func (r FuturePingResult) Receive() error {
 191         _, err := receiveFuture(r)
 192         return err
 193 }
 194
 195 // PingAsync returns an instance of a type that can be used to get the result of
 196 // the RPC at some future time by invoking the Receive function on the returned
 197 // instance.
 198 //
 199 // See Ping for the blocking version and more details.
 200 func (c *Client) PingAsync() FuturePingResult {
 201         cmd := btcjson.NewPingCmd()
 202         return c.sendCmd(cmd)
 203 }
 204
 205 // Ping queues a ping to be sent to each connected peer.
 206 //
 207 // Use the GetPeerInfo function and examine the PingTime and PingWait fields to
 208 // access the ping times.
 209 func (c *Client) Ping() error {
 210         return c.PingAsync().Receive()
 211 }
 212
 213 // FutureGetPeerInfoResult is a future promise to deliver the result of a
 214 // GetPeerInfoAsync RPC invocation (or an applicable error).
 215 type FutureGetPeerInfoResult chan *response
 216
 217 // Receive waits for the response promised by the future and returns  data about
 218 // each connected network peer.
 219 func (r FutureGetPeerInfoResult) Receive() ([]btcjson.GetPeerInfoResult, error) {
 220         res, err := receiveFuture(r)
 221         if err != nil {
 222                 return nil, err
 223         }
 224
 225         // Unmarshal result as an array of getpeerinfo result objects.
 226         var peerInfo []btcjson.GetPeerInfoResult
 227         err = json.Unmarshal(res, &peerInfo)
 228         if err != nil {
 229                 return nil, err
 230         }
 231
 232         return peerInfo, nil
 233 }
 234
 235 // GetPeerInfoAsync returns an instance of a type that can be used to get the
 236 // result of the RPC at some future time by invoking the Receive function on the
 237 // returned instance.
 238 //
 239 // See GetPeerInfo for the blocking version and more details.
 240 func (c *Client) GetPeerInfoAsync() FutureGetPeerInfoResult {
 241         cmd := btcjson.NewGetPeerInfoCmd()
 242         return c.sendCmd(cmd)
 243 }
 244
 245 // GetPeerInfo returns data about each connected network peer.
 246 func (c *Client) GetPeerInfo() ([]btcjson.GetPeerInfoResult, error) {
 247         return c.GetPeerInfoAsync().Receive()
 248 }
 249
 250 // FutureGetNetTotalsResult is a future promise to deliver the result of a
 251 // GetNetTotalsAsync RPC invocation (or an applicable error).
 252 type FutureGetNetTotalsResult chan *response
 253
 254 // Receive waits for the response promised by the future and returns network
 255 // traffic statistics.
 256 func (r FutureGetNetTotalsResult) Receive() (*btcjson.GetNetTotalsResult, error) {
 257         res, err := receiveFuture(r)
 258         if err != nil {
 259                 return nil, err
 260         }
 261
 262         // Unmarshal result as a getnettotals result object.
 263         var totals btcjson.GetNetTotalsResult
 264         err = json.Unmarshal(res, &totals)
 265         if err != nil {
 266                 return nil, err
 267         }
 268
 269         return &totals, nil
 270 }
 271
 272 // GetNetTotalsAsync returns an instance of a type that can be used to get the
 273 // result of the RPC at some future time by invoking the Receive function on the
 274 // returned instance.
 275 //
 276 // See GetNetTotals for the blocking version and more details.
 277 func (c *Client) GetNetTotalsAsync() FutureGetNetTotalsResult {
 278         cmd := btcjson.NewGetNetTotalsCmd()
 279         return c.sendCmd(cmd)
 280 }
 281
 282 // GetNetTotals returns network traffic statistics.
 283 func (c *Client) GetNetTotals() (*btcjson.GetNetTotalsResult, error) {
 284         return c.GetNetTotalsAsync().Receive()
 285 }