Add more documentation, some fixes

diff --git a/src/UDPConnection.cpp b/src/UDPConnection.cpp
index 1c5a6a4b7865305657965e446bb99f4e31d5f265..54cf42398c9a5d3482f01b7d507a73aa1c99c347 100644 (file)
--- a/src/UDPConnection.cpp
+++ b/src/UDPConnection.cpp
@@ -2234,7 +2234,7 @@ UDPC_ConnectionId* UDPC_get_list_connected(UDPC_HContext ctx, unsigned int *size
 }
 
 void UDPC_free_list_connected(UDPC_ConnectionId *list) {
-    std::free(list);
+    if(list) { std::free(list); }
 }
 
 uint32_t UDPC_get_protocol_id(UDPC_HContext ctx) {
@@ -2286,7 +2286,7 @@ int UDPC_set_receiving_events(UDPC_HContext ctx, int isReceivingEvents) {
         return 0;
     }
 
-    return c->isReceivingEvents.exchange(isReceivingEvents != 0);
+    return c->isReceivingEvents.exchange(isReceivingEvents != 0) ? 1 : 0;
 }
 
 UDPC_Event UDPC_get_event(UDPC_HContext ctx, unsigned long *remaining) {

diff --git a/src/UDPConnection.h b/src/UDPConnection.h
index f516dd76624c51400bb0dce63eaf57c4a804861e..903a03938f91d40ce03ab954965dd1ad201996a6 100644 (file)
--- a/src/UDPConnection.h
+++ b/src/UDPConnection.h
@@ -77,6 +77,7 @@
 #endif
 
 // other defines
+/// The maximum size of a UDP packet
 #define UDPC_PACKET_MAX_SIZE 8192
 #define UDPC_DEFAULT_PROTOCOL_ID 1357924680 // 0x50f04948
 
@@ -110,11 +111,17 @@ struct UDPC_Context;
 typedef struct UDPC_Context *UDPC_HContext;
 
 typedef enum {
+    /// Does not log anything
     UDPC_SILENT,
+    /// Only log errors
     UDPC_ERROR,
+    /// Log errors and warnings
     UDPC_WARNING,
+    /// Log errors, warnings, and info
     UDPC_INFO,
+    /// Log errors, warning, info, and verbose
     UDPC_VERBOSE,
+    /// Log all possible types of messages
     UDPC_DEBUG
 } UDPC_LoggingType;
 
@@ -143,9 +150,9 @@ typedef struct {
  */
 typedef struct {
     /*!
-     * A char array of size \p UDPC_PACKET_MAX_SIZE. Note that the received data
-     * will probably use up less data than the full size of the array. The
-     * actual size of the received data is \p dataSize.
+     * A char array of size \ref UDPC_PACKET_MAX_SIZE. Note that the received
+     * data will probably use up less data than the full size of the array. The
+     * actual size of the received data is \ref dataSize.
      */
     // id is stored at offset 8, size 4 (uint32_t) even for "empty" PktInfos
     char data[UDPC_PACKET_MAX_SIZE];
@@ -161,7 +168,7 @@ typedef struct {
      */
     uint32_t flags;
     /*!
-     * \brief The size in bytes of the received packet's data inside the \p data
+     * \brief The size in bytes of the received packet's data inside the \ref data
      * array member variable.
      *
      * If this variable is zero, then this packet is invalid, or an empty packet
@@ -169,9 +176,9 @@ typedef struct {
      */
     uint16_t dataSize;
     uint16_t rtt;
-    /// The \p UDPC_ConnectionId of the sender
+    /// The \ref UDPC_ConnectionId of the sender
     UDPC_ConnectionId sender;
-    /// The \p UDPC_ConnectionId of the receiver
+    /// The \ref UDPC_ConnectionId of the receiver
     UDPC_ConnectionId receiver;
 } UDPC_PacketInfo;
 
@@ -188,6 +195,10 @@ typedef struct {
  *
  * The other unmentioned enum values are used internally, and should never be
  * returned in a call to UDPC_get_event().
+ *
+ * All events returned by UDPC_get_event() will have set the member variable
+ * \p conId in the UDPC_Event which refers to the peer with which the event
+ * ocurred.
  */
 typedef enum {
     UDPC_ET_NONE,
@@ -226,6 +237,8 @@ typedef struct {
  * there is no need to convert the 16-bit value to network byte order, this will
  * be done automatically by this library when necessary (without modifying the
  * value in the used UDPC_ConnectionId).
+ *
+ * \return An initialized UDPC_ConnectionId
  */
 UDPC_ConnectionId UDPC_create_id(UDPC_IPV6_ADDR_TYPE addr, uint16_t port);
 
@@ -233,6 +246,8 @@ UDPC_ConnectionId UDPC_create_id(UDPC_IPV6_ADDR_TYPE addr, uint16_t port);
  * \brief Creates an UDPC_ConnectionId with the given addr, scope_id, and port
  *
  * port should be in native byte order (not network/big-endian).
+ *
+ * \return An initialized UDPC_ConnectionId
  */
 UDPC_ConnectionId UDPC_create_id_full(UDPC_IPV6_ADDR_TYPE addr, uint32_t scope_id, uint16_t port);
 
@@ -242,6 +257,8 @@ UDPC_ConnectionId UDPC_create_id_full(UDPC_IPV6_ADDR_TYPE addr, uint32_t scope_i
  * The address contained in the returned UDPC_ConnectionId will be zeroed out
  * (the "anyaddr" address).
  * port should be in native byte order (not network/big-endian).
+ *
+ * \return An initialized UDPC_ConnectionId
  */
 UDPC_ConnectionId UDPC_create_id_anyaddr(uint16_t port);
 
@@ -252,6 +269,8 @@ UDPC_ConnectionId UDPC_create_id_anyaddr(uint16_t port);
  * address is given, the internal address of the returned UDPC_ConnectionId will
  * be ipv4-mapped ipv6 address.)
  * port should be in native byte order (not network/big-endian).
+ *
+ * \return An initialized UDPC_ConnectionId
  */
 UDPC_ConnectionId UDPC_create_id_easy(const char *addrString, uint16_t port);
 
@@ -268,6 +287,8 @@ UDPC_ConnectionId UDPC_create_id_easy(const char *addrString, uint16_t port);
  * created.
  *
  * \warning The received UDPC_HContext must be freed with a call to UDPC_destroy().
+ *
+ * \return A UDPC context
  */
 UDPC_HContext UDPC_init(UDPC_ConnectionId listenId, int isClient, int isUsingLibsodium);
 /*!
@@ -286,6 +307,8 @@ UDPC_HContext UDPC_init(UDPC_ConnectionId listenId, int isClient, int isUsingLib
  * created.
  *
  * \warning The received UDPC_HContext must be freed with a call to UDPC_destroy().
+ *
+ * \return A UDPC context
  */
 UDPC_HContext UDPC_init_threaded_update(
     UDPC_ConnectionId listenId,
@@ -307,6 +330,8 @@ UDPC_HContext UDPC_init_threaded_update(
  * created.
  *
  * \warning The received UDPC_HContext must be freed with a call to UDPC_destroy().
+ *
+ * \return A UDPC context
  */
 UDPC_HContext UDPC_init_threaded_update_ms(
     UDPC_ConnectionId listenId,
@@ -436,6 +461,8 @@ void UDPC_queue_send(UDPC_HContext ctx, UDPC_ConnectionId destinationId,
  * queue holds packets for all connections this context maintains. Thus if one
  * connection has free space, then it may partially remove packets only destined
  * for that connection from the queue this function refers to.
+ *
+ * \return The size of the queue
  */
 unsigned long UDPC_get_queue_send_current_size(UDPC_HContext ctx);
 
@@ -447,6 +474,8 @@ unsigned long UDPC_get_queue_send_current_size(UDPC_HContext ctx);
  * internal queue, but must do so after locking an internal mutex (a call to
  * UDPC_update() will lock this mutex, regardless of whether or not the context
  * is using threaded update).
+ *
+ * \return The size of a connection's queue
  */
 unsigned long UDPC_get_queued_size(UDPC_HContext ctx, UDPC_ConnectionId id, int *exists);
 
@@ -455,31 +484,143 @@ unsigned long UDPC_get_queued_size(UDPC_HContext ctx, UDPC_ConnectionId id, int
  *
  * Note that a call to this function does not use any locks, as the limit is
  * known at compile time and is the same for all UDPC connections.
+ *
+ * \return The size limit of a connection's queue
  */
 unsigned long UDPC_get_max_queued_size();
 
+/*!
+ * \brief Set whether or not the UDPC context will accept new connections
+ * \param ctx The UDPC context
+ * \param isAccepting Set to non-zero to accept connections
+ * \return The previous setting (1 if accepting, 0 if not)
+ */
 int UDPC_set_accept_new_connections(UDPC_HContext ctx, int isAccepting);
 
+/*!
+ * \brief Drops an existing connection to a peer
+ *
+ * Note that UDPC will send a disconnect packet to the peer before removing
+ * the internal connection data handling the connection to that peer.
+ *
+ * \param ctx The UDPC context
+ * \param connectionId The identifier of the peer to disconnect from
+ * \param dropAllWithAddr Set to non-zero to drop all peers with the ip address
+ * specified in \p connectionId
+ */
 void UDPC_drop_connection(UDPC_HContext ctx, UDPC_ConnectionId connectionId, int dropAllWithAddr);
 
+/*!
+ * \brief Checks if a connection exists to the peer identified by the given
+ * \p connectionId
+ *
+ * \param ctx The UDPC context
+ * \param connectionId The identifier for a peer
+ *
+ * \return non-zero if a connection to the peer exists
+ */
 int UDPC_has_connection(UDPC_HContext ctx, UDPC_ConnectionId connectionId);
 
+/*!
+ * \brief Gets a dynamically allocated array of connected peers' identifiers
+ *
+ * Note that an additional element is appended to the array that is initialized
+ * with all fields to zero.
+ *
+ * \warning One must call UDPC_free_list_connected() with the returned array to
+ * clean up data to avoid a memory leak
+ *
+ * \param ctx The UDPC context
+ * \param size Pointer to an unsigned int to set the size of the returned array
+ * (set to NULL to not get a size)
+ * \return A dynamically allocated array of identifiers
+ */
 UDPC_ConnectionId* UDPC_get_list_connected(UDPC_HContext ctx, unsigned int *size);
 
+/*!
+ * \brief Cleans up a dynamically allocated array of connected peers' identifiers
+ * \param list The array to clean up
+ */
 void UDPC_free_list_connected(UDPC_ConnectionId *list);
 
+/*!
+ * \brief Gets the protocol id of the UDPC context
+ *
+ * UDPC uses the protocol id by prefixing every sent packet with it. Other UDPC
+ * instances will only accept packets with the same protocol id.
+ *
+ * One can use UDPC_set_protocol_id() to change it.
+ *
+ * \param ctx The UDPC context
+ * \return The protocol id of the given UDPC context
+ */
 uint32_t UDPC_get_protocol_id(UDPC_HContext ctx);
 
+/*!
+ * \brief Sets the protocol id of the UDPC context
+ *
+ * UDPC uses the protocol id by prefixing every sent packet with it. Other UDPC
+ * instances will only accept packets with the same protocol id.
+ *
+ * \param ctx The UDPC context
+ * \param id The new id to use as the protocol id
+ * \return The previous protocol id of the UDPC context
+ */
 uint32_t UDPC_set_protocol_id(UDPC_HContext ctx, uint32_t id);
 
+/*!
+ * \brief Gets the logging type of the UDPC context
+ *
+ * See \ref UDPC_LoggingType for possible values.
+ *
+ * \param ctx The UDPC context
+ * \return The logging type of the UDPC context
+ */
 UDPC_LoggingType UDPC_get_logging_type(UDPC_HContext ctx);
 
+/*!
+ * \brief Sets the logging type of the UDPC context
+ *
+ * See \ref UDPC_LoggingType for possible values.
+ *
+ * \param ctx The UDPC context
+ * \param loggingType The logging type to set to
+ * \return The previously set logging type
+ */
 UDPC_LoggingType UDPC_set_logging_type(UDPC_HContext ctx, UDPC_LoggingType loggingType);
 
-int UPDC_get_receiving_events(UDPC_HContext ctx);
+/*!
+ * \brief Returns non-zero if the UDPC context will record events
+ *
+ * Events that have ocurred can by polled by calling UDPC_get_event()
+ *
+ * \param ctx The UDPC context
+ * \return non-zero if receiving events
+ */
+int UDPC_get_receiving_events(UDPC_HContext ctx);
 
+/*!
+ * \brief Sets whether or not UDPC will record events
+ *
+ * Events that have ocurred can by polled by calling UDPC_get_event()
+ *
+ * \param ctx The UDPC context
+ * \param isReceivingEvents Set to non-zero to receive events
+ * \return non-zero if UDPC was previously receiving events
+ */
 int UDPC_set_receiving_events(UDPC_HContext ctx, int isReceivingEvents);
 
+/*!
+ * \brief Gets a recorded event
+ *
+ * See \ref UDPC_EventType for possible types of a UDPC_Event.
+ *
+ * \param ctx The UDPC context
+ * \param remaining Pointer to set the number of remaining events that can be
+ * returned
+ * \return An UDPC_Event (will be of type UDPC_ET_NONE if there are no more
+ * events)
+ */
 UDPC_Event UDPC_get_event(UDPC_HContext ctx, unsigned long *remaining);
 
 UDPC_PacketInfo UDPC_get_received(UDPC_HContext ctx, unsigned long *remaining);