cleaning up gnunet-service-ats_preferences.c

[oweals/gnunet.git] / src / ats / ats.h

diff --git a/src/ats/ats.h b/src/ats/ats.h
index b6750da10ef74669d48cff5919d09e8fc3452935..d5d5d6c3f97e3a2d04b0f732f4b34454ec97d3e4 100644 (file)
--- a/src/ats/ats.h
+++ b/src/ats/ats.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2010-2015 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2010-2015 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -50,7 +50,12 @@ enum StartFlag
    * Performance monitoring client that does NOT want to learn
    * about changes in performance characteristics.
    */
-  START_FLAG_PERFORMANCE_NO_PIC = 2
+  START_FLAG_PERFORMANCE_NO_PIC = 2,
+
+  /**
+   * Connection suggestion handle.
+   */
+  START_FLAG_CONNECTION_SUGGESTION = 3
 };
 
 
@@ -99,29 +104,6 @@ struct RequestAddressMessage
 };
 
 
-/**
- * Scheduling client to ATS service: reset backoff for
- * address suggestions to this peer.
- */
-struct ResetBackoffMessage
-{
-  /**
-   * Type is #GNUNET_MESSAGE_TYPE_ATS_RESET_BACKOFF.
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * Always zero.
-   */
-  uint32_t reserved GNUNET_PACKED;
-
-  /**
-   * Peer to reset backoff for.
-   */
-  struct GNUNET_PeerIdentity peer;
-};
-
-
 /**
  * ATS client to ATS service: here is another address you can use.
  */
@@ -208,37 +190,6 @@ struct AddressUpdateMessage
 };
 
 
-/**
- * Message sent from ATS client to ATS service to notify
- * it if we started (or stopped) using an address.
- */
-struct AddressUseMessage
-{
-  /**
-   * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_IN_USE.
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * Internal number this client uses to refer to this address.
-   */
-  uint32_t session_id GNUNET_PACKED;
-
-  /**
-   * Which peer is this about? (Technically redundant, as the
-   * @e session_id should be sufficient, but enables ATS service
-   * to find the session faster).
-   */
-  struct GNUNET_PeerIdentity peer;
-
-  /**
-   * #GNUNET_YES or #GNUNET_NO.
-   */
-  uint32_t in_use GNUNET_PACKED;
-
-};
-
-
 /**
  * Message sent by ATS client to ATS service when an address
  * was destroyed and must thus henceforth no longer be considered
@@ -330,26 +281,54 @@ struct AddressSuggestionMessage
 };
 
 
-
-
+/**
+ *
+ */
 struct PeerInformationMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_PEER_INFORMATION
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   *
+   */
   uint32_t ats_count GNUNET_PACKED;
 
+  /**
+   *
+   */
   uint32_t address_active GNUNET_PACKED;
 
+  /**
+   *
+   */
   uint32_t id GNUNET_PACKED;
 
+  /**
+   *
+   */
   struct GNUNET_PeerIdentity peer;
 
+  /**
+   *
+   */
   uint16_t address_length GNUNET_PACKED;
 
+  /**
+   *
+   */
   uint16_t plugin_name_length GNUNET_PACKED;
 
+  /**
+   *
+   */
   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 
+  /**
+   *
+   */
   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 
   /* followed by:
@@ -390,44 +369,95 @@ struct AddressListRequestMessage
 };
 
 
+/**
+ *
+ */
 struct ReservationRequestMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_REQUEST
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   *
+   */
   int32_t amount GNUNET_PACKED;
 
+  /**
+   *
+   */
   struct GNUNET_PeerIdentity peer;
 };
 
 
-
+/**
+ *
+ */
 struct ReservationResultMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_RESULT
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   *
+   */
   int32_t amount GNUNET_PACKED;
 
+  /**
+   *
+   */
   struct GNUNET_PeerIdentity peer;
 
+  /**
+   *
+   */
   struct GNUNET_TIME_RelativeNBO res_delay;
 };
 
+
+/**
+ * Variable-size entry in a `struct ChangePreferenceMessage` or
+ * `struct FeedbackPreferenceMessage`.
+ */
 struct PreferenceInformation
 {
 
+  /**
+   * An `enum GNUNET_ATS_PreferenceKind` in NBO.
+   */
   uint32_t preference_kind GNUNET_PACKED;
 
+  /**
+   * Degree of preference (or appreciation) for this @e
+   * preference_kind being expressed.
+   */
   float preference_value GNUNET_PACKED;
 
 };
 
 
+/**
+ * Client to ATS: I have a performance preference for a peer.
+ */
 struct ChangePreferenceMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_CHANGE.
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   * How many `struct PreferenceInformation` entries follow
+   * this struct?
+   */
   uint32_t num_preferences GNUNET_PACKED;
 
+  /**
+   * Which peer is the preference being expressed for?
+   */
   struct GNUNET_PeerIdentity peer;
 
   /* followed by 'num_preferences'
@@ -440,6 +470,9 @@ struct ChangePreferenceMessage
  */
 struct FeedbackPreferenceMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_FEEDBACK.
+   */
   struct GNUNET_MessageHeader header;
 
   /**