aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_psyc_service.h
diff options
context:
space:
mode:
authorGabor X Toth <*@tg-x.net>2013-07-15 07:54:16 +0000
committerGabor X Toth <*@tg-x.net>2013-07-15 07:54:16 +0000
commitd6e993f8abf50bd8d9b637e0fad3b74e71a1850b (patch)
tree7df97bf55a526f835ef34d0741031aa3159eaf83 /src/include/gnunet_psyc_service.h
parent0c4e64676857a0963d74588c0a20e5a54892fb67 (diff)
downloadgnunet-d6e993f8abf50bd8d9b637e0fad3b74e71a1850b.tar.gz
gnunet-d6e993f8abf50bd8d9b637e0fad3b74e71a1850b.zip
env: doc; spaces
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r--src/include/gnunet_psyc_service.h42
1 files changed, 21 insertions, 21 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 32f0677da..9354d81e9 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -33,21 +33,21 @@
33 * NOTE: 33 * NOTE:
34 * - this API does not know about psyc's "root" and "places"; 34 * - this API does not know about psyc's "root" and "places";
35 * there is no 'root' in GNUnet-Psyc as we're decentralized; 35 * there is no 'root' in GNUnet-Psyc as we're decentralized;
36 * 'places' and 'persons' are combined within the same 36 * 'places' and 'persons' are combined within the same
37 * abstraction, that of a "channel". Channels are identified 37 * abstraction, that of a "channel". Channels are identified
38 * and accessed in this API using a public/private key. 38 * and accessed in this API using a public/private key.
39 * Higher-level applications should use NAMES within GADS 39 * Higher-level applications should use NAMES within GADS
40 * to obtain public keys, and the distinction between 40 * to obtain public keys, and the distinction between
41 * 'places' and 'persons' can then be made with the help 41 * 'places' and 'persons' can then be made with the help
42 * of the naming system (and/or conventions). 42 * of the naming system (and/or conventions).
43 * Channels are (as in PSYC) organized into a hierarchy; each 43 * Channels are (as in PSYC) organized into a hierarchy; each
44 * channel master (the one with the private key) is then 44 * channel master (the one with the private key) is then
45 * the operator of the multicast group (its Origin in 45 * the operator of the multicast group (its Origin in
46 * the terminology of the multicast API). 46 * the terminology of the multicast API).
47 * - The API supports passing large amounts of data using 47 * - The API supports passing large amounts of data using
48 * 'streaming' for the argument passed to a method. State 48 * 'streaming' for the argument passed to a method. State
49 * and variables must fit into memory and cannot be streamed 49 * and variables must fit into memory and cannot be streamed
50 * (thus, no passing of 4 GB of data in a variable; 50 * (thus, no passing of 4 GB of data in a variable;
51 * once we implement this, we might want to create a 51 * once we implement this, we might want to create a
52 * @c \#define for the maximum size of a variable). 52 * @c \#define for the maximum size of a variable).
53 * - PSYC defines standard variables, methods, etc. This 53 * - PSYC defines standard variables, methods, etc. This
@@ -65,7 +65,7 @@
65 * receives messages (but never forwards; private responses 65 * receives messages (but never forwards; private responses
66 * would be transmitted by joining the senders 'inbox' 66 * would be transmitted by joining the senders 'inbox'
67 * channel -- or a inbox#bob subchannel). The 67 * channel -- or a inbox#bob subchannel). The
68 * goal for all of this is to keep the abstractions in this 68 * goal for all of this is to keep the abstractions in this
69 * API minimal: interaction with multicast, try \& slice, 69 * API minimal: interaction with multicast, try \& slice,
70 * state/variable/channel management. Higher-level 70 * state/variable/channel management. Higher-level
71 * operations belong elsewhere (so maybe this API should 71 * operations belong elsewhere (so maybe this API should
@@ -134,7 +134,7 @@ struct GNUNET_PSYC_PartHandle;
134 134
135/** 135/**
136 * Method called from PSYC upon receiving a message indicating a call 136 * Method called from PSYC upon receiving a message indicating a call
137 * to a @e method. 137 * to a @e method.
138 * 138 *
139 * @param cls Closure. 139 * @param cls Closure.
140 * @param sender Who transmitted the message (master, except for messages 140 * @param sender Who transmitted the message (master, except for messages
@@ -149,7 +149,7 @@ struct GNUNET_PSYC_PartHandle;
149 * @param header Modifiers present in the message. FIXME: use environment instead? 149 * @param header Modifiers present in the message. FIXME: use environment instead?
150 * @param data_offset Byte offset of @a data in the overall data of the method. 150 * @param data_offset Byte offset of @a data in the overall data of the method.
151 * @param data_size Number of bytes in @a data. 151 * @param data_size Number of bytes in @a data.
152 * @param data Data stream given to the method (might not be zero-terminated 152 * @param data Data stream given to the method (might not be zero-terminated
153 * if data is binary). 153 * if data is binary).
154 * @param frag Fragmentation status for the data. 154 * @param frag Fragmentation status for the data.
155 */ 155 */
@@ -174,7 +174,7 @@ typedef int (*GNUNET_PSYC_Method)(void *cls,
174 * @param header_length Number of modifiers in header. 174 * @param header_length Number of modifiers in header.
175 * @param header Modifiers present in the message. 175 * @param header Modifiers present in the message.
176 * @param data_size Number of bytes in @a data. 176 * @param data_size Number of bytes in @a data.
177 * @param data Data stream given to the method (might not be zero-terminated 177 * @param data Data stream given to the method (might not be zero-terminated
178 * if data is binary). 178 * if data is binary).
179 */ 179 */
180typedef int (*GNUNET_PSYC_JoinCallback)(void *cls, 180typedef int (*GNUNET_PSYC_JoinCallback)(void *cls,
@@ -196,7 +196,7 @@ typedef int (*GNUNET_PSYC_JoinCallback)(void *cls,
196 * @param header_length Number of modifiers in header. 196 * @param header_length Number of modifiers in header.
197 * @param header Modifiers present in the message. 197 * @param header Modifiers present in the message.
198 * @param data_size Number of bytes in @a data. 198 * @param data_size Number of bytes in @a data.
199 * @param data Data stream given to the method (might not be zero-terminated 199 * @param data Data stream given to the method (might not be zero-terminated
200 * if data is binary). 200 * if data is binary).
201 */ 201 */
202typedef int (*GNUNET_PSYC_PartCallback)(void *cls, 202typedef int (*GNUNET_PSYC_PartCallback)(void *cls,
@@ -300,7 +300,7 @@ GNUNET_PSYC_master_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
300 * @param[out] data Where to write the body of the message to give to the method; 300 * @param[out] data Where to write the body of the message to give to the method;
301 * function must copy at most @a *data_size bytes to @a data. 301 * function must copy at most @a *data_size bytes to @a data.
302 * @return #GNUNET_SYSERR on error (fatal, aborts transmission) 302 * @return #GNUNET_SYSERR on error (fatal, aborts transmission)
303 * #GNUNET_NO on success, if more data is to be transmitted later 303 * #GNUNET_NO on success, if more data is to be transmitted later
304 * (should be used if @a *data_size was not big enough to take all the data) 304 * (should be used if @a *data_size was not big enough to take all the data)
305 * #GNUNET_YES if this completes the transmission (all data supplied) 305 * #GNUNET_YES if this completes the transmission (all data supplied)
306 */ 306 */
@@ -311,7 +311,7 @@ typedef int (*GNUNET_PSYC_MasterReadyNotify)(void *cls,
311 311
312 312
313/** 313/**
314 * Handle for a pending PSYC transmission operation. 314 * Handle for a pending PSYC transmission operation.
315 */ 315 */
316struct GNUNET_PSYC_MasterTransmitHandle; 316struct GNUNET_PSYC_MasterTransmitHandle;
317 317
@@ -363,20 +363,20 @@ struct GNUNET_PSYC_Channel;
363 363
364/** 364/**
365 * Convert a channel @a master to a @e channel handle to access the @e channel APIs. 365 * Convert a channel @a master to a @e channel handle to access the @e channel APIs.
366 * 366 *
367 * @param master Channel master handle. 367 * @param master Channel master handle.
368 * @return Channel handle, valid for as long as @a master is valid. 368 * @return Channel handle, valid for as long as @a master is valid.
369 */ 369 */
370struct GNUNET_PSYC_Channel * 370struct GNUNET_PSYC_Channel *
371GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); 371GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master);
372 372
373 373
374/** 374/**
375 * Convert @a slave to a @e channel handle to access the @e channel APIs. 375 * Convert @a slave to a @e channel handle to access the @e channel APIs.
376 * 376 *
377 * @param slave Slave handle. 377 * @param slave Slave handle.
378 * @return Channel handle, valid for as long as @a slave is valid. 378 * @return Channel handle, valid for as long as @a slave is valid.
379 */ 379 */
380struct GNUNET_PSYC_Channel * 380struct GNUNET_PSYC_Channel *
381GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); 381GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave);
382 382
@@ -473,7 +473,7 @@ struct GNUNET_PSYC_Slave;
473 * @return Handle for the slave, NULL on error. 473 * @return Handle for the slave, NULL on error.
474 */ 474 */
475struct GNUNET_PSYC_Slave * 475struct GNUNET_PSYC_Slave *
476GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, 476GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
477 const struct GNUNET_CRYPTO_EccPublicKey *pub_key, 477 const struct GNUNET_CRYPTO_EccPublicKey *pub_key,
478 const struct GNUNET_PeerIdentity *origin, 478 const struct GNUNET_PeerIdentity *origin,
479 GNUNET_PSYC_Method method, 479 GNUNET_PSYC_Method method,
@@ -565,9 +565,9 @@ struct GNUNET_PSYC_Story;
565 * @param end_message_id Last (exclusive) interesting point in history. 565 * @param end_message_id Last (exclusive) interesting point in history.
566 * @param method Function to invoke on messages received from the story. 566 * @param method Function to invoke on messages received from the story.
567 * @param method_cls Closure for @a method. 567 * @param method_cls Closure for @a method.
568 * @param finish_cb Function to call when the requested story has been fully 568 * @param finish_cb Function to call when the requested story has been fully
569 * told (counting message IDs might not suffice, as some messages 569 * told (counting message IDs might not suffice, as some messages
570 * might be secret and thus the listener would not know the story is 570 * might be secret and thus the listener would not know the story is
571 * finished without being told explicitly); once this function 571 * finished without being told explicitly); once this function
572 * has been called, the client must not call 572 * has been called, the client must not call
573 * GNUNET_PSYC_slave_story_tell_cancel() anymore. 573 * GNUNET_PSYC_slave_story_tell_cancel() anymore.
@@ -609,7 +609,7 @@ GNUNET_PSYC_slave_story_tell_cancel (struct GNUNET_PSYC_Story *story);
609 * values stored under "_a_b_c". 609 * values stored under "_a_b_c".
610 * 610 *
611 * @param slave Slave handle. 611 * @param slave Slave handle.
612 * @param state_name Name of the state to query (full name 612 * @param state_name Name of the state to query (full name
613 * might be longer, this is only the prefix that must match). 613 * might be longer, this is only the prefix that must match).
614 * @param cb Function to call on the matching state values. 614 * @param cb Function to call on the matching state values.
615 * @param cb_cls Closure for @a cb. 615 * @param cb_cls Closure for @a cb.
@@ -636,7 +636,7 @@ GNUNET_PSYC_slave_state_get_all (struct GNUNET_PSYC_Slave *slave,
636 * 636 *
637 * @param slave Slave handle. 637 * @param slave Slave handle.
638 * @param variable_name Name of the variable to query. 638 * @param variable_name Name of the variable to query.
639 * @param[out] return_value_size Set to number of bytes in variable, 639 * @param[out] return_value_size Set to number of bytes in variable,
640 * needed as variables might contain binary data and 640 * needed as variables might contain binary data and
641 * might also not be 0-terminated; set to 0 on errors. 641 * might also not be 0-terminated; set to 0 on errors.
642 * @return NULL on error (no matching state or variable), pointer 642 * @return NULL on error (no matching state or variable), pointer