cpp-ipfs-http-client
IPFS C++ client library
Public Types | Public Member Functions | List of all members
ipfs::Client Class Reference

IPFS client. More...

#include <ipfs/client.h>

Public Types

enum  PinRmOptions { PinRmOptions::NON_RECURSIVE, PinRmOptions::RECURSIVE }
 Options to control the PinRm() method. More...
 

Public Member Functions

 Client (const std::string &host, long port)
 Constructor. More...
 
 Client (const Client &)
 Copy-constructor. More...
 
 Client (Client &&)
 Move-constructor. More...
 
Clientoperator= (const Client &)
 Copy assignment operator. More...
 
Clientoperator= (Client &&)
 Move assignment operator. More...
 
 ~Client ()
 Destructor. More...
 
void Id (Json *id)
 Return the identity of the peer. More...
 
void Version (Json *version)
 Return the implementation version of the peer. More...
 
void ConfigGet (const std::string &key, Json *config)
 Query the current config of the peer. More...
 
void ConfigSet (const std::string &key, const Json &value)
 Add or replace a config knob at the peer. More...
 
void ConfigReplace (const Json &config)
 Replace the entire config at the peer. More...
 
void DhtFindPeer (const std::string &peer_id, Json *addresses)
 Retrieve the peer info of a reachable node in the network. More...
 
void DhtFindProvs (const std::string &hash, Json *providers)
 Retrieve the providers for a content that is addressed by a hash. More...
 
void BlockGet (const std::string &block_id, std::iostream *block)
 Get a raw IPFS block. More...
 
void BlockPut (const http::FileUpload &block, Json *stat)
 Store a raw block in IPFS. More...
 
void BlockStat (const std::string &block_id, Json *stat)
 Get information for a raw IPFS block. More...
 
void FilesGet (const std::string &path, std::iostream *response)
 Get a file from IPFS. More...
 
void FilesAdd (const std::vector< http::FileUpload > &files, Json *result)
 Add files to IPFS. More...
 
void FilesLs (const std::string &path, Json *result)
 List directory contents for Unix filesystem objects. More...
 
void KeyGen (const std::string &key_name, const std::string &key_type, size_t key_size, std::string *key_id)
 Generate a new key. More...
 
void KeyList (Json *key_list)
 List all the keys. More...
 
void KeyRm (const std::string &key_name)
 Remove a key. More...
 
void NamePublish (const std::string &object_id, const std::string &key_name, const Json &options, std::string *name_id)
 Publish an IPNS name attached to a given value. More...
 
void NameResolve (const std::string &name_id, std::string *path_string)
 Resolve an IPNS name. More...
 
void ObjectNew (std::string *object_id)
 Create a new MerkleDAG node. More...
 
void ObjectPut (const Json &object, Json *object_stored)
 Store a MerkleDAG node. More...
 
void ObjectGet (const std::string &object_id, Json *object)
 Get a MerkleDAG node. More...
 
void ObjectData (const std::string &object_id, std::string *data)
 Get the data field of a MerkleDAG node. More...
 
void ObjectLinks (const std::string &object_id, Json *links)
 Get links of a MerkleDAG node. More...
 
void ObjectStat (const std::string &object_id, Json *stat)
 Get stats about a MerkleDAG node. More...
 
void ObjectPatchAddLink (const std::string &source, const std::string &link_name, const std::string &link_target, std::string *cloned)
 Create a new object from an existing MerkleDAG node and add to its links. More...
 
void ObjectPatchRmLink (const std::string &source, const std::string &link_name, std::string *cloned)
 Create a new object from an existing MerkleDAG node and remove one of its links. More...
 
void ObjectPatchAppendData (const std::string &source, const http::FileUpload &data, std::string *cloned)
 Create a new object from an existing MerkleDAG node and append data to it. More...
 
void ObjectPatchSetData (const std::string &source, const http::FileUpload &data, std::string *cloned)
 Create a new object from an existing MerkleDAG node and set its data. More...
 
void PinAdd (const std::string &object_id)
 Pin a given IPFS object. More...
 
void PinLs (Json *pinned)
 List all the objects pinned to local storage. More...
 
void PinLs (const std::string &object_id, Json *pinned)
 List the objects pinned under a specific hash. More...
 
void PinRm (const std::string &object_id, PinRmOptions options)
 Unpin an object. More...
 
void SwarmAddrs (Json *addresses)
 List of known addresses of each peer connected. More...
 
void SwarmConnect (const std::string &peer)
 Open a connection to a given address. More...
 
void SwarmDisconnect (const std::string &peer)
 Close a connection on a given address. More...
 
void SwarmPeers (Json *peers)
 List the peers that we have connections with. More...
 

Detailed Description

IPFS client.

