1 files changed, 323 insertions, 0 deletions
diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h
new file mode 100644
index 000000000..8b75271b9
--- /dev/null
+++ b/src/include/gnunet_core_service.h
@@ -0,0 +1,323 @@
+/*
+     This file is part of GNUnet.
+     (C) 2009 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
+     by the Free Software Foundation; either version 2, or (at your
+     option) any later version.
+     GNUnet is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+/**
+ * @file include/gnunet_core_service.h
+ * @brief core service; this is the main API for encrypted P2P
+ *        communications
+ * @author Christian Grothoff
+ */
+#ifndef GNUNET_CORE_SERVICE_H
+#define GNUNET_CORE_SERVICE_H
+#ifdef __cplusplus
+extern "C"
+{
+#if 0                           /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+#include "gnunet_util_lib.h"
+/**
+ * Version number of GNUnet-core API.
+ */
+#define GNUNET_CORE_VERSION 0x00000000
+/**
+ * Opaque handle to the service.
+ */
+struct GNUNET_CORE_Handle;
+/**
+ * Method called whenever a given peer either connects or
+ * disconnects (or list of connections was requested).
+ *
+ * @param cls closure
+ * @param peer peer identity this notification is about
+ * @param bpm how much bandwidth is available
+ *            (for sending) to this peer
+ * @param last_activity when did we last
+ *            receive anything from this peer?
+ */
+typedef void (*GNUNET_CORE_ClientEventHandler) (void *cls,
+                                                const struct
+                                                GNUNET_PeerIdentity * peer,
+                                                unsigned int bpm,
+                                                struct GNUNET_TIME_Absolute
+                                                last_activity);
+/**
+ * Type of a send callback to fill up buffers.
+ *
+ * @param receiver the receiver of the message
+ * @param position is the reference to the
+ *        first unused position in the buffer where GNUnet is building
+ *        the message
+ * @param padding is the number of bytes left in that buffer.
+ * @return the number of bytes written to
+ *   that buffer (must be a positive number).
+ */
+typedef unsigned int
+  (*GNUNET_CORE_BufferFillCallback) (void *cls,
+                                     const struct GNUNET_PeerIdentity *
+                                     receiver,
+                                     void *position, unsigned int padding);
+/**
+ * Functions with this signature are called whenever a message is
+ * received or transmitted.
+ *
+ * @param cls closure
+ * @param peer the other peer involved (sender or receiver, NULL
+ *        for loopback messages where we are both sender and receiver)
+ * @param message the actual message
+ * @return GNUNET_OK to keep the connection open,
+ *         GNUNET_SYSERR to close it (signal serious error)
+ */
+typedef int
+  (*GNUNET_CORE_MessageCallback) (void *cls,
+                                  const struct GNUNET_PeerIdentity * other,
+                                  const struct GNUNET_MessageHeader *
+                                  message);
+/**
+ * Message handler.  Each struct specifies how to handle on particular
+ * type of message received.
+ */
+struct GNUNET_CORE_MessageHandler
+{
+  /**
+   * Function to call for messages of "type".
+   */
+  GNUNET_CORE_MessageCallback callback;
+  /**
+   * Type of the message this handler covers.
+   */
+  uint16_t type;
+  /**
+   * Expected size of messages of this type.  Use 0 for variable-size.
+   * If non-zero, messages of the given type will be discarded if they
+   * do not have the right size.
+   */
+  uint16_t expected_size;
+};
+/**
+ * Function called after GNUNET_CORE_connect has succeeded
+ * (or failed for good).  Note that the private key of the
+ * peer is intentionally not exposed here; if you need it,
+ * your process should try to read the private key file
+ * directly (which should work if you are authorized...).
+ *
+ * @param cls closure
+ * @param server handle to the server, NULL if we failed
+ * @param my_identity ID of this peer, NULL if we failed
+ * @param publicKey public key of this peer, NULL if we failed
+ */
+typedef void
+  (*GNUNET_CORE_StartupCallback) (void *cls,
+                                  struct GNUNET_CORE_Handle * server,
+                                  const struct GNUNET_PeerIdentity *
+                                  my_identity,
+                                  const struct
+                                  GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *
+                                  publicKey);
+/**
+ * Connect to the core service.  Note that the connection may
+ * complete (or fail) asynchronously.
+ *
+ * @param sched scheduler to use
+ * @param cfg configuration to use
+ * @param timeout after how long should we give up trying to connect to the core service?
+ * @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
+ * @param connects function to call on peer connect, can be NULL
+ * @param disconnects function to call on peer disconnect / timeout, can be NULL
+ * @param bfc function to call to fill up spare bandwidth, can be NULL
+ * @param inbound_notify function to call for all inbound messages, can be NULL
+ * @param inbound_hdr_only set to GNUNET_YES if inbound_notify will only read the
+ *                GNUNET_MessageHeader and hence we do not need to give it the full message;
+ *                can be used to improve efficiency, ignored if inbound_notify is NULLL
+ * @param outbound_notify function to call for all outbound messages, can be NULL
+ * @param outbound_hdr_only set to GNUNET_YES if outbound_notify will only read the
+ *                GNUNET_MessageHeader and hence we do not need to give it the full message
+ *                can be used to improve efficiency, ignored if outbound_notify is NULLL
+ * @param handlers callbacks for messages we care about, NULL-terminated
+ */
+void
+GNUNET_CORE_connect (struct GNUNET_SCHEDULER_Handle *sched,
+                     struct GNUNET_CONFIGURATION_Handle *cfg,
+                     struct GNUNET_TIME_Relative timeout,
+                     void *cls,
+                     GNUNET_CORE_StartupCallback init,
+                     GNUNET_CORE_ClientEventHandler connects,
+                     GNUNET_CORE_ClientEventHandler disconnects,
+                     GNUNET_CORE_BufferFillCallback bfc,
+                     GNUNET_CORE_MessageCallback inbound_notify,
+                     int inbound_hdr_only,
+                     GNUNET_CORE_MessageCallback outbound_notify,
+                     int outbound_hdr_only,
+                     const struct GNUNET_CORE_MessageHandler *handlers);
+/**
+ * Disconnect from the core service.
+ *
+ * @param handle connection to core to disconnect
+ */
+void GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
+/**
+ * Function called with statistics about the given peer.
+ *
+ * @param peer identifies the peer
+ * @param latency current latency estimate, "FOREVER" if we have been
+ *                disconnected
+ * @param bpm_in set to the current bandwidth limit (receiving) for this peer
+ * @param bpm_out set to the current bandwidth limit (sending) for this peer
+ * @param amount set to the amount that was actually reserved or unreserved
+ * @param preference current traffic preference for the given peer
+ */
+typedef void
+  (*GNUNET_CORE_PeerConfigurationInfoCallback) (void *cls,
+                                                const struct
+                                                GNUNET_PeerIdentity * peer,
+                                                unsigned int bpm_in,
+                                                unsigned int bpm_out,
+                                                struct GNUNET_TIME_Relative
+                                                latency, int amount,
+                                                double preference);
+/**
+ * Obtain statistics and/or change preferences for the given peer.
+ *
+ * @param handle connection to core to use
+ * @param peer identifies the peer
+ * @param timeout after how long should we give up (and call "info" with NULL
+ *                for "peer" to signal an error)?
+ * @param bpm_out set to the current bandwidth limit (sending) for this peer,
+ *                caller should set "bpm_out" to "-1" to avoid changing
+ *                the current value; otherwise "bpm_out" will be lowered to
+ *                the specified value; passing a pointer to "0" can be used to force
+ *                us to disconnect from the peer; "bpm_out" might not increase
+ *                as specified since the upper bound is generally
+ *                determined by the other peer!
+ * @param amount reserve N bytes for receiving, negative
+ *                amounts can be used to undo a (recent) reservation;
+ * @param preference increase incoming traffic share preference by this amount;
+ *                in the absence of "amount" reservations, we use this
+ *                preference value to assign proportional bandwidth shares
+ *                to all connected peers
+ * @param info function to call with the resulting configuration information
+ * @param info_cls closure for info
+ */
+void
+GNUNET_CORE_peer_configure (struct GNUNET_CORE_Handle *handle,
+                            const struct GNUNET_PeerIdentity *peer,
+                            struct GNUNET_TIME_Relative timeout,
+                            unsigned int bpm_out,
+                            int amount,
+                            double preference,
+                            GNUNET_CORE_PeerConfigurationInfoCallback info,
+                            void *info_cls);
+/**
+ * Handle for a transmission request.
+ */
+struct GNUNET_CORE_TransmitHandle;
+/**
+ * Ask the core to call "notify" once it is ready to transmit the
+ * given number of bytes to the specified "target".  If we are not yet
+ * connected to the specified peer, a call to this function will cause
+ * us to try to establish a connection.
+ *
+ * @param handle connection to core service
+ * @param priority how important is the message?
+ * @param maxdelay how long can the message wait?
+ * @param target who should receive the message,
+ *        use NULL for this peer (loopback)
+ * @param notify_size how many bytes of buffer space does notify want?
+ * @param notify function to call when buffer space is available
+ * @param notify_cls closure for notify
+ * @return non-NULL if the notify callback was queued,
+ *         NULL if we can not even queue the request (insufficient
+ *         memory); if NULL is returned, "notify" will NOT be called.
+ */
+struct GNUNET_CORE_TransmitHandle *GNUNET_CORE_notify_transmit_ready (struct
+                                                                      GNUNET_CORE_Handle
+                                                                      *handle,
+                                                                      unsigned
+                                                                      int
+                                                                      priority,
+                                                                      struct
+                                                                      GNUNET_TIME_Relative
+                                                                      maxdelay,
+                                                                      const
+                                                                      struct
+                                                                      GNUNET_PeerIdentity
+                                                                      *target,
+                                                                      size_t
+                                                                      notify_size,
+                                                                      GNUNET_NETWORK_TransmitReadyNotify
+                                                                      notify,
+                                                                      void
+                                                                      *notify_cls);
+/**
+ * Cancel the specified transmission-ready notification.
+ *
+ * @param h handle that was returned by "notify_transmit_ready".
+ */
+void
+GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle
+                                          *h);
+#if 0                           /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
+/* ifndef GNUNET_CORE_SERVICE_H */
+#endif
+/* end of gnunet_core_service.h */

diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h new file mode 100644 index 000000000..8b75271b9 --- /dev/null +++ b/src/include/gnunet_core_service.h
@@ -0,0 +1,323 @@
	1	/*
	2	This file is part of GNUnet.
	3	(C) 2009 Christian Grothoff (and other contributing authors)
	4
	5	GNUnet is free software; you can redistribute it and/or modify
	6	it under the terms of the GNU General Public License as published
	7	by the Free Software Foundation; either version 2, or (at your
	8	option) any later version.
	9
	10	GNUnet is distributed in the hope that it will be useful, but
	11	WITHOUT ANY WARRANTY; without even the implied warranty of
	12	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	13	General Public License for more details.
	14
	15	You should have received a copy of the GNU General Public License
	16	along with GNUnet; see the file COPYING. If not, write to the
	17	Free Software Foundation, Inc., 59 Temple Place - Suite 330,
	18	Boston, MA 02111-1307, USA.
	19	*/
	20
	21	/**
	22	* @file include/gnunet_core_service.h
	23	* @brief core service; this is the main API for encrypted P2P
	24	* communications
	25	* @author Christian Grothoff
	26	*/
	27
	28	#ifndef GNUNET_CORE_SERVICE_H
	29	#define GNUNET_CORE_SERVICE_H
	30
	31	#ifdef __cplusplus
	32	extern "C"
	33	{
	34	#if 0 /* keep Emacsens' auto-indent happy */
	35	}
	36	#endif
	37	#endif
	38
	39	#include "gnunet_util_lib.h"
	40
	41	/**
	42	* Version number of GNUnet-core API.
	43	*/
	44	#define GNUNET_CORE_VERSION 0x00000000
	45
	46
	47	/**
	48	* Opaque handle to the service.
	49	*/
	50	struct GNUNET_CORE_Handle;
	51
	52
	53	/**
	54	* Method called whenever a given peer either connects or
	55	* disconnects (or list of connections was requested).
	56	*
	57	* @param cls closure
	58	* @param peer peer identity this notification is about
	59	* @param bpm how much bandwidth is available
	60	* (for sending) to this peer
	61	* @param last_activity when did we last
	62	* receive anything from this peer?
	63	*/
	64	typedef void (GNUNET_CORE_ClientEventHandler) (void cls,
	65	const struct
	66	GNUNET_PeerIdentity * peer,
	67	unsigned int bpm,
	68	struct GNUNET_TIME_Absolute
	69	last_activity);
	70
	71
	72	/**
	73	* Type of a send callback to fill up buffers.
	74	*
	75	* @param receiver the receiver of the message
	76	* @param position is the reference to the
	77	* first unused position in the buffer where GNUnet is building
	78	* the message
	79	* @param padding is the number of bytes left in that buffer.
	80	* @return the number of bytes written to
	81	* that buffer (must be a positive number).
	82	*/
	83	typedef unsigned int
	84	(GNUNET_CORE_BufferFillCallback) (void cls,
	85	const struct GNUNET_PeerIdentity *
	86	receiver,
	87	void *position, unsigned int padding);
	88
	89
	90	/**
	91	* Functions with this signature are called whenever a message is
	92	* received or transmitted.
	93	*
	94	* @param cls closure
	95	* @param peer the other peer involved (sender or receiver, NULL
	96	* for loopback messages where we are both sender and receiver)
	97	* @param message the actual message
	98	* @return GNUNET_OK to keep the connection open,
	99	* GNUNET_SYSERR to close it (signal serious error)
	100	*/
	101	typedef int
	102	(GNUNET_CORE_MessageCallback) (void cls,
	103	const struct GNUNET_PeerIdentity * other,
	104	const struct GNUNET_MessageHeader *
	105	message);
	106
	107
	108	/**
	109	* Message handler. Each struct specifies how to handle on particular
	110	* type of message received.
	111	*/
	112	struct GNUNET_CORE_MessageHandler
	113	{
	114	/**
	115	* Function to call for messages of "type".
	116	*/
	117	GNUNET_CORE_MessageCallback callback;
	118
	119	/**
	120	* Type of the message this handler covers.
	121	*/
	122	uint16_t type;
	123
	124	/**
	125	* Expected size of messages of this type. Use 0 for variable-size.
	126	* If non-zero, messages of the given type will be discarded if they
	127	* do not have the right size.
	128	*/
	129	uint16_t expected_size;
	130
	131	};
	132
	133
	134	/**
	135	* Function called after GNUNET_CORE_connect has succeeded
	136	* (or failed for good). Note that the private key of the
	137	* peer is intentionally not exposed here; if you need it,
	138	* your process should try to read the private key file
	139	* directly (which should work if you are authorized...).
	140	*
	141	* @param cls closure
	142	* @param server handle to the server, NULL if we failed
	143	* @param my_identity ID of this peer, NULL if we failed
	144	* @param publicKey public key of this peer, NULL if we failed
	145	*/
	146	typedef void
	147	(GNUNET_CORE_StartupCallback) (void cls,
	148	struct GNUNET_CORE_Handle * server,
	149	const struct GNUNET_PeerIdentity *
	150	my_identity,
	151	const struct
	152	GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *
	153	publicKey);
	154
	155
	156	/**
	157	* Connect to the core service. Note that the connection may
	158	* complete (or fail) asynchronously.
	159	*
	160	* @param sched scheduler to use
	161	* @param cfg configuration to use
	162	* @param timeout after how long should we give up trying to connect to the core service?
	163	* @param cls closure for the various callbacks that follow (including handlers in the handlers array)
	164	* @param init callback to call on timeout or once we have successfully
	165	* connected to the core service
	166	* @param connects function to call on peer connect, can be NULL
	167	* @param disconnects function to call on peer disconnect / timeout, can be NULL
	168	* @param bfc function to call to fill up spare bandwidth, can be NULL
	169	* @param inbound_notify function to call for all inbound messages, can be NULL
	170	* @param inbound_hdr_only set to GNUNET_YES if inbound_notify will only read the
	171	* GNUNET_MessageHeader and hence we do not need to give it the full message;
	172	* can be used to improve efficiency, ignored if inbound_notify is NULLL
	173	* @param outbound_notify function to call for all outbound messages, can be NULL
	174	* @param outbound_hdr_only set to GNUNET_YES if outbound_notify will only read the
	175	* GNUNET_MessageHeader and hence we do not need to give it the full message
	176	* can be used to improve efficiency, ignored if outbound_notify is NULLL
	177	* @param handlers callbacks for messages we care about, NULL-terminated
	178	*/
	179	void
	180	GNUNET_CORE_connect (struct GNUNET_SCHEDULER_Handle *sched,
	181	struct GNUNET_CONFIGURATION_Handle *cfg,
	182	struct GNUNET_TIME_Relative timeout,
	183	void *cls,
	184	GNUNET_CORE_StartupCallback init,
	185	GNUNET_CORE_ClientEventHandler connects,
	186	GNUNET_CORE_ClientEventHandler disconnects,
	187	GNUNET_CORE_BufferFillCallback bfc,
	188	GNUNET_CORE_MessageCallback inbound_notify,
	189	int inbound_hdr_only,
	190	GNUNET_CORE_MessageCallback outbound_notify,
	191	int outbound_hdr_only,
	192	const struct GNUNET_CORE_MessageHandler *handlers);
	193
	194
	195	/**
	196	* Disconnect from the core service.
	197	*
	198	* @param handle connection to core to disconnect
	199	*/
	200	void GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
	201
	202
	203	/**
	204	* Function called with statistics about the given peer.
	205	*
	206	* @param peer identifies the peer
	207	* @param latency current latency estimate, "FOREVER" if we have been
	208	* disconnected
	209	* @param bpm_in set to the current bandwidth limit (receiving) for this peer
	210	* @param bpm_out set to the current bandwidth limit (sending) for this peer
	211	* @param amount set to the amount that was actually reserved or unreserved
	212	* @param preference current traffic preference for the given peer
	213	*/
	214	typedef void
	215	(GNUNET_CORE_PeerConfigurationInfoCallback) (void cls,
	216	const struct
	217	GNUNET_PeerIdentity * peer,
	218	unsigned int bpm_in,
	219	unsigned int bpm_out,
	220	struct GNUNET_TIME_Relative
	221	latency, int amount,
	222	double preference);
	223
	224
	225	/**
	226	* Obtain statistics and/or change preferences for the given peer.
	227	*
	228	* @param handle connection to core to use
	229	* @param peer identifies the peer
	230	* @param timeout after how long should we give up (and call "info" with NULL
	231	* for "peer" to signal an error)?
	232	* @param bpm_out set to the current bandwidth limit (sending) for this peer,
	233	* caller should set "bpm_out" to "-1" to avoid changing
	234	* the current value; otherwise "bpm_out" will be lowered to
	235	* the specified value; passing a pointer to "0" can be used to force
	236	* us to disconnect from the peer; "bpm_out" might not increase
	237	* as specified since the upper bound is generally
	238	* determined by the other peer!
	239	* @param amount reserve N bytes for receiving, negative
	240	* amounts can be used to undo a (recent) reservation;
	241	* @param preference increase incoming traffic share preference by this amount;
	242	* in the absence of "amount" reservations, we use this
	243	* preference value to assign proportional bandwidth shares
	244	* to all connected peers
	245	* @param info function to call with the resulting configuration information
	246	* @param info_cls closure for info
	247	*/
	248	void
	249	GNUNET_CORE_peer_configure (struct GNUNET_CORE_Handle *handle,
	250	const struct GNUNET_PeerIdentity *peer,
	251	struct GNUNET_TIME_Relative timeout,
	252	unsigned int bpm_out,
	253	int amount,
	254	double preference,
	255	GNUNET_CORE_PeerConfigurationInfoCallback info,
	256	void *info_cls);
	257
	258
	259	/**
	260	* Handle for a transmission request.
	261	*/
	262	struct GNUNET_CORE_TransmitHandle;
	263
	264
	265	/**
	266	* Ask the core to call "notify" once it is ready to transmit the
	267	* given number of bytes to the specified "target". If we are not yet
	268	* connected to the specified peer, a call to this function will cause
	269	* us to try to establish a connection.
	270	*
	271	* @param handle connection to core service
	272	* @param priority how important is the message?
	273	* @param maxdelay how long can the message wait?
	274	* @param target who should receive the message,
	275	* use NULL for this peer (loopback)
	276	* @param notify_size how many bytes of buffer space does notify want?
	277	* @param notify function to call when buffer space is available
	278	* @param notify_cls closure for notify
	279	* @return non-NULL if the notify callback was queued,
	280	* NULL if we can not even queue the request (insufficient
	281	* memory); if NULL is returned, "notify" will NOT be called.
	282	*/
	283	struct GNUNET_CORE_TransmitHandle *GNUNET_CORE_notify_transmit_ready (struct
	284	GNUNET_CORE_Handle
	285	*handle,
	286	unsigned
	287	int
	288	priority,
	289	struct
	290	GNUNET_TIME_Relative
	291	maxdelay,
	292	const
	293	struct
	294	GNUNET_PeerIdentity
	295	*target,
	296	size_t
	297	notify_size,
	298	GNUNET_NETWORK_TransmitReadyNotify
	299	notify,
	300	void
	301	*notify_cls);
	302
	303
	304	/**
	305	* Cancel the specified transmission-ready notification.
	306	*
	307	* @param h handle that was returned by "notify_transmit_ready".
	308	*/
	309	void
	310	GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle
	311	*h);
	312
	313
	314	#if 0 /* keep Emacsens' auto-indent happy */
	315	{
	316	#endif
	317	#ifdef __cplusplus
	318	}
	319	#endif
	320
	321	/* ifndef GNUNET_CORE_SERVICE_H */
	322	#endif
	323	/* end of gnunet_core_service.h */