fixing core API issues

3 files changed, 94 insertions, 26 deletions

diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h
index 94656b916..cffdf0a14 100644
--- a/src/include/gnunet_core_service.h
+++ b/src/include/gnunet_core_service.h
@@ -138,6 +138,7 @@ typedef void
  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
  * @param init callback to call on timeout or once we have successfully
  *        connected to the core service; note that timeout is only meaningful if init is not NULL
+ * @param pre_connects function to call on peer pre-connect (no session key yet), can be NULL
  * @param connects function to call on peer connect, can be NULL
  * @param disconnects function to call on peer disconnect / timeout, can be NULL
  * @param inbound_notify function to call for all inbound messages, can be NULL
@@ -158,6 +159,7 @@ GNUNET_CORE_connect (struct GNUNET_SCHEDULER_Handle *sched,
                      struct GNUNET_TIME_Relative timeout,
                      void *cls,
                      GNUNET_CORE_StartupCallback init,
+                     GNUNET_CORE_ClientEventHandler pre_connects,
                      GNUNET_CORE_ClientEventHandler connects,
                      GNUNET_CORE_ClientEventHandler disconnects,
                      GNUNET_CORE_MessageCallback inbound_notify,
@@ -175,27 +177,77 @@ GNUNET_CORE_connect (struct GNUNET_SCHEDULER_Handle *sched,
 void GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 
 
-// FIXME
+/**
+ * Handle for a request to the core to connect or disconnect
+ * from a particular peer.  Can be used to cancel the request
+ * (before the 'cont'inuation is called).
+ */
 struct GNUNET_CORE_PeerRequestHandle;
 
-// FIXME
+
+/**
+ * Request that the core should try to connect to a particular peer.
+ * Once the request has been transmitted to the core, the continuation
+ * function will be called.  Note that this does NOT mean that a
+ * connection was successfully established -- it only means that the
+ * core will now try.  Successful establishment of the connection
+ * will be signalled to the 'connects' callback argument of
+ * 'GNUNET_CORE_connect' only.  If the core service does not respond
+ * to our connection attempt within the given time frame, 'cont' will
+ * be called with the TIMEOUT reason code.
+ *
+ * @param sched scheduler to use
+ * @param cfg configuration to use
+ * @param timeout how long to try to talk to core
+ * @param cont function to call once the request has been completed (or timed out)
+ * @param cont_cls closure for cont
+ * @return NULL on error (cont will not be called), otherwise handle for cancellation
+ */
 struct GNUNET_CORE_PeerRequestHandle *
 GNUNET_CORE_peer_request_connect (struct GNUNET_SCHEDULER_Handle *sched,
-                                         const struct GNUNET_CONFIGURATION_Handle *cfg,
-                                         const struct GNUNET_PeerIdentity * peer,
-                                         GNUNET_SCHEDULER_Task cont,
-                                         void *cont_cls);
+                                  const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                  struct GNUNET_TIME_Relative timeout,
+                                  const struct GNUNET_PeerIdentity * peer,
+                                  GNUNET_SCHEDULER_Task cont,
+                                  void *cont_cls);
 
 
-// FIXME
+/**
+ * Request that the core should try to disconnect from a particular
+ * peer.  Once the request has been transmitted to the core, the
+ * continuation function will be called.  Note that this does NOT mean
+ * that a connection was successfully cut -- it only means that the
+ * core will now try.  Typically this will work pretty much
+ * immediately, but it is at least in theory also possible that a
+ * reconnect is also triggered rather quickly.  Successful creation
+ * and destruction of connections will be signalled to the 'connects'
+ * and 'disconnects' callback arguments of 'GNUNET_CORE_connect' only.
+ * If the core service does not respond to our connection attempt
+ * within the given time frame, 'cont' will be called with the TIMEOUT
+ * reason code.
+ *
+ * @param sched scheduler to use
+ * @param cfg configuration to use
+ * @param timeout how long to try to talk to core
+ * @param cont function to call once the request has been completed (or timed out)
+ * @param cont_cls closure for cont
+ * @return NULL on error (cont will not be called), otherwise handle for cancellation
+ */
 struct GNUNET_CORE_PeerRequestHandle *
 GNUNET_CORE_peer_request_disconnect (struct GNUNET_SCHEDULER_Handle *sched,
-                                            const struct GNUNET_CONFIGURATION_Handle *cfg,
-                                            const struct GNUNET_PeerIdentity * peer,
-                                            GNUNET_SCHEDULER_Task cont,
-                                            void *cont_cls);
+                                     const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                     struct GNUNET_TIME_Relative timeout,
+                                     const struct GNUNET_PeerIdentity * peer,
+                                     GNUNET_SCHEDULER_Task cont,
+                                     void *cont_cls);
 