It implements the interface described in https://github.com/ipfs/interface-ipfs-core. The methods of this class may throw some variant of std::exception if a connectivity error occurs or if the response cannot be parsed. Be prepared!

Since
version 0.1.0

Member Enumeration Documentation

◆ PinRmOptions

Options to control the PinRm() method.

Enumerator
NON_RECURSIVE 

Just unpin the specified object.

RECURSIVE 

Recursively unpin the objects.

Constructor & Destructor Documentation

◆ Client() [1/3]

ipfs::Client::Client ( const std::string &  host,
long  port 
)

Constructor.

An example usage:

ipfs::Client client("localhost", 5001);
Since
version 0.1.0
Parameters
[in]hostHostname or IP address of the server to connect to.
[in]portPort to connect to.

◆ Client() [2/3]

ipfs::Client::Client ( const Client other)

Copy-constructor.

Parameters
[in]otherOther client connection to be copied.

◆ Client() [3/3]

ipfs::Client::Client ( Client &&  other)

Move-constructor.

Parameters
[in,out]otherOther client connection to be moved.

◆ ~Client()

ipfs::Client::~Client ( )

Destructor.

Since
version 0.1.0

Member Function Documentation

◆ BlockGet()

void ipfs::Client::BlockGet ( const std::string &  block_id,
std::iostream *  block 
)

Get a raw IPFS block.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BLOCK.md#blockget.

An example usage:

std::stringstream block_contents;
/* E.g. block["Key"] is "QmQpWo5TL9nivqvL18Bq8bS34eewAA6jcgdVsUu4tGeVHo". */
client.BlockGet(block["Key"], &block_contents);
std::cout << "Block (hex): "
<< ipfs::test::string_to_hex(block_contents.str()) << std::endl;
/* An example output:
Block (hex): 426c6f636b2070757420746573742e
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]block_idId of the block (multihash).
[out]blockRaw contents of the block is written to this stream as it is retrieved.

◆ BlockPut()

void ipfs::Client::BlockPut ( const http::FileUpload block,
Json stat 
)

Store a raw block in IPFS.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BLOCK.md#blockput.

An example usage:

ipfs::Json block;
client.BlockPut(
"Block put test."},
&block);
std::cout << "Stored block key: " << block["Key"] << std::endl;
/* An example output:
Stored block key: "QmQpWo5TL9nivqvL18Bq8bS34eewAA6jcgdVsUu4tGeVHo"
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]blockRaw contents of the block to store.
[out]statInformation about the stored block.

◆ BlockStat()

void ipfs::Client::BlockStat ( const std::string &  block_id,
Json stat 
)

Get information for a raw IPFS block.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BLOCK.md#blockstat.

An example usage:

ipfs::Json stat_result;
client.BlockStat(block["Key"], &stat_result);
std::cout << "Stat: " << stat_result << std::endl;
/* An example output:
Stat: {"Key":"QmQpWo5TL9nivqvL18Bq8bS34eewAA6jcgdVsUu4tGeVHo","Size":15}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]block_idId of the block (multihash).
[out]statRetrieved information about the block.

◆ ConfigGet()

void ipfs::Client::ConfigGet ( const std::string &  key,
Json config 
)

Query the current config of the peer.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/CONFIG.md#configget.

An example usage:

ipfs::Json config;
client.ConfigGet("Datastore", &config);
std::cout << R"(Config "Datastore":)" << std::endl
<< config.dump(2) << std::endl;
/* An example output:
Config "Datastore":
{
"BloomFilterSize": 0,
"GCPeriod": "1h",
"HashOnRead": false,
"NoSync": false,
"Params": null,
"Path": "/home/vd/.ipfs/datastore",
"StorageGCWatermark": 90,
"StorageMax": "10GB",
"Type": "leveldb"
}
*/
client.ConfigGet("" /* fetch the entire config */, &config);
std::cout << "Config max storage: " << config["Datastore"]["StorageMax"]
<< std::endl;
/* An example output:
Config max storage: "10GB"
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]keyThe key of the value to fetch from the config. If this is an empty string, then the whole config is fetched.
[out]configFetched config.

◆ ConfigReplace()

void ipfs::Client::ConfigReplace ( const Json config)

Replace the entire config at the peer.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/CONFIG.md#configreplace.

An example usage:

ipfs::Json entire_config;
client.ConfigGet("" /* fetch the entire config */, &entire_config);
client.ConfigReplace(entire_config);
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]configThe entire config to set/replace.

◆ ConfigSet()

void ipfs::Client::ConfigSet ( const std::string &  key,
const Json value 
)

Add or replace a config knob at the peer.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/CONFIG.md#configset.

An example usage:

client.ConfigSet("Datastore.StorageMax", "20GB");
client.ConfigSet("Datastore.StorageGCWatermark", 80);
client.ConfigSet("Mounts",
R"({
"FuseAllowOther": false,
"IPFS": "/ipfs",
"IPNS": "/ipns"
})"_json);
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]keyThe key of the config knob to set.
[in]valueThe value to set for the key.

◆ DhtFindPeer()

void ipfs::Client::DhtFindPeer ( const std::string &  peer_id,
Json addresses 
)

Retrieve the peer info of a reachable node in the network.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DHT.md#dhtfindpeer.

An example usage:

/* std::string peer_id = "QmcZrBqWBYV3RGsPuhQX11Qzp...maDYF" for example. */
ipfs::Json peer_addresses;
client.DhtFindPeer(peer_id, &peer_addresses);
std::cout << "Peer " << peer_id << " info:" << std::endl
<< peer_addresses.dump(2) << std::endl;
/* An example output:
Peer QmcZrBqWBYV3RGsPuhQX11QzpKAQ8SYfMYL1dGXuPmaDYF info:
[
"/ip6/::1/tcp/4001",
"/ip4/212.227.249.191/tcp/4001",
"/ip4/127.0.0.1/tcp/4001"
]
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]peer_idId of the peer (multihash).
[out]addressesList of the peer's addresses.

◆ DhtFindProvs()

void ipfs::Client::DhtFindProvs ( const std::string &  hash,
Json providers 
)

Retrieve the providers for a content that is addressed by a hash.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DHT.md#dhtfindprovs.

An example usage:

/* std::string hash = "QmWPyMW2u7J2Zyzut7TcBMT8pG6F...Bt1nP" for example. */
ipfs::Json providers;
client.DhtFindProvs(hash, &providers);
std::cout << "Providers for " << hash << ":" << std::endl
<< providers.dump(2).substr(0, 512) << "..." << std::endl;
/* An example output:
[
{
"Extra": "",
"ID": "",
"Responses": [
{
"Addrs": null,
"ID": "QmZSb7SYajaEEbJU2FB4XJWWfxX9AjwmdreK5MDu9zuQvn"
}
],
"Type": 4
},
{
"Extra": "",
"ID": "QmYoQjsZeSyzeeX9yCu5jfETgKinR2Udeej385FzPprsGg",
"Responses": null,
"Type": 6
},
{
"Extra": "",
"ID": "QmdsoQ8xhfkaEpAYCLJ75LEiup9E4ybUdbqDkZZKggfWjS",
"Responses": null,
"Type": 6
},...
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]hashMultihash whose providers to find.
[out]providersList of providers of hash.

◆ FilesAdd()

void ipfs::Client::FilesAdd ( const std::vector< http::FileUpload > &  files,
Json result 
)

Add files to IPFS.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/FILES.md#add.

An example usage:

ipfs::Json add_result;
client.FilesAdd(
"../compile_commands.json"}},
&add_result);
std::cout << "FilesAdd() result:" << std::endl
<< add_result.dump(2) << std::endl;
/* An example output:
[
{
"path": "foo.txt",
"hash": "QmWPyMW2u7J2Zyzut7TcBMT8pG6F2cB4hmZk1vBJFBt1nP",
"size": 4
}
{
"path": "bar.txt",
"hash": "QmVjQsMgtRsRKpNM8amTCDRuUPriY8tGswsTpo137jPWwL",
"size": 1176
},
]
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]filesList of files to add.
[out]resultList of results, one per file. For example: [{"path": "foo.txt", "hash": "Qm...", "size": 123}, {"path": ...}, ...]

◆ FilesGet()

void ipfs::Client::FilesGet ( const std::string &  path,
std::iostream *  response 
)

Get a file from IPFS.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/FILES.md#get.

An example usage:

std::stringstream contents;
client.FilesGet(
"/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme",
&contents);
std::cout << "Retrieved contents: " << contents.str().substr(0, 8) << "..."
<< std::endl;
/* An example output:
Retrieved contents: Hello an...
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]pathPath of the file in IPFS. For example: "/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme"
[out]responseThe file's contents is written to this stream as it is retrieved from IPFS.

◆ FilesLs()

void ipfs::Client::FilesLs ( const std::string &  path,
Json result 
)

List directory contents for Unix filesystem objects.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#ls.

An example usage:

ipfs::Json ls_result;
client.FilesLs("/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
&ls_result);
std::cout << "FilesLs() result:" << std::endl
<< ls_result.dump(2) << std::endl;
/* An example output:
{
"Arguments": {
"/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG":
"QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"
},
"Objects": {
"QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG": {
"Hash": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
"Links": [
{
"Hash": "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V",
"Name": "about",
"Size": 1677,
"Type": "File"
},
...
{
"Hash": "QmdncfsVm2h5Kqq9hPmU7oAVX2zTSVP3L869tgTbPYnsha",
"Name": "quick-start",
"Size": 1717,
"Type": "File"
},
...
],
"Size": 0,
"Type": "Directory"
}
}
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.2.0
Parameters
[in]pathThe path to an IPFS object.
[out]resultList of results (files). For example: { "Arguments": { ... }, "Objects": { "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG": { "Hash": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG", "Links": [ { "Hash": "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgf...", "Name": "about", "Size": 1677, "Type": "File" }, ... { "Hash": "QmdncfsVm2h5Kqq9hPmU7oAVX2zTSVP...", "Name": "quick-start", "Size": 1717, "Type": "File" }, ... ], "Size": 0, "Type": "Directory" } } }

◆ Id()

void ipfs::Client::Id ( Json id)

Return the identity of the peer.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/MISCELLANEOUS.md#id.

An example usage:

client.Id(&id);
std::cout << "Peer's public key: " << id["PublicKey"] << std::endl;
/* An example output:
Peer's public key: "CAASpgIwggEiMA0GCSqGSIb3DQN/ImJDE/CN1eHE....gMBAAE="
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]idThe identity of the peer. It contains at least the properties "Addresses", "ID", "PublicKey".

◆ KeyGen()

void ipfs::Client::KeyGen ( const std::string &  key_name,
const std::string &  key_type,
size_t  key_size,
std::string *  key_id 
)

Generate a new key.

Implements https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/KEY.md#keygen.

An example usage:

std::string key_id;
client.KeyGen("foobar-key", "rsa", 2048, &key_id);
std::cout << "Generated key: " << key_id << std::endl;
/* An example output:
Generated key: "QmQeVW8BKqpHbUV5GcecC3wDLF3iqV6ZJhtFN8q8mUYFUs"
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.3.0
Parameters
[in]key_nameKey name (local, user-friendly name for the key).
[in]key_typeKey type.
[in]key_sizeKey size.
[out]key_idKey CID.

◆ KeyList()

void ipfs::Client::KeyList ( Json key_list)

List all the keys.

Implements https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/KEY.md#keylist.

An example usage:

Json key_list;
client.KeyList(&key_list);
std::cout << "A list of all local keys: " << key_list.dump(2) << std::endl;
/* An example output:
A list of all local keys: [
{
"Id": "QmQ9KnoHP3iRwXLSrdDb8wdJCbEdjk7hVFYGUGDUsdC41k",
"Name": "self"
},
{
"Id": "QmNjm428tzU5P2ik1yDJNZP2F5zG2jb8fHXZ5D2mzvJGLg",
"Name": "foobar-key"
}
]
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.3.0
Parameters
[out]key_listList of all local keys.

◆ KeyRm()

void ipfs::Client::KeyRm ( const std::string &  key_name)

Remove a key.

Implements https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/KEY.md#keyrm.

An example usage:

/* Successful, if no error is thrown. */
client.KeyRm("foobar-key");
Exceptions
std::exceptionif any error occurs
Since
version 0.3.0
Parameters
[in]key_nameKey name (local, user-friendly name for the key).

