From 95f8e5d6d8c117c91fbd93dc0ffffe98c96fd274 Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Fri, 11 Apr 2014 10:45:20 -0500 Subject: [PATCH] Deprecate CreateMessage(WithId) and update docs. This commit marks the CreateMessage and CreateMessageWithId functions as deprecated as they are no longer maintained due to the new concrete command approach. It also updates the package documentation to show the new preferred method as well as add details about btcd. ok @jcvernaleo --- doc.go | 29 +++++++++++++++++------------ jsonapi.go | 8 ++++++++ 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/doc.go b/doc.go index 30fca096..c738ad13 100644 --- a/doc.go +++ b/doc.go @@ -14,7 +14,7 @@ https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list. This package provides data structures and code for marshalling and unmarshalling json for communicating with a running instance of btcd or bitcoind/bitcoin-qt. It also provides code for sending those -message. It does not provide any code for the client to actually deal +messages. It does not provide any code for the client to actually deal with the messages. Although it is meant primarily for btcd, it is possible to use this code elsewhere for interacting with a bitcoin client programatically. @@ -30,7 +30,7 @@ different method (or command) being sent. Replies will vary in form for the different commands. The basic form is: - {"result":SOMETHING,"error":null,"id":"btcd"} + {"result":SOMETHING,"error":null,"id":"SOMEID"} The result field can be as simple as an int, or a complex structure containing many nested fields. For cases where we have already worked @@ -51,8 +51,10 @@ RPC Server Authentication All RPC calls must be authenticated with a username and password. The specifics on how to configure the RPC server varies depending on the specific bitcoin implementation. For bitcoind, this is accomplished by setting rpcuser and -rpcpassword in the file ~/.bitcoin/bitcoin.conf. The default local address -of bitcoind is 127.0.0.1:8332. +rpcpassword in the file ~/.bitcoin/bitcoin.conf. For btcd, this is accomplished +by setting rpcuser and rpcpass in the file ~/.btcd/btcd.conf. The default local +address of bitcoind is 127.0.0.1:8332 and the default local address of btcd is +127.0.0.1:8334 Usage @@ -64,16 +66,18 @@ For commands where the reply structure is known, such as getinfo, one can directly access the fields in the Reply structure by type asserting the reply to the appropriate concrete type. - // Create a getinfo message. - msg, err := btcjson.CreateMessage("getinfo") + // Create a getinfo command. + id := 1 + cmd, err := btcjson.NewGetInfoCmd(id) if err != nil { // Log and handle error. } // Send the message to server using the appropriate username and // password. - reply, err := btcjson.RpcCommand(user, password, server, msg) + reply, err := btcjson.RpcSend(user, password, server, cmd) if err != nil { + fmt.Println(err) // Log and handle error. } @@ -88,22 +92,23 @@ For other commands where this package does not yet provide a concrete implementation for the reply, such as getrawmempool, the reply uses a generic interface so one can access individual items as follows: - // Create a getrawmempool message. - msg, err := btcjson.CreateMessage("getrawmempool") + // Create a getrawmempool command. + id := 1 + cmd, err := btcjson.NewGetRawMempoolCmd(id) if err != nil { // Log and handle error. } // Send the message to server using the appropriate username and // password. - reply, err := btcjson.RpcCommand(user, password, server, msg) + reply, err := btcjson.RpcSend(user, password, server, cmd) if err != nil { // Log and handle error. } - // Ensure there is a result and type assert it to an interface slice. + // Ensure there is a result and type assert it to a string slice. if reply.Result != nil { - if mempool, ok := reply.Result.([]interface{}); ok { + if mempool, ok := reply.Result.([]string); ok { fmt.Println("num mempool entries =", len(mempool)) } } diff --git a/jsonapi.go b/jsonapi.go index 9e0f5c99..1fbbc1f8 100644 --- a/jsonapi.go +++ b/jsonapi.go @@ -356,6 +356,10 @@ func jsonWithArgs(command string, id interface{}, args interface{}) ([]byte, err // It is capable of handeling all of the commands from the standard client, // described at: // https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list +// +// WARNING: This method is deprecated and may be removed in a future version. +// Do NOT use this as it does not work for all commands. Instead, use one of +// the NewCmd functions to create a specific command. func CreateMessage(message string, args ...interface{}) ([]byte, error) { finalMessage, err := CreateMessageWithId(message, "btcd", args...) return finalMessage, err @@ -366,6 +370,10 @@ func CreateMessage(message string, args ...interface{}) ([]byte, error) { // message ready to send off to the daemon or server. It is capable of handling // all of the commands from the standard client, described at: // https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list +// +// WARNING: This method is deprecated and may be removed in a future version. +// Do NOT use this as it does not work for all commands. Instead, use one of +// the NewCmd functions to create a specific command. func CreateMessageWithId(message string, id interface{}, args ...interface{}) ([]byte, error) { var finalMessage []byte var err error