diff --git a/src/protocol/bittorrent/common.h b/src/protocol/bittorrent/common.h index 90f1e1b6..70d6df64 100644 --- a/src/protocol/bittorrent/common.h +++ b/src/protocol/bittorrent/common.h @@ -19,50 +19,51 @@ struct bittorrent_fetcher; struct connection; struct terminal; -/* The least acceptable default sharing rate. */ +/** The least acceptable default sharing rate. */ #define BITTORRENT_DEFAULT_SHARING_RATE 0.250 -/* The number of seconds between updating the connection state and most +/** The number of seconds between updating the connection state and most * importantly choke and unchoke peer connections. */ #define BITTORRENT_DEFAULT_CHOKE_INTERVAL 10 -/* The length regarded as ``typical'' by the community wiki specification. */ -/* Looks like Bram uses 2^14 here. */ -/* Used for the protocol.bittorrent.request_length option */ +/** The length regarded as ``typical'' by the community wiki specification. + * Looks like Bram uses 2^14 here. + * Used for the protocol.bittorrent.request_length option */ #define BITTORRENT_REQUEST_LENGTH (1 << 14) -/* The length of requested blocks of pieces should not exceed 2^17 bytes. */ -/* Used for the protocol.bittorrent.max_request_length option */ -/* Bram uses 2^23 here. */ +/** The length of requested blocks of pieces should not exceed 2^17 bytes. + * Used for the protocol.bittorrent.max_request_length option + * Bram uses 2^23 here. */ #define BITTORRENT_REQUEST_ACCEPT_LENGTH (1 << 23) -/* The maximum size to allow a peer message to have. */ +/** The maximum size to allow a peer message to have. */ /* Bram uses 2^23 here. */ #define BITTORRENT_MESSAGE_MAX_SIZE (1 << 23) -/* 20-byte string ID used for both peer IDs and info-hashes. */ +/** 20-byte string ID used for both peer IDs and info-hashes. */ typedef sha1_digest_bin_T bittorrent_id_T; -/* Special peer ID used for determining whether an ID has been set. */ +/** Special peer ID used for determining whether an ID has been set. */ const bittorrent_id_T BITTORRENT_NULL_ID; +/** Check if the ID has been set. */ #define bittorrent_id_is_empty(id) \ (!memcmp(id, BITTORRENT_NULL_ID, sizeof(bittorrent_id_T))) -/* BitTorrent error states. */ +/** BitTorrent error states. */ enum bittorrent_state { - BITTORRENT_STATE_OK, /* All is well. */ - BITTORRENT_STATE_ERROR, /* Some error happened. */ - BITTORRENT_STATE_REQUEST_FAILURE, /* Failure from tracker. */ - BITTORRENT_STATE_OUT_OF_MEM, /* Allocation failure. */ - BITTORRENT_STATE_CACHE_FAILURE, /* Cache data access failed. */ - BITTORRENT_STATE_CACHE_RESUME, /* Resume state from disk.. */ - BITTORRENT_STATE_FILE_MISSING, /* File does not exist. */ + BITTORRENT_STATE_OK, /**< All is well. */ + BITTORRENT_STATE_ERROR, /**< Some error happened. */ + BITTORRENT_STATE_REQUEST_FAILURE, /**< Failure from tracker. */ + BITTORRENT_STATE_OUT_OF_MEM, /**< Allocation failure. */ + BITTORRENT_STATE_CACHE_FAILURE, /**< Cache data access failed. */ + BITTORRENT_STATE_CACHE_RESUME, /**< Resume state from disk.. */ + BITTORRENT_STATE_FILE_MISSING, /**< File does not exist. */ }; -/* For showing tracker failure responses to the user. */ +/** For showing tracker failure responses to the user. */ struct bittorrent_message { LIST_HEAD(struct bittorrent_message); @@ -76,7 +77,7 @@ struct bittorrent_message { /* Peer-wire types: */ /* ************************************************************************** */ -/* BitTorrent peer-wire state and message IDs. */ +/** BitTorrent peer-wire state and message IDs. */ enum bittorrent_message_id { /* Special internal state and message type. */ BITTORRENT_MESSAGE_ERROR = -3, @@ -95,40 +96,40 @@ enum bittorrent_message_id { BITTORRENT_MESSAGE_CANCEL = 8, }; -/* The peer request matches information sent in the request and cancel messages +/** The peer request matches information sent in the request and cancel messages * in the peer-wire protocol. See the piece cache header file (cache.h) for more * information about the cloned flag. */ struct bittorrent_peer_request { LIST_HEAD(struct bittorrent_peer_request); - uint32_t piece; /* Zero-based piece index. */ - uint32_t offset; /* Zero-based piece byte offset. */ - uint32_t length; /* The wanted number of bytes. */ + uint32_t piece; /**< Zero-based piece index. */ + uint32_t offset; /**< Zero-based piece byte offset. */ + uint32_t length; /**< The wanted number of bytes. */ - uint16_t block; /* The block index in the piece. */ + uint16_t block; /**< The block index in the piece. */ /* This holds the message id when the request struct is used for queuing * pending messages. */ - char id; /* -> enum bittorrent_message_id */ + char id; /**< @-> enum bittorrent_message_id */ - unsigned int cloned:1; /* The request was cloned. */ - unsigned int requested:1; /* Whether it has been requested. */ + unsigned int cloned:1; /**< The request was cloned. */ + unsigned int requested:1; /**< Whether it has been requested. */ }; struct bittorrent_peer_status { - /* FIFO-like recording of requests. */ + /** FIFO-like recording of requests. */ LIST_OF(struct bittorrent_peer_request) requests; /* Flags for scheduling updating of the peer state. */ - unsigned int choked:1; /* The peer was choked. */ - unsigned int interested:1; /* The peer is interested. */ - unsigned int snubbed:1; /* The peer was snubbed. */ + unsigned int choked:1; /**< The peer was choked. */ + unsigned int interested:1; /**< The peer is interested. */ + unsigned int snubbed:1; /**< The peer was snubbed. */ /* State flags used for determining what to accept. */ - unsigned int handshake:1; /* The handshake was sent. */ - unsigned int bitfield:1; /* The bitfield was sent. */ - unsigned int initiater:1; /* Initiater of the connection. */ - unsigned int seeder:1; /* The peer has the complete torrent. */ + unsigned int handshake:1; /**< The handshake was sent. */ + unsigned int bitfield:1; /**< The bitfield was sent. */ + unsigned int initiater:1; /**< Initiater of the connection. */ + unsigned int seeder:1; /**< The peer has the complete torrent. */ }; struct bittorrent_peer_stats { @@ -142,38 +143,38 @@ struct bittorrent_peer_stats { off_t uploaded; }; -/* Peer connection information. */ +/** Peer connection information. */ struct bittorrent_peer_connection { LIST_HEAD(struct bittorrent_peer_connection); - /* Unique peer ID string which can be used to look-up the peer hash. */ + /** Unique peer ID string which can be used to look-up the peer hash. */ bittorrent_id_T id; - /* Timer handle for scheduling timeouts. */ + /** Timer handle for scheduling timeouts. */ timer_id_T timer; - /* Socket information. */ + /** Socket information. */ struct socket *socket; - /* Progress information and counter for the number of uploaded or + /** Progress information and counter for the number of uploaded or * downloaded bytes depending on the mode. */ struct bittorrent_peer_stats stats; - /* The BitTorrent connection the peer connection is associated with. + /** The BitTorrent connection the peer connection is associated with. * For recently accepted peer connections it might be NULL indicating * that the info_hash has not yet been read from the handshake. */ struct bittorrent_connection *bittorrent; - /* Local client and remote peer status info. */ + /** Local client and remote peer status info. */ struct bittorrent_peer_status local; struct bittorrent_peer_status remote; - /* Outgoing message queue. Note piece messages are maintained entirely + /** Outgoing message queue. Note piece messages are maintained entirely * in the request list in the bittorrent_peer_status struct. */ LIST_OF(struct bittorrent_peer_request) queue; - /* A bitfield of the available pieces from the peer. */ - /* The size depends on the number of pieces. */ + /** A bitfield of the available pieces from the peer. + * The size depends on the number of pieces. */ struct bitfield *bitfield; }; @@ -182,27 +183,27 @@ struct bittorrent_peer_connection { /* Tracker types: */ /* ************************************************************************** */ -/* Event state information needed by the tracker. */ +/** Event state information needed by the tracker. */ enum bittorrent_tracker_event { - BITTORRENT_EVENT_STARTED = 0, /* XXX: Zero, to always send first */ - BITTORRENT_EVENT_STOPPED, /* Graceful shut down */ - BITTORRENT_EVENT_COMPLETED, /* Download was completed */ - BITTORRENT_EVENT_REGULAR, /* Regular (periodical) tracker request */ + BITTORRENT_EVENT_STARTED = 0, /**< XXX: Zero, to always send first */ + BITTORRENT_EVENT_STOPPED, /**< Graceful shut down */ + BITTORRENT_EVENT_COMPLETED, /**< Download was completed */ + BITTORRENT_EVENT_REGULAR, /**< Regular (periodical) tracker request */ }; -/* This stores info about tracker requests. */ -/* It is not a real connection because it consists of a series of HTTP requests +/** This stores info about tracker requests. + * It is not a real connection because it consists of a series of HTTP requests * but both the tracker and client is supposed to keep state information across * all requests. */ struct bittorrent_tracker_connection { - /* Used for keeping track of when to send event info to the tracker. */ + /** Used for keeping track of when to send event info to the tracker. */ enum bittorrent_tracker_event event; - /* Time in seconds between contacting the tracker and a timer handle. */ + /** Time in seconds between contacting the tracker and a timer handle. */ timer_id_T timer; int interval; - /* Requesting the tracker failed or was never started so no + /** Requesting the tracker failed or was never started so no * event=stopped should be sent. */ unsigned int failed:1; unsigned int started:1; @@ -213,74 +214,75 @@ struct bittorrent_tracker_connection { /* Metafile types: */ /* ************************************************************************** */ -/* Information about peers returned by the tracker. */ +/** Information about peers returned by the tracker. */ struct bittorrent_peer { LIST_HEAD(struct bittorrent_peer); - bittorrent_id_T id; /* Unique peer ID string. */ - uint16_t port; /* The port number to connect to. */ - unsigned char ip[1]; /* String with a IPv4 or IPv6 address. */ + bittorrent_id_T id; /**< Unique peer ID string. */ + uint16_t port; /**< The port number to connect to. */ + unsigned char ip[1]; /**< String with a IPv4 or IPv6 address. */ }; -/* Information about a file in the torrent. */ +/** Information about a file in the torrent. */ struct bittorrent_file { LIST_HEAD(struct bittorrent_file); - off_t length; /* Length of the file in bytes. */ - md5_digest_hex_T md5sum; /* Hexadecimal MD5 sum of the file. */ + off_t length; /**< Length of the file in bytes. */ + md5_digest_hex_T md5sum; /**< Hexadecimal MD5 sum of the file. */ int selected; - unsigned char name[1]; /* Filename converted from path list. */ + unsigned char name[1]; /**< Filename converted from path list. */ }; -/* Static information from the .torrent metafile. */ +/** Static information from the .torrent metafile. */ struct bittorrent_meta { - /* The SHA1 info hash of the value of the info key from the metainfo + /** The SHA1 info hash of the value of the info key from the metainfo * .torrent file is used regularly when connecting to both the tracker * and peers. */ bittorrent_id_T info_hash; - /* Optional information about the creation time of the torrent. */ - /* Used if the document.download.set_original_time is true. */ + /** Optional information about the creation time of the torrent. + * Used if the document.download.set_original_time is true. */ time_t creation_date; - /* Optional comment in free-form text. */ + /** Optional comment in free-form text. */ unsigned char *comment; - /* The announced URI of each available tracker. */ + /** The announced URI of each available tracker. */ struct uri_list tracker_uris; - /* The number of pieces. */ + /** The number of pieces. */ uint32_t pieces; - /* The number of bytes in each piece. The last piece can be shorter - * than the others. */ + /** The number of bytes in each piece. */ uint32_t piece_length; + /** The last piece can be shorter than the others. */ uint32_t last_piece_length; - /* List of concatenated SHA1 hash values for each piece. */ + /** List of concatenated SHA1 hash values for each piece. */ unsigned char *piece_hash; - /* The type of the torrent. */ + /** The type of the torrent. */ enum { BITTORRENT_SINGLE_FILE, BITTORRENT_MULTI_FILE } type; - unsigned int malicious_paths:1; /* Potential bad file path detected. */ + /** Potential bad file path detected. */ + unsigned int malicious_paths:1; - /* The name of either the single file or the top-most directory. */ + /** The name of either the single file or the top-most directory. */ unsigned char *name; - /* A list with information about files in the torrent. */ - /* The list is a singleton for single-file torrents. */ + /** A list with information about files in the torrent. + * The list is a singleton for single-file torrents. */ LIST_OF(struct bittorrent_file) files; }; enum bittorrent_connection_mode { - BITTORRENT_MODE_PIECELESS, /* The client has no piece to share. */ - BITTORRENT_MODE_NORMAL, /* The client is up- and downloading. */ - BITTORRENT_MODE_END_GAME, /* All remaining pieces are requested. */ - BITTORRENT_MODE_SEEDER, /* The client is only uploading. */ + BITTORRENT_MODE_PIECELESS, /**< The client has no piece to share. */ + BITTORRENT_MODE_NORMAL, /**< The client is up- and downloading. */ + BITTORRENT_MODE_END_GAME, /**< All remaining pieces are requested. */ + BITTORRENT_MODE_SEEDER, /**< The client is only uploading. */ }; -/* This stores info about an active BitTorrent connection. Note, the list head +/** This stores info about an active BitTorrent connection. Note, the list head * is used by the handling of the peer-wire listening socket and should only be * managed by that. */ struct bittorrent_connection { @@ -288,55 +290,57 @@ struct bittorrent_connection { enum bittorrent_connection_mode mode; - /* Static information from the .torrent metafile. */ + /** Static information from the .torrent metafile. */ struct bittorrent_meta meta; - /* Dynamic tracker information. */ + /** Dynamic tracker information. */ struct bittorrent_tracker_connection tracker; - /* Dynamic tracker information. */ + /** Dynamic tracker information. */ struct bittorrent_piece_cache *cache; - /* Back-reference to the connection the bittorrent connection belongs + /** Back-reference to the connection the bittorrent connection belongs * to. */ struct connection *conn; - /* Active peer list */ - /* The size is controlled by the protocol.bittorrent.max_active_peers + /** Active peer list + * The size is controlled by the protocol.bittorrent.max_active_peers * option. */ LIST_OF(struct bittorrent_peer_connection) peers; - /* List of information about potential peers. */ - /* TODO: Use hash. */ + /** List of information about potential peers. + * @todo TODO: Use hash. */ LIST_OF(struct bittorrent_peer) peer_pool; - /* The peer ID of the client. */ + /** The peer ID of the client. */ bittorrent_id_T peer_id; - /* The port of the listening socket */ + /** The port of the listening socket */ uint16_t port; - /* Timer handle for scheduling periodic updating and rating of peer + /** Timer handle for scheduling periodic updating and rating of peer * connections. */ timer_id_T timer; - /* Statistics for the tracker and total progress information for the + /** Statistics for the tracker and total progress information for the * user interface. */ struct progress upload_progress; off_t uploaded; off_t downloaded; off_t left; - /* Number of seeders and leechers. */ + /** Number of seeders. */ uint32_t complete; + /** Number of leechers. */ uint32_t incomplete; double sharing_rate; - /* Information about any running metainfo file or tracker request. */ + /** Information about any running metainfo file or tracker request. */ struct bittorrent_fetcher *fetch; - /* For notifying on completion. May be NULL. */ + /** For notifying on completion. + * May be NULL. */ struct terminal *term; }; @@ -416,10 +420,10 @@ void done_bittorrent_fetch(struct bittorrent_fetcher **fetcher_ref); /* ************************************************************************** */ enum bittorrent_blacklist_flags { - BITTORRENT_BLACKLIST_NONE, /* No blacklisting is in effect */ - BITTORRENT_BLACKLIST_PEER_POOL, /* Blacklist from peer pool. */ - BITTORRENT_BLACKLIST_MALICIOUS, /* Malicious peer, refuse connection */ - BITTORRENT_BLACKLIST_BEHAVIOUR, /* Unfair behaviour, refuse connection */ + BITTORRENT_BLACKLIST_NONE, /**< No blacklisting is in effect */ + BITTORRENT_BLACKLIST_PEER_POOL, /**< Blacklist from peer pool. */ + BITTORRENT_BLACKLIST_MALICIOUS, /**< Malicious peer, refuse connection */ + BITTORRENT_BLACKLIST_BEHAVIOUR, /**< Unfair behaviour, refuse connection */ }; void diff --git a/src/protocol/bittorrent/piececache.h b/src/protocol/bittorrent/piececache.h index 1c2a5d9e..f76a9e9f 100644 --- a/src/protocol/bittorrent/piececache.h +++ b/src/protocol/bittorrent/piececache.h @@ -11,7 +11,8 @@ struct string; struct bittorrent_piece_cache_entry { LIST_HEAD(struct bittorrent_piece_cache_entry); - /* To keep track of the client's view of the swarm in regards to pieces a + /** Piece rarity index + * To keep track of the client's view of the swarm in regards to pieces a * piece rarity index for neighboring peers is maintained for each piece * in the torrent. It keeps track of how many neighboring peers have the * piece. The smaller the value the more rare the piece is. The table is @@ -19,50 +20,51 @@ struct bittorrent_piece_cache_entry { * indicates that no neightboring peer has the piece. */ uint16_t rarity; - unsigned int completed:1; /* All blocks was downloaded. */ - unsigned int remaining:1; /* Nothing has been even requested. */ - unsigned int locked:1; /* Edge piece from partial downloads. */ - unsigned int selected:1; /* Piece is part of partial download. */ + unsigned int completed:1; /**< All blocks was downloaded. */ + unsigned int remaining:1; /**< Nothing has been even requested. */ + unsigned int locked:1; /**< Edge piece from partial downloads. */ + unsigned int selected:1; /**< Piece is part of partial download. */ - /* A bitfield of the blocks which remains to be downloaded for this + /** A bitfield of the blocks which remains to be downloaded for this * piece. May be NULL if downloading is not in progress. */ struct bitfield *blocks; - /* The data of the piece. May be NULL if data has not been downloaded - * or the piece has been written to disk. */ - /* XXX: This memory is mmaped using the mem_mmap_*() functions. */ + /** The data of the piece. + * May be NULL if data has not been downloaded + * or the piece has been written to disk. + * XXX: This memory is mmaped using the mem_mmap_*() functions. */ unsigned char *data; }; struct bittorrent_piece_cache { /* The following is mostly maintained for making it easy to display in * dialogs. */ - unsigned int remaining_pieces; /* Number of untouched pieces */ - unsigned int completed_pieces; /* Number of downloaded pieces */ - unsigned int loading_pieces; /* Number of pieces in progress */ - unsigned int rejected_pieces; /* Number of hash check rejects */ - unsigned int unavailable_pieces;/* Number of unavailable pieces */ - unsigned int partial_pieces; /* Number of selected file pieces */ - unsigned int locked_pieces; /* Pieces locked due to partial download */ + unsigned int remaining_pieces; /**< Number of untouched pieces */ + unsigned int completed_pieces; /**< Number of downloaded pieces */ + unsigned int loading_pieces; /**< Number of pieces in progress */ + unsigned int rejected_pieces; /**< Number of hash check rejects */ + unsigned int unavailable_pieces;/**< Number of unavailable pieces */ + unsigned int partial_pieces; /**< Number of selected file pieces */ + unsigned int locked_pieces; /**< Pieces locked due to partial download */ /* Flags set from the download dialog. */ - unsigned int delete_files:1; /* Unlink files on shutdown? */ - unsigned int notify_complete:1; /* Notify upon completion? */ - unsigned int partial:1; /* Dealing with a partial download? */ + unsigned int delete_files:1; /**< Unlink files on shutdown? */ + unsigned int notify_complete:1; /**< Notify upon completion? */ + unsigned int partial:1; /**< Dealing with a partial download? */ - /* The pipe descripter used for communicating with the resume thread. */ + /** The pipe descripter used for communicating with the resume thread. */ int resume_fd; uint32_t resume_pos; - /* A bitfield of the available pieces. */ + /** A bitfield of the available pieces. */ struct bitfield *bitfield; - /* A list of completed and saved entries which has been loaded into + /** A list of completed and saved entries which has been loaded into * memory. The allocated memory for all these entries is disposable. The * entries are sorted in a LRU-manner. */ LIST_OF(struct bittorrent_piece_cache_entry) queue; - /* Remaining pieces are tracked using the remaining_blocks member of the + /** Remaining pieces are tracked using the remaining_blocks member of the * piece cache entry and a free list of piece blocks to be requested. * Requests are taken from the free list every time a peer queries which * piece block to request next. If the piece list is empty (or if the