◆ NamePublish()

void ipfs::Client::NamePublish ( const std::string &  object_id,
const std::string &  key_name,
const Json options,
std::string *  name_id 
)

Publish an IPNS name attached to a given value.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/NAME.md#namepublish.

An example usage:

// The object here is well-known.
std::string object_id = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";
std::string name;
ipfs::Json options = {{"lifetime", "4h"}, {"ttl", "60s"}};
client.NamePublish(object_id, "foobar-key", options, &name);
/* An example output: "QmbJ5UzreC86qtHrWC2SwWKLsTiLqTuG4cqHHJVdYPK6s9" */
std::cout << "Published name: " << name << std::endl;
Exceptions
std::exceptionif any error occurs
Since
version 0.4.0
Parameters
[in]object_idId (multihash) of the object to publish.
[in]key_nameName of the key to use. This is the local, human-friendly keyname
[in]optionsOptional JSON parameter providing options. If specified, these will be used to determine how the name is published: { resolve: // bool - Resolve given path before publishing. // Default: true lifetime: // string - Lifetime duration of the record. // Default: 24h ttl: // string - Duration in client's cache. }
[out]name_idIPNS name id (multihash) of the named object.

◆ NameResolve()

void ipfs::Client::NameResolve ( const std::string &  name_id,
std::string *  path_string 
)

Resolve an IPNS name.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/NAME.md#nameresolve.

An example usage:

// std::string name = "QmTN15ibVzXhNBUZvv4rjHtrsM1xvHe19iy8feGFbUxb3P";
std::string resolved_object_path;
client.NameResolve(name, &resolved_object_path);
/* The expected output:
* "/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"; */
std::cout << "Resolved name: " << resolved_object_path << std::endl;
Exceptions
std::exceptionif any error occurs
Since
version 0.4.0
Parameters
[in]name_idId (multihash) of the name to resolve.
[out]path_stringIPFS path string to the resolving object. For example: "/ipfs/QmRrVRGx5xAXX52BYuScmJk1KWPny86BtexP8YNJ8jz76U"

◆ ObjectData()

void ipfs::Client::ObjectData ( const std::string &  object_id,
std::string *  data 
)

Get the data field of a MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectdata.

An example usage:

std::string data;
client.ObjectData("QmZZmY4KCu9r3e7M2Pcn46Fc5qbn6NpzaAGaYb22kbfTqm", &data);
std::cout << "Object data: " << data << std::endl;
/* An example output:
Object data: another
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId (multihash) of the MerkleDAG node whose data to fetch.
[out]dataRaw data of the MerkleDAG node.

◆ ObjectGet()

void ipfs::Client::ObjectGet ( const std::string &  object_id,
Json object 
)

Get a MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectget.

An example usage:

ipfs::Json object;
client.ObjectGet("QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n", &object);
std::cout << "Object: " << std::endl << object.dump(2) << std::endl;
/* An example output:
Object:
{
"Data": "another",
"Links": [ {
"Name": "some link",
"Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V",
"Size": 8
} ]
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId (multihash) of the MerkleDAG node to fetch.
[out]objectRetrieved MerkleDAG node. For example: {"Data": "abc", "Links": [{"Name": "link1", "Hash": "...", "Size": 8}]}

◆ ObjectLinks()

void ipfs::Client::ObjectLinks ( const std::string &  object_id,
Json links 
)

Get links of a MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectlinks.

An example usage:

ipfs::Json links;
client.ObjectLinks("QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
&links);
std::cout << "Object links:" << std::endl << links.dump(2) << std::endl;
/* An example output:
[
{
"Hash": "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V",
"Name": "about",
"Size": 1688
},
{
"Hash": "QmYCvbfNbCwFR45HiNP45rwJgvatpiW38D961L5qAhUM5Y",
"Name": "contact",
"Size": 200
},
{
"Hash": "QmY5heUM5qgRubMDD1og9fhCPA6QdkMp3QCwd4s7gJsyE7",
"Name": "help",
"Size": 322
},
{
"Hash": "QmdncfsVm2h5Kqq9hPmU7oAVX2zTSVP3L869tgTbPYnsha",
"Name": "quick-start",
"Size": 1728
},
{
"Hash": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB",
"Name": "readme",
"Size": 1102
},
{
"Hash": "QmTumTjvcYCAvRRwQ8sDRxh8ezmrcr88YFU7iYNroGGTBZ",
"Name": "security-notes",
"Size": 1027
}
]
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId of the object to query (multihash).
[out]linksLinks of the object. For example: [{"Name": "...", "Hash": "...", "Size": 8}, ...]

◆ ObjectNew()

void ipfs::Client::ObjectNew ( std::string *  object_id)

Create a new MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectnew.

An example usage:

std::string object_id;
client.ObjectNew(&object_id);
std::cout << "New object id: " << object_id << std::endl;
/* An example output:
New object id: QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]object_idId of the newly created object (multihash).

◆ ObjectPatchAddLink()

void ipfs::Client::ObjectPatchAddLink ( const std::string &  source,
const std::string &  link_name,
const std::string &  link_target,
std::string *  cloned 
)

Create a new object from an existing MerkleDAG node and add to its links.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectpatchaddlink.

An example usage:

/* Create a new node, upload two files and link them to the node. */
std::string orig_id;
client.ObjectNew(&orig_id);
ipfs::Json added_files;
client.FilesAdd(
&added_files);
std::string new_id;
client.ObjectPatchAddLink(orig_id, "link to file1.txt",
added_files[0]["hash"], &new_id);
ipfs::Json new_object;
client.ObjectGet(new_id, &new_object);
std::cout << "Added a link to " << orig_id << "." << std::endl
<< "New object " << new_id << ":" << std::endl
<< new_object.dump(2) << std::endl;
/* An example output:
Added a link to QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n.
New object QmRgn5ZeLiPRwQHqSbMLUZ2gkyLbJiaxVEx3LrDCqqaCAb:
{
"Data": "",
"Links": [
{
"Hash": "QmNYaS23te5Rja36U94JoSTuMxJZmBEnHN8KEcjR6rGRGn",
"Name": "link to file1.txt",
"Size": 12
}
]
}
*/
orig_id = new_id;
client.ObjectPatchAddLink(orig_id, "link to file2.txt",
added_files[1]["hash"], &new_id);
client.ObjectGet(new_id, &new_object);
std::cout << "Added another link to " << orig_id << "." << std::endl
<< "New object " << new_id << ":" << std::endl
<< new_object.dump(2) << std::endl;
/* An example output:
Added another link to QmRgn5ZeLiPRwQHqSbMLUZ2gkyLbJiaxVEx3LrDCqqaCAb.
New object QmTxf3cBwrzyRvCZgDQni5wkRkcpM81wiWFTK17okLtT21:
{
"Data": "",
"Links": [
{
"Hash": "QmNYaS23te5Rja36U94JoSTuMxJZmBEnHN8KEcjR6rGRGn",
"Name": "link to file1.txt",
"Size": 12
},
{
"Hash": "QmYuNVU4vwpXqX9RLv47HbmiveWwZvLBsXyYbUtEQMJYGQ",
"Name": "link to file2.txt",
"Size": 12
}
]
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]sourceId of the object to clone (multihash).
[in]link_nameLink name.
[in]link_targetId of the object that the link points to (multihash).
[out]clonedId of the newly created (cloned) object (multihash).

◆ ObjectPatchAppendData()

void ipfs::Client::ObjectPatchAppendData ( const std::string &  source,
const http::FileUpload data,
std::string *  cloned 
)

Create a new object from an existing MerkleDAG node and append data to it.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectpatchappenddata.

An example usage:

/* std::string target_id = "QmTxf3cBwrzyRvCZgDQni...LtT21" for example. */
std::string with_appended_data_id;
client.ObjectPatchAppendData(
target_id,
&with_appended_data_id);
ipfs::Json with_appended_data;
client.ObjectGet(with_appended_data_id, &with_appended_data);
std::cout << "Appended data to " << target_id << "." << std::endl
<< "New object " << with_appended_data_id << ":" << std::endl
<< with_appended_data.dump(2) << std::endl;
/* An example output:
Appended data to QmTxf3cBwrzyRvCZgDQni5wkRkcpM81wiWFTK17okLtT21.
New object QmbDtmUVyiN8vFZr8cDTpuVtZwnVd3k6wqpEq3NvE67bTj:
{
"Data": "appended data",
"Links": [
{
"Hash": "QmNYaS23te5Rja36U94JoSTuMxJZmBEnHN8KEcjR6rGRGn",
"Name": "link to file1.txt",
"Size": 12
},
{
"Hash": "QmYuNVU4vwpXqX9RLv47HbmiveWwZvLBsXyYbUtEQMJYGQ",
"Name": "link to file2.txt",
"Size": 12
}
]
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]sourceId of the object to append data to (multihash).
[in]dataData to be appended.
[out]clonedId of the newly created (cloned) object (multihash).

◆ ObjectPatchRmLink()

void ipfs::Client::ObjectPatchRmLink ( const std::string &  source,
const std::string &  link_name,
std::string *  cloned 
)

Create a new object from an existing MerkleDAG node and remove one of its links.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectpatchrmlink.

An example usage:

/* std::string target_id = "QmTxf3cBwrzyRvCZgDQni...LtT21" for example. */
std::string without_link_id;
client.ObjectPatchRmLink(target_id, "link to file1.txt",
&without_link_id);
ipfs::Json without_link;
client.ObjectGet(without_link_id, &without_link);
std::cout << "Removed a link from " << target_id << "." << std::endl
<< "New object " << without_link_id << ":" << std::endl
<< without_link.dump(2) << std::endl;
/* An example output:
Removed a link from QmTxf3cBwrzyRvCZgDQni5wkRkcpM81wiWFTK17okLtT21.
New object QmVUXX6chMMT4cPosYsLq64FZ21ie94KPknSnWfG8YDJBB:
{
"Data": "",
"Links": [
{
"Hash": "QmYuNVU4vwpXqX9RLv47HbmiveWwZvLBsXyYbUtEQMJYGQ",
"Name": "link to file2.txt",
"Size": 12
}
]
}
*/
bool removal_ok;
try {
client.ObjectPatchRmLink(target_id, "nonexistent", &without_link_id);
removal_ok = true;
} catch (const std::exception&) {
removal_ok = false;
}
if (removal_ok) {
throw std::runtime_error(
"Removal of nonexistent link succeeded but should have failed.");
}
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]sourceId of the object to remove the link from (multihash).
[in]link_nameName of the link to remove.
[out]clonedId of the newly created (cloned) object (multihash).

