WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Affero General Public License for more details.
-
+
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
SPDX-License-Identifier: AGPL3.0-or-later
-*/
+ */
/**
* @author Christian Grothoff
* @author Bart Polot
#define GNUNET_CADET_SERVICE_H
#ifdef __cplusplus
-extern "C"
-{
-#if 0 /* keep Emacsens' auto-indent happy */
+extern "C" {
+#if 0 /* keep Emacsens' auto-indent happy */
}
#endif
#endif
* Given two peers, both may initiate channels over the same tunnel.
* The @e cn must be greater or equal to 0x80000000 (high-bit set)
* for tunnels initiated with the peer that has the larger peer
- * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity().
+ * identity as compared using #GNUNET_memcmp().
*/
uint32_t cn GNUNET_PACKED;
};
-
-/**
- * Channel options. Second line indicates filed in the
- * CadetChannelInfo union carrying the answer.
- */
-enum GNUNET_CADET_ChannelOption
-{
- /**
- * Default options: unreliable, default buffering, not out of order.
- */
- GNUNET_CADET_OPTION_DEFAULT = 0x0,
-
- /**
- * Disable buffering on intermediate nodes (for minimum latency).
- * Yes/No.
- */
- GNUNET_CADET_OPTION_NOBUFFER = 0x1,
-
- /**
- * Enable channel reliability, lost messages will be retransmitted.
- * Yes/No.
- */
- GNUNET_CADET_OPTION_RELIABLE = 0x2,
-
- /**
- * Enable out of order delivery of messages.
- * Set bit for out-of-order delivery.
- */
- GNUNET_CADET_OPTION_OUT_OF_ORDER = 0x4,
-
- /**
- * Who is the peer at the other end of the channel.
- * Only for use in @c GNUNET_CADET_channel_get_info
- * struct GNUNET_PeerIdentity *peer
- */
- GNUNET_CADET_OPTION_PEER = 0x8
-
-};
-
-
/**
* Method called whenever a peer connects to a port in MQ-based CADET.
*
* - Each the #GNUNET_MQ_MessageCallback handlers for each message
* received on the @a channel.
*/
-typedef void *
-(*GNUNET_CADET_ConnectEventHandler) (void *cls,
- struct GNUNET_CADET_Channel *channel,
- const struct GNUNET_PeerIdentity *source);
+typedef void *(*GNUNET_CADET_ConnectEventHandler) (
+ void *cls,
+ struct GNUNET_CADET_Channel *channel,
+ const struct GNUNET_PeerIdentity *source);
/**
* @param cls Channel closure.
* @param channel Connection to the other end (henceforth invalid).
*/
-typedef void
-(*GNUNET_CADET_DisconnectEventHandler) (void *cls,
- const struct GNUNET_CADET_Channel *channel);
+typedef void (*GNUNET_CADET_DisconnectEventHandler) (
+ void *cls,
+ const struct GNUNET_CADET_Channel *channel);
/**
* @param window_size New window size. If the is more messages than buffer size
* this value will be negative. -- FIXME: make unsigned, we never call negative?
*/
-typedef void
-(*GNUNET_CADET_WindowSizeEventHandler) (void *cls,
- const struct GNUNET_CADET_Channel *channel,
- int window_size);
+typedef void (*GNUNET_CADET_WindowSizeEventHandler) (
+ void *cls,
+ const struct GNUNET_CADET_Channel *channel,
+ int window_size);
/**
/**
* Create a new channel towards a remote peer.
*
- * If the destination port is not open by any peer or the destination peer
- * does not accept the channel, @a disconnects will be called
- * for this channel.
+ * If the destination peer closes the channel after accepting it,
+ * @a disconnects will be called for this channel (unless
+ * #GNUNET_CADET_channel_destroy() was called on this end first).
*
* @param h CADET handle.
* @param channel_cls Closure for the channel. It's given to:
* - Each message type callback in @a handlers
* @param destination Peer identity the channel should go to.
* @param port Identification of the destination port.
- * @param options CadetOption flag field, with all desired option bits set to 1.
* @param window_changes Function called when the transmit window size changes.
* Can be NULL if this data is of no interest.
- * TODO Not yet implemented.
* @param disconnects Function called when the channel is disconnected.
* @param handlers Callbacks for messages we care about, NULL-terminated.
* @return Handle to the channel.
void *channel_cls,
const struct GNUNET_PeerIdentity *destination,
const struct GNUNET_HashCode *port,
- enum GNUNET_CADET_ChannelOption options,
GNUNET_CADET_WindowSizeEventHandler window_changes,
GNUNET_CADET_DisconnectEventHandler disconnects,
const struct GNUNET_MQ_MessageHandler *handlers);
const struct GNUNET_HashCode *
GC_u2h (uint32_t port);
-
+enum GNUNET_CADET_ChannelInfoOption
+{
+ /**
+ * Who is the peer at the other end of the channel.
+ * Only for use in @c GNUNET_CADET_channel_get_info
+ * struct GNUNET_PeerIdentity *peer
+ */
+ GNUNET_CADET_OPTION_PEER = 0x0
+};
/**
- * Struct to retrieve info about a channel.
+ * Union to retrieve info about a channel.
*/
union GNUNET_CADET_ChannelInfo
{
-
/**
* #GNUNET_YES / #GNUNET_NO, for binary flags.
*/
* Get information about a channel.
*
* @param channel Channel handle.
- * @param option Query type GNUNET_CADET_OPTION_*
* @param ... dependant on option, currently not used
* @return Union with an answer to the query.
*/
const union GNUNET_CADET_ChannelInfo *
GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
- enum GNUNET_CADET_ChannelOption option,
+ enum GNUNET_CADET_ChannelInfoOption option,
...);
/******************************************************************************/
+/**
+ * Internal details about a channel.
+ */
+struct GNUNET_CADET_ChannelInternals
+{
+ /**
+ * Root of the channel
+ */
+ struct GNUNET_PeerIdentity root;
+
+ /**
+ * Destination of the channel
+ */
+ struct GNUNET_PeerIdentity dest;
+
+ // to be expanded!
+};
+
+
/**
* Method called to retrieve information about a specific channel the cadet peer
* is aware of, including all transit nodes.
*
* @param cls Closure.
- * @param root Root of the channel.
- * @param dest Destination of the channel.
- * @param port Destination port of the channel.
- * @param root_channel_number Local number for root, if known.
- * @param dest_channel_number Local number for dest, if known.
- * @param public_channel_numbe Number for P2P, always known.
+ * @param info internal details, NULL for end of list
*/
-typedef void
-(*GNUNET_CADET_ChannelCB) (void *cls,
- const struct GNUNET_PeerIdentity *root,
- const struct GNUNET_PeerIdentity *dest,
- uint32_t /* UGH */ port,
- uint32_t /* ugh */ root_channel_number,
- uint32_t /* ugh */ dest_channel_number,
- uint32_t /* ugh */ public_channel_number);
+typedef void (*GNUNET_CADET_ChannelCB) (
+ void *cls,
+ const struct GNUNET_CADET_ChannelInternals *info);
/**
/**
- * Request information about a specific channel of the running cadet peer.
+ * Request information about channels to @a peer from the local peer.
*
* @param cfg configuration to use
* @param peer ID of the other end of the channel.
- * @param channel_number Channel number.
* @param callback Function to call with the requested data.
* @param callback_cls Closure for @c callback.
*/
struct GNUNET_CADET_ChannelMonitor *
GNUNET_CADET_get_channel (const struct GNUNET_CONFIGURATION_Handle *cfg,
struct GNUNET_PeerIdentity *peer,
- uint32_t /* UGH */ channel_number,
GNUNET_CADET_ChannelCB callback,
void *callback_cls);
GNUNET_CADET_get_channel_cancel (struct GNUNET_CADET_ChannelMonitor *cm);
+/**
+ * Information we return per peer.
+ */
+struct GNUNET_CADET_PeerListEntry
+{
+ /**
+ * Which peer is the information about?
+ */
+ struct GNUNET_PeerIdentity peer;
+
+ /**
+ * Do we have a tunnel to this peer?
+ */
+ int have_tunnel;
+
+ /**
+ * Number of disjoint known paths to @e peer.
+ */
+ unsigned int n_paths;
+
+ /**
+ * Length of the shortest path (0 = unknown, 1 = ourselves, 2 = direct neighbour).
+ */
+ unsigned int best_path_length;
+};
+
+
/**
* Method called to retrieve information about all peers in CADET, called
* once per peer.
* After last peer has been reported, an additional call with NULL is done.
*
* @param cls Closure.
- * @param peer Peer, or NULL on "EOF".
- * @param tunnel Do we have a tunnel towards this peer?
- * @param n_paths Number of known paths towards this peer.
- * @param best_path How long is the best path?
- * (0 = unknown, 1 = ourselves, 2 = neighbor)
+ * @param ple information about a peer, or NULL on "EOF".
*/
-typedef void
-(*GNUNET_CADET_PeersCB) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- int tunnel,
- unsigned int n_paths,
- unsigned int best_path);
+typedef void (*GNUNET_CADET_PeersCB) (
+ void *cls,
+ const struct GNUNET_CADET_PeerListEntry *ple);
/**
*/
struct GNUNET_CADET_PeersLister *
GNUNET_CADET_list_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
- GNUNET_CADET_PeersCB callback,
- void *callback_cls);
+ GNUNET_CADET_PeersCB callback,
+ void *callback_cls);
/**
/**
- * Method called to retrieve information about a specific peer
+ * Detailed information we return per peer.
+ */
+struct GNUNET_CADET_PeerPathDetail
+{
+ /**
+ * Peer this is about.
+ */
+ struct GNUNET_PeerIdentity peer;
+
+ /**
+ * Offset of the target peer on the @e path.
+ */
+ unsigned int target_offset;
+
+ /**
+ * Number of entries on the @e path.
+ */
+ unsigned int path_length;
+
+ /**
+ * Array of PEER_IDs representing all paths to reach the peer. Each
+ * path starts with the first hop (local peer not included). Each
+ * path ends with the destination peer (given in @e peer).
+ */
+ const struct GNUNET_PeerIdentity *path;
+};
+
+
+/**
+ * Method called to retrieve information about a specific path
* known to the service.
*
* @param cls Closure.
- * @param peer Peer ID.
- * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO
- * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO
- * @param n_paths Number of paths known towards peer.
- * @param paths Array of PEER_IDs representing all paths to reach the peer.
- * Each path starts with the first hop (local peer not included).
- * Each path ends with the destination peer (given in @c peer).
+ * @param ppd details about a path to the peer, NULL for end of information
*/
-typedef void
-(*GNUNET_CADET_PeerCB) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- int tunnel,
- int neighbor,
- unsigned int n_paths,
- const struct GNUNET_PeerIdentity *paths,
- int offset,
- int finished_with_paths);
+typedef void (*GNUNET_CADET_PathCB) (
+ void *cls,
+ const struct GNUNET_CADET_PeerPathDetail *ppd);
/**
- * Handle to cancel #GNUNET_CADET_get_peer() operation.
+ * Handle to cancel #GNUNET_CADET_get_path() operation.
*/
-struct GNUNET_CADET_GetPeer;
+struct GNUNET_CADET_GetPath;
/**
* Request information about a peer known to the running cadet peer.
- * The callback will be called for the tunnel once.
- * Only one info request (of any kind) can be active at once.
*
* @param cfg configuration to use
- * @param id Peer whose tunnel to examine.
+ * @param id Peer whose paths we want to examine.
* @param callback Function to call with the requested data.
* @param callback_cls Closure for @c callback.
* @return NULL on error
*/
-struct GNUNET_CADET_GetPeer *
-GNUNET_CADET_get_peer (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const struct GNUNET_PeerIdentity *id,
- GNUNET_CADET_PeerCB callback,
- void *callback_cls);
+struct GNUNET_CADET_GetPath *
+GNUNET_CADET_get_path (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ const struct GNUNET_PeerIdentity *id,
+ GNUNET_CADET_PathCB callback,
+ void *callback_cls);
/**
* Cancel @a gp operation.
*
* @param gp operation to cancel
- * @return closure from #GNUNET_CADET_get_peer().
+ * @return closure from #GNUNET_CADET_get_path().
*/
void *
-GNUNET_CADET_get_peer_cancel (struct GNUNET_CADET_GetPeer *gp);
+GNUNET_CADET_get_path_cancel (struct GNUNET_CADET_GetPath *gp);
+
+
+/**
+ * Details about a tunnel managed by CADET.
+ */
+struct GNUNET_CADET_TunnelDetails
+{
+ /**
+ * Target of the tunnel.
+ */
+ struct GNUNET_PeerIdentity peer;
+
+ /**
+ * How many channels use the tunnel.
+ */
+ uint32_t channels;
+
+ /**
+ * How many connections support the tunnel.
+ */
+ uint32_t connections;
+
+ /**
+ * What is our encryption state?
+ */
+ uint16_t estate;
+
+ /**
+ * What is our connectivity state?
+ */
+ uint16_t cstate;
+};
/**
* After last tunnel has been reported, an additional call with NULL is done.
*
* @param cls Closure.
- * @param peer Destination peer, or NULL on "EOF".
- * @param channels Number of channels.
- * @param connections Number of connections.
- * @param estate Encryption state.
- * @param cstate Connectivity state.
+ * @param td tunnel details, NULL for end of list
*/
-typedef void
-(*GNUNET_CADET_TunnelsCB) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- unsigned int channels,
- unsigned int connections,
- uint16_t estate,
- uint16_t cstate);
+typedef void (*GNUNET_CADET_TunnelsCB) (
+ void *cls,
+ const struct GNUNET_CADET_TunnelDetails *td);
/**
* @param cfg configuration to use
* @param callback Function to call with the requested data.
* @param callback_cls Closure for @c callback.
- * @return #GNUNET_OK / #GNUNET_SYSERR
+ * @return NULL on error
*/
struct GNUNET_CADET_ListTunnels *
GNUNET_CADET_list_tunnels (const struct GNUNET_CONFIGURATION_Handle *cfg,
- GNUNET_CADET_TunnelsCB callback,
- void *callback_cls);
+ GNUNET_CADET_TunnelsCB callback,
+ void *callback_cls);
/**
GNUNET_CADET_list_tunnels_cancel (struct GNUNET_CADET_ListTunnels *lt);
-
-/**
- * Method called to retrieve information about a specific tunnel the cadet peer
- * has established, o`r is trying to establish.
- *
- * @param cls Closure.
- * @param peer Peer towards whom the tunnel is directed.
- * @param n_channels Number of channels.
- * @param n_connections Number of connections.
- * @param channels Channels.
- * @param connections Connections.
- * @param estate Encryption state.
- * @param cstate Connectivity state.
- */
-typedef void
-(*GNUNET_CADET_TunnelCB) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- unsigned int n_channels,
- unsigned int n_connections,
- const struct GNUNET_CADET_ChannelTunnelNumber *channels,
- const struct GNUNET_CADET_ConnectionTunnelIdentifier *connections,
- unsigned int estate,
- unsigned int cstate);
-
-
-/**
- * Operation handle.
- */
-struct GNUNET_CADET_GetTunnel;
-
-
-/**
- * Request information about a tunnel of the running cadet peer.
- * The callback will be called for the tunnel once.
- * Only one info request (of any kind) can be active at once.
- *
- * @param cfg configuration to use
- * @param id Peer whose tunnel to examine.
- * @param callback Function to call with the requested data.
- * @param callback_cls Closure for @c callback.
- * @return #GNUNET_OK / #GNUNET_SYSERR
- */
-struct GNUNET_CADET_GetTunnel *
-GNUNET_CADET_get_tunnel (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const struct GNUNET_PeerIdentity *id,
- GNUNET_CADET_TunnelCB callback,
- void *callback_cls);
-
-
-/**
- * Cancel a monitor request. The monitor callback will not be called.
- *
- * @param lt operation handle
- * @return Closure given to #GNUNET_CADET_get_tunnel(), if any.
- */
-void *
-GNUNET_CADET_get_tunnel_cancel (struct GNUNET_CADET_GetTunnel *gt);
-
-
-#if 0 /* keep Emacsens' auto-indent happy */
+#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
/* ifndef GNUNET_CADET_SERVICE_H */
#endif
-/** @} */ /* end of group */
+/** @} */ /* end of group */
/* end of gnunet_cadet_service.h */
projects / oweals / gnunet.git / blobdiff