c-ipfs/include/ipfs/exchange/exchange.h
2017-08-31 06:41:54 -05:00

77 lines
2.4 KiB
C

#pragma once
/**
* This is the definition of an "Exchange"
*
* Anything that implements the Exchange interface can be used as
* an IPFS block exchange protocol.
*/
#include "ipfs/blocks/block.h"
#include "ipfs/cid/cid.h"
#include "libp2p/utils/vector.h"
/**
* These are methods that the local IPFS daemon (or client)
* call to communicate with the local repository or network
*/
struct Exchange {
/**
* Retrieve a block from peers within the deadline enforced
* by the context
*
* NOTE: Shouldn't the block parameter be a callback (function pointer)?
* Otherwise, this function is going to block. Is that what we want?
*
* @param context the context
* @param cid the hash of the block to retrieve
* @param block a pointer to the block (allocated by this method if return is true)
* @returns true(1) on success, false(0) otherwise
*/
int (*GetBlock)(struct Exchange* exchange, struct Cid* cid, struct Block** block);
/**
* Retrieve a block from peers asynchronously
*
* @param context the context
* @param cid the hash of the block to retrieve
* @param queue_entry the queue entry to watch
* @returns true(1) on success, false(0) otherwise
*/
int (*GetBlockAsync)(struct Exchange* exchange, struct Cid* cid, struct Block** block);
/**
* Retrieve several blocks
* @param context the context
* @param Cids a vector of hashes for the blocks to be retrieved
* @param blocks a pointer to a vector of retrieved blocks (will be NULL on error)
* @returns true(1) on success, otherwise false(0)
*/
int (*GetBlocks)(struct Exchange* exchange, struct Libp2pVector* Cids, struct Libp2pVector** blocks);
/**
* Announces the existance of a block to this bitswap service. The service will
* potentially notify its peers.
* NOTE: This is mainly designed to announce blocks added by non-bitswap methods (i.e. the local user)
* @param block the block being announced
* @returns true(1) on success, false(0) if not
*/
int (*HasBlock)(struct Exchange* exchange, struct Block* block);
/**
* Determine if we're online
* @returns true(1) if we're online
*/
int (*IsOnline)(struct Exchange*);
/**
* Close up the exchange, and go offline
* @returns true(1);
*/
int (*Close)(struct Exchange*);
/**
* Used by each implementation to maintain state
* (will be cast-ed to an implementation-specific structure)
*/
void* exchangeContext;
};