◆ ObjectPatchSetData()

void ipfs::Client::ObjectPatchSetData ( const std::string &  source,
const http::FileUpload data,
std::string *  cloned 
)

Create a new object from an existing MerkleDAG node and set its data.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectpatchsetdata.

An example usage:

/* std::string target_id = "QmbDtmUVyiN8vFZr8cDTp...67bTj" for example. */
std::string with_new_data_id;
client.ObjectPatchSetData(
target_id,
&with_new_data_id);
ipfs::Json with_new_data;
client.ObjectGet(with_new_data_id, &with_new_data);
std::cout << "Set the data of " << target_id << "." << std::endl
<< "New object " << with_new_data_id << ":" << std::endl
<< with_new_data.dump(2) << std::endl;
/* An example output:
Set the data of QmbDtmUVyiN8vFZr8cDTpuVtZwnVd3k6wqpEq3NvE67bTj.
New object QmZ19WxdWzPbLTyTkb1MYDvpdLi1pu1fRtECAiHzhLJAxz:
{
"Data": "new data",
"Links": [
{
"Hash": "QmNYaS23te5Rja36U94JoSTuMxJZmBEnHN8KEcjR6rGRGn",
"Name": "link to file1.txt",
"Size": 12
},
{
"Hash": "QmYuNVU4vwpXqX9RLv47HbmiveWwZvLBsXyYbUtEQMJYGQ",
"Name": "link to file2.txt",
"Size": 12
}
]
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]sourceId of the object whose data to set (multihash).
[in]dataData to be set.
[out]clonedId of the newly created (cloned) object (multihash).

◆ ObjectPut()

void ipfs::Client::ObjectPut ( const Json object,
Json object_stored 
)

Store a MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectput.

An example usage:

ipfs::Json object_to_store = R"(
{
"Data": "another",
"Links": [ {
"Name": "some link",
"Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V",
"Size": 8
} ]
}
)"_json;
ipfs::Json object_stored;
client.ObjectPut(object_to_store, &object_stored);
std::cout << "Object to store:" << std::endl
<< object_to_store.dump(2) << std::endl;
std::cout << "Stored object:" << std::endl
<< object_stored.dump(2) << std::endl;
/* An example output:
Object to store:
{
"Data": "another",
"Links": [
{
"Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V",
"Name": "some link",
"Size": 8
}
]
}
Stored object:
{
"Hash": "QmZZmY4KCu9r3e7M2Pcn46Fc5qbn6NpzaAGaYb22kbfTqm",
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]objectNode to store.
[out]object_storedStored node. Should be the same as the provided object plus the stored object's multihash id.

◆ ObjectStat()

void ipfs::Client::ObjectStat ( const std::string &  object_id,
Json stat 
)

Get stats about a MerkleDAG node.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/OBJECT.md#objectstat.

An example usage:

ipfs::Json stat;
client.ObjectStat("QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG", &stat);
std::cout << "Object data size: " << stat["DataSize"] << std::endl;
/* An example output:
Object data size: 2
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId of the object to query (multihash).
[out]statStats about the object. For example: {"NumLinks": 0, "BlockSize": 10, "LinksSize": 2, ...}

◆ operator=() [1/2]

Client & ipfs::Client::operator= ( const Client other)

Copy assignment operator.

Returns
*this
Parameters
[in]otherOther client connection to be copied.

◆ operator=() [2/2]

Client & ipfs::Client::operator= ( Client &&  other)

Move assignment operator.

Returns
*this
Parameters
[in,out]otherOther client connection to be moved.

◆ PinAdd()

void ipfs::Client::PinAdd ( const std::string &  object_id)

Pin a given IPFS object.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/PIN.md#pinadd.

An example usage:

/* std::string object_id = "QmdfTbBqBPQ7VNxZEYEj14V...1zR1n" for example. */
client.PinAdd(object_id);
std::cout << "Pinned object: " << object_id << std::endl;
/* An example output:
Pinned object: QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId of the object to pin (multihash).

◆ PinLs() [1/2]

void ipfs::Client::PinLs ( Json pinned)

List all the objects pinned to local storage.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/PIN.md#pinls.

An example usage:

ipfs::Json pinned;
client.PinLs(&pinned);
std::cout << "List of all pinned objects:" << std::endl
<< pinned.dump(2) << std::endl;
/* An example output:
List of all pinned objects:
{
"Keys": {
"QmNYaS23te5Rja36U94JoSTuMxJZmBEnHN8KEcjR6rGRGn": {
"Type": "indirect"
},
"QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn": {
"Type": "recursive"
},
"Qmf5t6BgYbiT2usHRToVzLu5DNHfH39S4dq6JTxf69Npzt": {
"Type": "indirect"
}
}
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]pinnedList of pinned objects.

◆ PinLs() [2/2]

void ipfs::Client::PinLs ( const std::string &  object_id,
Json pinned 
)

List the objects pinned under a specific hash.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/PIN.md#pinls.

An example usage:

/* std::string object_id = "QmdfTbBqBPQ7VNxZEYEj14V...1zR1n" for example. */
client.PinLs(object_id, &pinned);
std::cout << "List pinned objects under " << object_id << ":" << std::endl
<< pinned.dump(2) << std::endl;
/* An example output:
List pinned objects under QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n:
{
"Keys": {
"QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n": {
"Type": "recursive"
}
}
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]object_idId of the object to list (multihash).
[out]pinnedList of pinned objects.

◆ PinRm()

void ipfs::Client::PinRm ( const std::string &  object_id,
PinRmOptions  options 
)

Unpin an object.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/PIN.md#pinrm.

An example usage:

/* std::string object_id = "QmdfTbBqBPQ7VNxZEYEj14V...1zR1n" for example. */
bool unpinned;
try {
unpinned = true;
} catch (const std::exception&) {
unpinned = false;
}
if (unpinned) {
throw std::runtime_error(
"Unpinning " + object_id +
" non-recursively succeeded but should have failed.");
}
client.PinRm(object_id, ipfs::Client::PinRmOptions::RECURSIVE);
Exceptions
std::exceptionif any error occurs
See also
PinRmOptions
Since
version 0.1.0
Parameters
[in]object_idId of the object to unpin (multihash).
[in]optionsUnpin options.

