aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2018-10-18 16:43:40 +0200
committerChristian Grothoff <christian@grothoff.org>2018-10-18 16:43:40 +0200
commitd66b89ea37c9885f3ea8c42a6735b2c805c00618 (patch)
tree243f7cf63f129127bbf6e72a208a5871c2a5e177 /src
parente6c64fc035500bc098777e7687dc3da5b2aac35c (diff)
downloadgnunet-d66b89ea37c9885f3ea8c42a6735b2c805c00618.tar.gz
gnunet-d66b89ea37c9885f3ea8c42a6735b2c805c00618.zip
revise communicator API
Diffstat (limited to 'src')
-rw-r--r--src/include/gnunet_transport_communication_service.h53
1 files changed, 31 insertions, 22 deletions
diff --git a/src/include/gnunet_transport_communication_service.h b/src/include/gnunet_transport_communication_service.h
index 62822ddc3..94d15af22 100644
--- a/src/include/gnunet_transport_communication_service.h
+++ b/src/include/gnunet_transport_communication_service.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet. 2 This file is part of GNUnet.
3 Copyright (C) 2009-2016 GNUnet e.V. 3 Copyright (C) 2009-2018 GNUnet e.V.
4 4
5 GNUnet is free software: you can redistribute it and/or modify it 5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published 6 under the terms of the GNU Affero General Public License as published
@@ -52,15 +52,21 @@ extern "C"
52/** 52/**
53 * Function called by the transport service to initialize a 53 * Function called by the transport service to initialize a
54 * message queue given address information about another peer. 54 * message queue given address information about another peer.
55 * If and when the communication channel is established, the
56 * communicator must call #GNUNET_TRANSPORT_communicator_mq_add()
57 * to notify the service that the channel is now up. It is
58 * the responsibility of the communicator to manage sane
59 * retries and timeouts for any @a peer/@a address combination
60 * provided by the transport service. Timeouts and retries
61 * do not need to be signalled to the transport service.
55 * 62 *
56 * @param cls closure 63 * @param cls closure
57 * @param peer identity of the other peer 64 * @param peer identity of the other peer
58 * @param address where to send the message, human-readable 65 * @param address where to send the message, human-readable
59 * communicator-specific format, 0-terminated, UTF-8 66 * communicator-specific format, 0-terminated, UTF-8
60 * @return NULL if the provided address is invalid, otherwise an MQ to 67 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the provided address is invalid
61 * send messages to that peer
62 */ 68 */
63typedef struct GNUNET_MQ_Handle * 69typedef int
64(*GNUNET_TRANSPORT_CommunicatorMqInit) (void *cls, 70(*GNUNET_TRANSPORT_CommunicatorMqInit) (void *cls,
65 const struct GNUNET_PeerIdentity *peer, 71 const struct GNUNET_PeerIdentity *peer,
66 const void *address); 72 const void *address);
@@ -78,7 +84,7 @@ struct GNUNET_TRANSPORT_CommunicatorHandle;
78 * @param cfg configuration to use 84 * @param cfg configuration to use
79 * @param name name of the communicator that is connecting 85 * @param name name of the communicator that is connecting
80 * @param mtu maximum message size supported by communicator, 0 if 86 * @param mtu maximum message size supported by communicator, 0 if
81 * sending is not supported 87 * sending is not supported, SIZE_MAX for no MTU
82 * @param mq_init function to call to initialize a message queue given 88 * @param mq_init function to call to initialize a message queue given
83 * the address of another peer, can be NULL if the 89 * the address of another peer, can be NULL if the
84 * communicator only supports receiving messages 90 * communicator only supports receiving messages
@@ -144,6 +150,12 @@ GNUNET_TRANSPORT_communicator_receive (struct GNUNET_TRANSPORT_CommunicatorHandl
144 150
145/* ************************* Discovery *************************** */ 151/* ************************* Discovery *************************** */
146 152
153/**
154 * Handle returned to identify the internal data structure the transport
155 * API has created to manage a message queue to a particular peer.
156 */
157struct GNUNET_TRANSPORT_QueueHandle;
158
147 159
148/** 160/**
149 * Notify transport service that an MQ became available due to an 161 * Notify transport service that an MQ became available due to an
@@ -155,8 +167,9 @@ GNUNET_TRANSPORT_communicator_receive (struct GNUNET_TRANSPORT_CommunicatorHandl
155 * @param address address in human-readable format, 0-terminated, UTF-8 167 * @param address address in human-readable format, 0-terminated, UTF-8
156 * @param nt which network type does the @a address belong to? 168 * @param nt which network type does the @a address belong to?
157 * @param mq message queue of the @a peer 169 * @param mq message queue of the @a peer
170 * @return API handle identifying the new MQ
158 */ 171 */
159void 172struct GNUNET_TRANSPORT_QueueHandle *
160GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, 173GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
161 const struct GNUNET_PeerIdentity *peer, 174 const struct GNUNET_PeerIdentity *peer,
162 const char *address, 175 const char *address,
@@ -168,18 +181,17 @@ GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle
168 * Notify transport service that an MQ became unavailable due to a 181 * Notify transport service that an MQ became unavailable due to a
169 * disconnect or timeout. 182 * disconnect or timeout.
170 * 183 *
171 * @param handle connection to transport service 184 * @param qh handle for the queue that must be invalidated
172 * @param peer peer with which we can no longer communicate via the given mq
173 * @param address address in human-readable format, 0-terminated, UTF-8
174 * @param nt which network type does the @a address belong to?
175 * @param mq message queue of the @a peer
176 */ 185 */
177void 186void
178GNUNET_TRANSPORT_communicator_mq_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, 187GNUNET_TRANSPORT_communicator_mq_del (struct GNUNET_TRANSPORT_QueueHandle *qh);
179 const struct GNUNET_PeerIdentity *peer, 188
180 const char *address, 189
181 enum GNUNET_ATS_Network_Type nt, 190/**
182 struct GNUNET_MQ_Handle *mq); 191 * Internal representation of an address a communicator is
192 * currently providing for the transport service.
193 */
194struct GNUNET_TRANSPORT_AddressIdentifier;
183 195
184 196
185/** 197/**
@@ -191,7 +203,7 @@ GNUNET_TRANSPORT_communicator_mq_remove (struct GNUNET_TRANSPORT_CommunicatorHan
191 * @param nt which network type does the address belong to? 203 * @param nt which network type does the address belong to?
192 * @param expiration when does the communicator forsee this address expiring? 204 * @param expiration when does the communicator forsee this address expiring?
193 */ 205 */
194void 206struct GNUNET_TRANSPORT_AddressIdentifier *
195GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, 207GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
196 const char *address, 208 const char *address,
197 enum GNUNET_ATS_Network_Type nt, 209 enum GNUNET_ATS_Network_Type nt,
@@ -202,13 +214,10 @@ GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorH
202 * Notify transport service about an address that this communicator 214 * Notify transport service about an address that this communicator
203 * no longer provides for this peer. 215 * no longer provides for this peer.
204 * 216 *
205 * @param handle connection to transport service 217 * @param ai address that is no longer provided
206 * @param address our former address in human-readable format,
207 * 0-terminated, in UTF-8
208 */ 218 */
209void 219void
210GNUNET_TRANSPORT_communicator_address_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, 220GNUNET_TRANSPORT_communicator_address_remove (struct GNUNET_TRANSPORT_AddressIdentifier *ai);
211 const char *address);
212 221
213 222
214#if 0 /* keep Emacsens' auto-indent happy */ 223#if 0 /* keep Emacsens' auto-indent happy */