-// FIXME
+
+/**
+ * Cancel a pending request to connect or disconnect from/to a particular
+ * peer.   Must not be called after the 'cont' function was invoked.
+ *
+ * @param req request handle that was returned for the original request
+ */
 void
 GNUNET_CORE_peer_request_cancel (struct GNUNET_CORE_PeerRequestHandle *req);
 
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index cdf5d0df3..28535587d 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -263,40 +263,57 @@ extern "C"
 #define GNUNET_MESSAGE_TYPE_CORE_INIT_REPLY 65
 
 /**
- * Notify clients about new peer-to-peer connections.
+ * Notify clients about new peer-to-peer connections (before
+ * key exchange and authentication).
  */
-#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_CONNECT 66
+#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_PRE_CONNECT 66
+
+/**
+ * Notify clients about new peer-to-peer connections (triggered
+ * after key exchange).
+ */
+#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_CONNECT 67
 
 /**
  * Notify clients about peer disconnecting.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_DISCONNECT 67
+#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_DISCONNECT 68
 
 /**
  * Notify clients about incoming P2P messages.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_INBOUND 68
+#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_INBOUND 69
 
 /**
  * Notify clients about outgoing P2P transmissions.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND 69
+#define GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND 70
 
 /**
  * Request from client to "configure" P2P connection.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_REQUEST_INFO 70
+#define GNUNET_MESSAGE_TYPE_CORE_REQUEST_INFO 71
 
 /**
  * Response from server about (possibly updated) P2P
  * connection configuration.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_CONFIGURATION_INFO 71
+#define GNUNET_MESSAGE_TYPE_CORE_CONFIGURATION_INFO 72
 
 /**
  * Request from client with message to transmit.
  */
-#define GNUNET_MESSAGE_TYPE_CORE_SEND 72
+#define GNUNET_MESSAGE_TYPE_CORE_SEND 73
+
+/**
+ * Request from client asking to connect to a peer.
+ */
+#define GNUNET_MESSAGE_TYPE_CORE_REQUEST_CONNECT 74
+
+/**
+ * Request from client asking to disconnect from a peer.
+ */
+#define GNUNET_MESSAGE_TYPE_CORE_REQUEST_DISCONNECT 75
 
 
 /**
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index 726e03a95..344de582f 100644
--- a/src/include/gnunet_transport_service.h
+++ b/src/include/gnunet_transport_service.h
@@ -138,10 +138,8 @@ void GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
  *
  * @param handle connection to transport service
  * @param target who's bandwidth quota is being changed
- * @param quota_in incoming bandwidth quota in bytes per ms; 0 can
- *        be used to force all traffic to be discarded
- * @param quota_out outgoing bandwidth quota in bytes per ms; 0 can
- *        be used to force all traffic to be discarded
+ * @param quota_in incoming bandwidth quota in bytes per ms
+ * @param quota_out outgoing bandwidth quota in bytes per ms
  * @param timeout how long to wait until signaling failure if
  *        we can not communicate the quota change
  * @param cont continuation to call when done, will be called
@@ -195,8 +193,9 @@ struct GNUNET_TRANSPORT_TransmitHandle
 
 
 /**
- * Cancel the specified transmission-ready
- * notification.
+ * Cancel the specified transmission-ready notification.
+ *
+ * @param h handle of the transmission notification request to cancel
  */
 void
 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct