X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Fats%2Fats.h;h=b6750da10ef74669d48cff5919d09e8fc3452935;hb=bfc6d94bd600d3048c155dc2a48c2e1faee484d0;hp=61c3bd148ad598dcacb2d5530201472e0c462152;hpb=0faae7b9f8d646f42a3a404bea9e86313cb3ec31;p=oweals%2Fgnunet.git

diff --git a/src/ats/ats.h b/src/ats/ats.h
index 61c3bd148..b6750da10 100644
--- a/src/ats/ats.h
+++ b/src/ats/ats.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2010,2011 Christian Grothoff (and other contributing authors)
+     (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
@@ -35,18 +35,36 @@
 enum StartFlag
 {
 
+  /**
+   * This is a scheduling client (aka transport service)
+   */
   START_FLAG_SCHEDULING = 0,
 
+  /**
+   * Performance monitoring client that wants to learn about
+   * changes in performance characteristics.
+   */
   START_FLAG_PERFORMANCE_WITH_PIC = 1,
 
+  /**
+   * Performance monitoring client that does NOT want to learn
+   * about changes in performance characteristics.
+   */
   START_FLAG_PERFORMANCE_NO_PIC = 2
 };
 
 
 GNUNET_NETWORK_STRUCT_BEGIN
 
+/**
+ * First message any client sends to ATS, used to self-identify
+ * (what type of client this is).
+ */
 struct ClientStartMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_START.
+   */
   struct GNUNET_MessageHeader header;
 
   /**
@@ -56,40 +74,94 @@ struct ClientStartMessage
 };
 
 
+/**
+ * Scheduling client to ATS service: we would like to have
+ * address suggestions for this peer.
+ */
 struct RequestAddressMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_REQUEST_ADDRESS or
+   * #GNUNET_MESSAGE_TYPE_ATS_REQUEST_ADDRESS_CANCEL to stop
+   * suggestions.
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   * Always zero.
+   */
   uint32_t reserved GNUNET_PACKED;
 
+  /**
+   * Peer to get address suggestions for.
+   */
   struct GNUNET_PeerIdentity peer;
 };
 
+
+/**
+ * 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;
 };
 
 
-struct AddressUpdateMessage
+/**
+ * ATS client to ATS service: here is another address you can use.
+ */
+struct AddressAddMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_ADD.
+   */
   struct GNUNET_MessageHeader header;
 
+  /**
+   * Length of the `struct GNUNET_ATS_Information` array that follows this struct.
+   */
   uint32_t ats_count GNUNET_PACKED;
 
+  /**
+   * Identity of the peer that this address is for.
+   */
   struct GNUNET_PeerIdentity peer;
 
-
+  /**
+   * Number of bytes in the address that follows this struct.
+   */
   uint16_t address_length GNUNET_PACKED;
 
+  /**
+   * Number of bytes in the plugin name that follows this struct.
+   */
   uint16_t plugin_name_length GNUNET_PACKED;
 
+  /**
+   * Internal number this client will henceforth use to
+   * refer to this address.
+   */
   uint32_t session_id GNUNET_PACKED;
 
+  /**
+   * Local-only information of the address, see
+   * `enum GNUNET_HELLO_AddressInfo`.
+   */
   uint32_t address_local_info GNUNET_PACKED;
 
   /* followed by:
@@ -100,83 +172,166 @@ struct AddressUpdateMessage
 
 };
 
-struct AddressUseMessage
+
+/**
+ * Message used to notify ATS that the performance
+ * characteristics for an address have changed.
+ */
+struct AddressUpdateMessage
 {
+  /**
+   * Message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_UPDATE.
+   */
   struct GNUNET_MessageHeader header;
 
-  struct GNUNET_PeerIdentity peer;
-
-  uint16_t in_use GNUNET_PACKED;
-
-  uint16_t address_length GNUNET_PACKED;
+  /**
+   * Length of the `struct GNUNET_ATS_Information` array that follows.
+   */
+  uint32_t ats_count GNUNET_PACKED;
 
-  uint16_t plugin_name_length 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;
 
+  /**
+   * Internal number this client uses to refer to this address.
+   */
   uint32_t session_id GNUNET_PACKED;
 
-  uint32_t address_local_info GNUNET_PACKED;
-
   /* followed by:
-   * - char address[address_length]
-   * - char plugin_name[plugin_name_length] (including '\0'-termination).
+   * - struct GNUNET_ATS_Information [ats_count];
    */
 
 };
 
 
-struct AddressDestroyedMessage
+/**
+ * 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;
 
-  uint32_t reserved GNUNET_PACKED;
+  /**
+   * 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;
 
-  uint16_t address_length GNUNET_PACKED;
+  /**
+   * #GNUNET_YES or #GNUNET_NO.
+   */
+  uint32_t in_use GNUNET_PACKED;
 
-  uint16_t plugin_name_length GNUNET_PACKED;
+};
 
-  uint32_t session_id GNUNET_PACKED;
 
-  uint32_t address_local_info GNUNET_PACKED;
+/**
+ * Message sent by ATS client to ATS service when an address
+ * was destroyed and must thus henceforth no longer be considered
+ * for scheduling.
+ */
+struct AddressDestroyedMessage
+{
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_DESTROYED.
+   */
+  struct GNUNET_MessageHeader header;
 
-  /* followed by:
-   * - char address[address_length]
-   * - char plugin_name[plugin_name_length] (including '\0'-termination).
+  /**
+   * 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;
 
 };
 
 
-struct AddressSuggestionMessage
+/**
+ * Message sent by ATS service to client to confirm that it is done
+ * using the given session ID.
+ */
+struct SessionReleaseMessage
 {
+  /**
+   * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_RELEASE.
+   */
   struct GNUNET_MessageHeader header;
 
-  uint32_t ats_count GNUNET_PACKED;
+  /**
+   * Number the client used to identify the session.
+   */
+  uint32_t session_id GNUNET_PACKED;
 
+  /**
+   * Which peer is this about? (Technically redundant, as the
+   * @e session_id should be sufficient, but may enable client
+   * to find the session faster).
+   */
   struct GNUNET_PeerIdentity peer;
+};
 
-  uint16_t address_length GNUNET_PACKED;
 
-  uint16_t plugin_name_length GNUNET_PACKED;
 
+/**
+ * ATS Service suggests to the transport service to use the address
+ * identified by the given @e session_id for the given @e peer with
+ * the given @e bandwidth_in and @e bandwidth_out limits from now on.
+ */
+struct AddressSuggestionMessage
+{
+  /**
+   * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
+   */
+  struct GNUNET_MessageHeader header;
+
+  /**
+   * Internal number this client uses to refer to the address this
+   * suggestion is about.
+   */
   uint32_t session_id GNUNET_PACKED;
 
-  uint32_t address_local_info GNUNET_PACKED;
+  /**
+   * Which peer is this about? (Technically redundant, as the
+   * @e session_id should be sufficient, but may enable client
+   * to find the session faster and/or check consistency).
+   */
+  struct GNUNET_PeerIdentity peer;
 
+  /**
+   * How much bandwidth we are allowed for sending.
+   */
   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 
-  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
-
-  /* followed by:
-   * - struct GNUNET_ATS_Information [ats_count];
-   * - char address[address_length]
-   * - char plugin_name[plugin_name_length] (including '\0'-termination).
+  /**
+   * How much bandwidth we are allowed for receiving.
    */
+  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 
 };
 
 
+
+
 struct PeerInformationMessage
 {
   struct GNUNET_MessageHeader header;
@@ -245,19 +400,6 @@ struct ReservationRequestMessage
 };
 
 
-/**
- * Message sent by ATS service to client to confirm that it is done
- * using the given session ID.
- */
-struct SessionReleaseMessage
-{
-  struct GNUNET_MessageHeader header;
-
-  uint32_t session_id GNUNET_PACKED;
-
-  struct GNUNET_PeerIdentity peer;
-};
-
 
 struct ReservationResultMessage
 {