◆ SwarmAddrs()

void ipfs::Client::SwarmAddrs ( Json addresses)

List of known addresses of each peer connected.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/SWARM.md#swarmaddrs.

An example usage:

ipfs::Json addresses;
client.SwarmAddrs(&addresses);
std::cout << "Known addresses of each peer:" << std::endl
<< addresses.dump(2).substr(0, 8192) << std::endl;
/* An example output:
Known addresses of each peer:
{
"Addrs": {
"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y": [
"/ip4/127.0.0.1/tcp/4001",
"/ip4/172.17.0.2/tcp/4001",
"/ip4/5.9.33.222/tcp/1040",
"/ip4/5.9.33.222/tcp/4001",
"/ip6/::1/tcp/4001"
],
"QmNYXVn17mHCA1cdTh2DF5KmD9RJ72QkJQ6Eo7HyAuMYqG": [
"/ip4/10.12.0.5/tcp/4001",
"/ip4/104.131.144.16/tcp/4001",
"/ip4/127.0.0.1/tcp/4001",
"/ip6/::1/tcp/4001"
],
...
}
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]addressesThe retrieved list.

◆ SwarmConnect()

void ipfs::Client::SwarmConnect ( const std::string &  peer)

Open a connection to a given address.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/SWARM.md#swarmconnect.

An example usage:

/* std::string peer =
* "/ip4/104.131.131.81/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
* for example */
client.SwarmConnect(peer);
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]peerPeer to connect to. For example: "/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"

