From c9da7ad1de089f109a3798ff19bede86348150aa Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Sun, 25 May 2014 22:49:36 +0200 Subject: peer.h: some documentation --- src/peer.h | 83 +++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 49 insertions(+), 34 deletions(-) (limited to 'src') diff --git a/src/peer.h b/src/peer.h index 50e8a68..c44f599 100644 --- a/src/peer.h +++ b/src/peer.h @@ -23,70 +23,85 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file peer.h + + Structures and functions for peer management +*/ + #pragma once #include "fastd.h" +/** The state of a peer */ typedef enum fastd_peer_state { - STATE_INIT = 0, - STATE_RESOLVING, - STATE_HANDSHAKE, - STATE_ESTABLISHED, + STATE_INIT = 0, /**< The peer peer was just created */ + STATE_RESOLVING, /**< The peer is currently resolving its first remote */ + STATE_HANDSHAKE, /**< The peer has tried to perform a handshake */ + STATE_ESTABLISHED, /**< The peer has established a connection */ } fastd_peer_state_t; +/** Dynamic state of a peer */ struct fastd_peer { - uint64_t id; + uint64_t id; /**< A unique ID assigned to each peer */ - const fastd_peer_config_t *config; - fastd_peer_group_t *group; + const fastd_peer_config_t *config; /**< The peer's fastd_peer_config_t */ + fastd_peer_group_t *group; /**< The peer's peer group */ + /** The socket used by the peer. This can either be a common bound socket or a + dynamic, unbound socket that is used exclusively by this peer */ fastd_socket_t *sock; - fastd_peer_address_t local_address; - fastd_peer_address_t address; + fastd_peer_address_t local_address; /**< The local address used to communicate with this peer */ + fastd_peer_address_t address; /**< The peers current address */ - fastd_peer_state_t state; - struct timespec timeout; - struct timespec keepalive_timeout; + fastd_peer_state_t state; /**< The peer's state */ + struct timespec timeout; /**< The timeout after which the peer is reset */ + struct timespec keepalive_timeout; /**< The timeout after which a keepalive is sent to the peer */ - VECTOR(fastd_remote_t) remotes; - ssize_t next_remote; + VECTOR(fastd_remote_t) remotes; /**< The vector of the peer's remotes */ + ssize_t next_remote; /**< An index into the field remotes or -1 */ - struct timespec next_handshake; - fastd_dlist_head_t handshake_entry; + struct timespec next_handshake; /**< The time of the next handshake */ + fastd_dlist_head_t handshake_entry; /**< Entry in the handshake queue */ - struct timespec last_handshake_timeout; - fastd_peer_address_t last_handshake_address; + struct timespec last_handshake_timeout; /**< No handshakes are sent to the peer until this timeout has occured to avoid flooding the peer */ + fastd_peer_address_t last_handshake_address; /**< The address the last handshake was sent to */ - struct timespec last_handshake_response_timeout; - fastd_peer_address_t last_handshake_response_address; + struct timespec last_handshake_response_timeout; /**< All handshakes from last_handshake_address will be ignored until this timeout has occured */ + fastd_peer_address_t last_handshake_response_address; /**< The address the last handshake was received from */ - struct timespec establish_handshake_timeout; + struct timespec establish_handshake_timeout; /**< A timeout during which all handshakes for this peer will be ignored after a new connection has been established */ #ifdef WITH_VERIFY - struct timespec verify_timeout; - struct timespec verify_valid_timeout; + struct timespec verify_timeout; /**< Specifies the minimum time after which on-verify may be run again */ + struct timespec verify_valid_timeout; /**< Specifies how long a peer stays valid after a successful on-verify run */ #endif - fastd_protocol_peer_config_t *protocol_config; - fastd_protocol_peer_state_t *protocol_state; + fastd_protocol_peer_config_t *protocol_config; /**< Protocol-specific peer configuration for config-less (on-verify) peers */ + fastd_protocol_peer_state_t *protocol_state; /**< Protocol-specific peer state */ }; +/** + Static configuration of a peer + + Peer configurations are kept in a linked list. +*/ struct fastd_peer_config { - fastd_peer_config_t *next; + fastd_peer_config_t *next; /**< The next peer configuration */ - const char *config_source_dir; + const char *config_source_dir; /**< The directory this peer's configuration was loaded from */ - bool enabled; - char *name; + bool enabled; /**< Speficies if this peer was disabled because of a configuration error */ + char *name; /**< The peer's name */ - fastd_remote_config_t *remotes; - char *key; - bool floating; - const fastd_peer_group_config_t *group; + fastd_remote_config_t *remotes; /**< A linked list of the peer's remote entries */ + char *key; /**< The peer's public key */ + bool floating; /**< Specifies if the peer has any floating remotes (or no remotes at all) */ + const fastd_peer_group_config_t *group; /**< The peer group the peer belongs to */ - fastd_protocol_peer_config_t *protocol_config; + fastd_protocol_peer_config_t *protocol_config; /**< The protocol-specific configuration of the peer */ }; struct fastd_peer_group { -- cgit v1.2.3