diff options
author | Christian Grothoff <christian@grothoff.org> | 2018-10-18 16:43:40 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2018-10-18 16:43:40 +0200 |
commit | d66b89ea37c9885f3ea8c42a6735b2c805c00618 (patch) | |
tree | 243f7cf63f129127bbf6e72a208a5871c2a5e177 /src | |
parent | e6c64fc035500bc098777e7687dc3da5b2aac35c (diff) | |
download | gnunet-d66b89ea37c9885f3ea8c42a6735b2c805c00618.tar.gz gnunet-d66b89ea37c9885f3ea8c42a6735b2c805c00618.zip |
revise communicator API
Diffstat (limited to 'src')
-rw-r--r-- | src/include/gnunet_transport_communication_service.h | 53 |
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 | */ |
63 | typedef struct GNUNET_MQ_Handle * | 69 | typedef 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 | */ | ||
157 | struct 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 | */ |
159 | void | 172 | struct GNUNET_TRANSPORT_QueueHandle * |
160 | GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, | 173 | GNUNET_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 | */ |
177 | void | 186 | void |
178 | GNUNET_TRANSPORT_communicator_mq_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, | 187 | GNUNET_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 | */ | ||
194 | struct 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 | */ |
194 | void | 206 | struct GNUNET_TRANSPORT_AddressIdentifier * |
195 | GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, | 207 | GNUNET_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 | */ |
209 | void | 219 | void |
210 | GNUNET_TRANSPORT_communicator_address_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, | 220 | GNUNET_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 */ |