◆ SwarmDisconnect()

void ipfs::Client::SwarmDisconnect ( const std::string &  peer)

Close a connection on a given address.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/SWARM.md#swarmdisconnect.

An example usage:

/* std::string peer =
* "/ip4/104.131.131.81/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
* for example */
client.SwarmDisconnect(peer);
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[in]peerPeer to disconnect from to. For example: "/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"

◆ SwarmPeers()

void ipfs::Client::SwarmPeers ( Json peers)

List the peers that we have connections with.

Implements https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/SWARM.md#swarmpeers.

An example usage:

ipfs::Json peers;
client.SwarmPeers(&peers);
std::cout << "Peers:" << std::endl << peers.dump(2) << std::endl;
/* An example output:
Peers:
{
"Strings": [
"/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.131.144.16/tcp/4001/ipfs/QmNYXVn17mHCA1cdTh2DF5KmD9RJ72QkJQ6Eo7HyAuMYqG",
"/ip4/104.223.59.174/tcp/4001/ipfs/QmeWdgoZezpdHz1PX8Ly8AeDQahFkBNtHn6qKeNtWP1jB6",
...
]
}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]peersThe retrieved list.

◆ Version()

void ipfs::Client::Version ( Json version)

Return the implementation version of the peer.

Implements https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/MISCELLANEOUS.md#version.

An example usage:

ipfs::Json version;
client.Version(&version);
std::cout << "Peer's version: " << version << std::endl;
/* An example output:
Peer's version: {"Commit":"ee6dd5e","Golang":"go1.7.3","Repo":"4",
"System":"amd64/freebsd","Version":"0.4.3"}
*/
Exceptions
std::exceptionif any error occurs
Since
version 0.1.0
Parameters
[out]versionThe peer's implementation version. It contains at least the properties "Repo", "System", "Version".

The documentation for this class was generated from the following files: