diff options
author | Gabor X Toth <*@tg-x.net> | 2015-05-07 12:15:58 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2015-05-07 12:15:58 +0000 |
commit | 4725d59b468f1f30ba2910992333ca157682ce29 (patch) | |
tree | 23715ee20879c94a3363e28ea184370a4a71e44d /src/include/gnunet_psyc_service.h | |
parent | a5edf8ac9f03a368c87ea6163994d4ac3d62af06 (diff) | |
download | gnunet-4725d59b468f1f30ba2910992333ca157682ce29.tar.gz gnunet-4725d59b468f1f30ba2910992333ca157682ce29.zip |
psyc/social: request history & state from psycstore; more documentation, tests, cleanup
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 247 |
1 files changed, 195 insertions, 52 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index 5239acb16..c7692f074 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h | |||
@@ -376,6 +376,106 @@ struct GNUNET_PSYC_JoinDecisionMessage | |||
376 | /* Followed by struct GNUNET_MessageHeader join_response */ | 376 | /* Followed by struct GNUNET_MessageHeader join_response */ |
377 | }; | 377 | }; |
378 | 378 | ||
379 | |||
380 | enum GNUNET_PSYC_HistoryReplayFlags | ||
381 | { | ||
382 | /** | ||
383 | * Replay locally available messages. | ||
384 | */ | ||
385 | GNUNET_PSYC_HISTORY_REPLAY_LOCAL = 0, | ||
386 | |||
387 | /** | ||
388 | * Replay messages from remote peers if not found locally. | ||
389 | */ | ||
390 | GNUNET_PSYC_HISTORY_REPLAY_REMOTE = 1, | ||
391 | }; | ||
392 | |||
393 | |||
394 | struct GNUNET_PSYC_HistoryRequestMessage | ||
395 | { | ||
396 | /** | ||
397 | * Type: GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_HISTORY_REPLAY | ||
398 | */ | ||
399 | struct GNUNET_MessageHeader header; | ||
400 | |||
401 | /** | ||
402 | * @see enum GNUNET_PSYC_HistoryReplayFlags | ||
403 | */ | ||
404 | uint32_t flags GNUNET_PACKED; | ||
405 | |||
406 | /** | ||
407 | * ID for this operation. | ||
408 | */ | ||
409 | uint64_t op_id GNUNET_PACKED; | ||
410 | |||
411 | uint64_t start_message_id GNUNET_PACKED; | ||
412 | |||
413 | uint64_t end_message_id GNUNET_PACKED; | ||
414 | |||
415 | uint64_t message_limit GNUNET_PACKED; | ||
416 | |||
417 | /* Followed by NUL-terminated method name prefix. */ | ||
418 | }; | ||
419 | |||
420 | |||
421 | struct GNUNET_PSYC_StateRequestMessage | ||
422 | { | ||
423 | /** | ||
424 | * Types: | ||
425 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET | ||
426 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET_PREFIX | ||
427 | */ | ||
428 | struct GNUNET_MessageHeader header; | ||
429 | |||
430 | uint32_t reserved GNUNET_PACKED; | ||
431 | |||
432 | /** | ||
433 | * ID for this operation. | ||
434 | */ | ||
435 | uint64_t op_id GNUNET_PACKED; | ||
436 | |||
437 | /* Followed by NUL-terminated name. */ | ||
438 | }; | ||
439 | |||
440 | |||
441 | /**** service -> library ****/ | ||
442 | |||
443 | |||
444 | /** | ||
445 | * Answer from service to client about last operation. | ||
446 | */ | ||
447 | struct GNUNET_PSYC_OperationResultMessage | ||
448 | { | ||
449 | /** | ||
450 | * Types: | ||
451 | * - GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE | ||
452 | * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_RESULT | ||
453 | */ | ||
454 | struct GNUNET_MessageHeader header; | ||
455 | |||
456 | uint32_t reserved GNUNET_PACKED; | ||
457 | |||
458 | /** | ||
459 | * Operation ID. | ||
460 | */ | ||
461 | uint64_t op_id GNUNET_PACKED; | ||
462 | |||
463 | /** | ||
464 | * Status code for the operation. | ||
465 | */ | ||
466 | uint64_t result_code GNUNET_PACKED; | ||
467 | |||
468 | /* Followed by: | ||
469 | * - on error: NUL-terminated error message | ||
470 | * - on success: one of the following message types | ||
471 | * | ||
472 | * For a STATE_RESULT, one of: | ||
473 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER | ||
474 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT | ||
475 | * - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END | ||
476 | */ | ||
477 | }; | ||
478 | |||
379 | GNUNET_NETWORK_STRUCT_END | 479 | GNUNET_NETWORK_STRUCT_END |
380 | 480 | ||
381 | 481 | ||
@@ -907,23 +1007,6 @@ struct GNUNET_PSYC_Channel; | |||
907 | 1007 | ||
908 | 1008 | ||
909 | /** | 1009 | /** |
910 | * Function called with the result of an asynchronous operation. | ||
911 | * | ||
912 | * @param cls | ||
913 | * Closure. | ||
914 | * @param result | ||
915 | * Result of the operation. | ||
916 | * Usually one of #GNUNET_OK, #GNUNET_YES, #GNUNET_NO, or #GNUNET_SYSERR. | ||
917 | * @param err_msg | ||
918 | * Error message. | ||
919 | */ | ||
920 | typedef void | ||
921 | (*GNUNET_PSYC_ResultCallback) (void *cls, | ||
922 | int64_t result, | ||
923 | const char *err_msg); | ||
924 | |||
925 | |||
926 | /** | ||
927 | * Convert a channel @a master to a @e channel handle to access the @e channel | 1010 | * Convert a channel @a master to a @e channel handle to access the @e channel |
928 | * APIs. | 1011 | * APIs. |
929 | * | 1012 | * |
@@ -960,17 +1043,28 @@ GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); | |||
960 | * correctly; not doing so correctly will result in either denying other slaves | 1043 | * correctly; not doing so correctly will result in either denying other slaves |
961 | * access or offering access to channel data to non-members. | 1044 | * access or offering access to channel data to non-members. |
962 | * | 1045 | * |
963 | * @param channel Channel handle. | 1046 | * @param channel |
964 | * @param slave_key Identity of channel slave to add. | 1047 | * Channel handle. |
965 | * @param announced_at ID of the message that announced the membership change. | 1048 | * @param slave_key |
966 | * @param effective_since Addition of slave is in effect since this message ID. | 1049 | * Identity of channel slave to add. |
1050 | * @param announced_at | ||
1051 | * ID of the message that announced the membership change. | ||
1052 | * @param effective_since | ||
1053 | * Addition of slave is in effect since this message ID. | ||
1054 | * @param result_cb | ||
1055 | * Function to call with the result of the operation. | ||
1056 | * The @e result_code argument is #GNUNET_OK on success, or | ||
1057 | * #GNUNET_SYSERR on error. In case of an error, the @e data argument | ||
1058 | * can contain an optional error message. | ||
1059 | * @param cls | ||
1060 | * Closure for @a result_cb. | ||
967 | */ | 1061 | */ |
968 | void | 1062 | void |
969 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | 1063 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, |
970 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | 1064 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, |
971 | uint64_t announced_at, | 1065 | uint64_t announced_at, |
972 | uint64_t effective_since, | 1066 | uint64_t effective_since, |
973 | GNUNET_PSYC_ResultCallback result_cb, | 1067 | GNUNET_ResultCallback result_cb, |
974 | void *cls); | 1068 | void *cls); |
975 | 1069 | ||
976 | 1070 | ||
@@ -991,33 +1085,33 @@ GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | |||
991 | * denying members access or offering access to channel data to | 1085 | * denying members access or offering access to channel data to |
992 | * non-members. | 1086 | * non-members. |
993 | * | 1087 | * |
994 | * @param channel Channel handle. | 1088 | * @param channel |
995 | * @param slave_key Identity of channel slave to remove. | 1089 | * Channel handle. |
996 | * @param announced_at ID of the message that announced the membership change. | 1090 | * @param slave_key |
1091 | * Identity of channel slave to remove. | ||
1092 | * @param announced_at | ||
1093 | * ID of the message that announced the membership change. | ||
1094 | * @param result_cb | ||
1095 | * Function to call with the result of the operation. | ||
1096 | * The @e result_code argument is #GNUNET_OK on success, or | ||
1097 | * #GNUNET_SYSERR on error. In case of an error, the @e data argument | ||
1098 | * can contain an optional error message. | ||
1099 | * @param cls | ||
1100 | * Closure for @a result_cb. | ||
997 | */ | 1101 | */ |
998 | void | 1102 | void |
999 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | 1103 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, |
1000 | const struct GNUNET_CRYPTO_EcdsaPublicKey | 1104 | const struct GNUNET_CRYPTO_EcdsaPublicKey |
1001 | *slave_key, | 1105 | *slave_key, |
1002 | uint64_t announced_at, | 1106 | uint64_t announced_at, |
1003 | GNUNET_PSYC_ResultCallback result_cb, | 1107 | GNUNET_ResultCallback result_cb, |
1004 | void *cls); | 1108 | void *cls); |
1005 | 1109 | ||
1006 | 1110 | ||
1007 | /** | 1111 | /** |
1008 | * Function called to inform a member about stored state values for a channel. | 1112 | * History request handle. |
1009 | * | ||
1010 | * @param cls Closure. | ||
1011 | * @param name Name of the state variable. A NULL value indicates that there | ||
1012 | * are no more state variables to be returned. | ||
1013 | * @param value Value of the state variable. | ||
1014 | * @param value_size Number of bytes in @a value. | ||
1015 | */ | 1113 | */ |
1016 | typedef void | 1114 | struct GNUNET_PSYC_HistoryRequest; |
1017 | (*GNUNET_PSYC_StateVarCallback) (void *cls, | ||
1018 | const char *name, | ||
1019 | const void *value, | ||
1020 | size_t value_size); | ||
1021 | 1115 | ||
1022 | 1116 | ||
1023 | /** | 1117 | /** |
@@ -1032,22 +1126,28 @@ typedef void | |||
1032 | * Earliest interesting point in history. | 1126 | * Earliest interesting point in history. |
1033 | * @param end_message_id | 1127 | * @param end_message_id |
1034 | * Last (inclusive) interesting point in history. | 1128 | * Last (inclusive) interesting point in history. |
1035 | * @param finish_cb | 1129 | * @param method_prefix |
1036 | * Function to call when the requested history has been fully replayed | 1130 | * Retrieve only messages with a matching method prefix. |
1037 | * (counting message IDs might not suffice, as some messages might be | 1131 | * @param flags |
1038 | * secret and thus the listener would not know the story is finished | 1132 | * OR'ed enum GNUNET_PSYC_HistoryReplayFlags |
1039 | * without being told explicitly)o once this function has been called, the | 1133 | * @param result_cb |
1040 | * client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore. | 1134 | * Function to call when the requested history has been fully replayed. |
1135 | * Once this function has been called, the client must not call | ||
1136 | * GNUNET_PSYC_channel_history_replay_cancel() anymore. | ||
1041 | * @param cls | 1137 | * @param cls |
1042 | * Closure for the callbacks. | 1138 | * Closure for the callbacks. |
1043 | * | 1139 | * |
1044 | * @return Handle to cancel history replay operation. | 1140 | * @return Handle to cancel history replay operation. |
1045 | */ | 1141 | */ |
1046 | void | 1142 | struct GNUNET_PSYC_HistoryRequest * |
1047 | GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, | 1143 | GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, |
1048 | uint64_t start_message_id, | 1144 | uint64_t start_message_id, |
1049 | uint64_t end_message_id, | 1145 | uint64_t end_message_id, |
1050 | GNUNET_PSYC_ResultCallback finish_cb, | 1146 | const char *method_prefix, |
1147 | uint32_t flags, | ||
1148 | GNUNET_PSYC_MessageCallback message_cb, | ||
1149 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
1150 | GNUNET_ResultCallback result_cb, | ||
1051 | void *cls); | 1151 | void *cls); |
1052 | 1152 | ||
1053 | 1153 | ||
@@ -1061,6 +1161,8 @@ GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, | |||
1061 | * Which channel should be replayed? | 1161 | * Which channel should be replayed? |
1062 | * @param message_limit | 1162 | * @param message_limit |
1063 | * Maximum number of messages to replay. | 1163 | * Maximum number of messages to replay. |
1164 | * @param flags | ||
1165 | * OR'ed enum GNUNET_PSYC_HistoryReplayFlags | ||
1064 | * @param finish_cb | 1166 | * @param finish_cb |
1065 | * Function to call when the requested history has been fully replayed | 1167 | * Function to call when the requested history has been fully replayed |
1066 | * (counting message IDs might not suffice, as some messages might be | 1168 | * (counting message IDs might not suffice, as some messages might be |
@@ -1072,13 +1174,44 @@ GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, | |||
1072 | * | 1174 | * |
1073 | * @return Handle to cancel history replay operation. | 1175 | * @return Handle to cancel history replay operation. |
1074 | */ | 1176 | */ |
1075 | void | 1177 | struct GNUNET_PSYC_HistoryRequest * |
1076 | GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel, | 1178 | GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel, |
1077 | uint64_t message_limit, | 1179 | uint64_t message_limit, |
1078 | GNUNET_PSYC_ResultCallback finish_cb, | 1180 | const char *method_prefix, |
1181 | uint32_t flags, | ||
1182 | GNUNET_PSYC_MessageCallback message_cb, | ||
1183 | GNUNET_PSYC_MessagePartCallback message_part_cb, | ||
1184 | GNUNET_ResultCallback result_cb, | ||
1079 | void *cls); | 1185 | void *cls); |
1080 | 1186 | ||
1081 | 1187 | ||
1188 | void | ||
1189 | GNUNET_PSYC_channel_history_replay_cancel (struct GNUNET_PSYC_Channel *channel, | ||
1190 | struct GNUNET_PSYC_HistoryRequest *hr); | ||
1191 | |||
1192 | |||
1193 | /** | ||
1194 | * Function called to inform a member about stored state values for a channel. | ||
1195 | * | ||
1196 | * @param cls Closure. | ||
1197 | * @param name Name of the state variable. A NULL value indicates that there | ||
1198 | * are no more state variables to be returned. | ||
1199 | * @param value Value of the state variable. | ||
1200 | * @param value_size Number of bytes in @a value. | ||
1201 | */ | ||
1202 | typedef void | ||
1203 | (*GNUNET_PSYC_StateVarCallback) (void *cls, | ||
1204 | const char *name, | ||
1205 | const void *value, | ||
1206 | size_t value_size); | ||
1207 | |||
1208 | |||
1209 | /** | ||
1210 | * State request handle. | ||
1211 | */ | ||
1212 | struct GNUNET_PSYC_StateRequest; | ||
1213 | |||
1214 | |||
1082 | /** | 1215 | /** |
1083 | * Retrieve the best matching channel state variable. | 1216 | * Retrieve the best matching channel state variable. |
1084 | * | 1217 | * |
@@ -1100,11 +1233,11 @@ GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel, | |||
1100 | * @param cls | 1233 | * @param cls |
1101 | * Closure for the callbacks. | 1234 | * Closure for the callbacks. |
1102 | */ | 1235 | */ |
1103 | void | 1236 | struct GNUNET_PSYC_StateRequest * |
1104 | GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | 1237 | GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, |
1105 | const char *full_name, | 1238 | const char *full_name, |
1106 | GNUNET_PSYC_StateVarCallback var_cb, | 1239 | GNUNET_PSYC_StateVarCallback var_cb, |
1107 | GNUNET_PSYC_ResultCallback result_cb, | 1240 | GNUNET_ResultCallback result_cb, |
1108 | void *cls); | 1241 | void *cls); |
1109 | 1242 | ||
1110 | 1243 | ||
@@ -1131,13 +1264,23 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | |||
1131 | * @param cls | 1264 | * @param cls |
1132 | * Closure for the callbacks. | 1265 | * Closure for the callbacks. |
1133 | */ | 1266 | */ |
1134 | void | 1267 | struct GNUNET_PSYC_StateRequest * |
1135 | GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, | 1268 | GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, |
1136 | const char *name_prefix, | 1269 | const char *name_prefix, |
1137 | GNUNET_PSYC_StateVarCallback var_cb, | 1270 | GNUNET_PSYC_StateVarCallback var_cb, |
1138 | GNUNET_PSYC_ResultCallback result_cb, | 1271 | GNUNET_ResultCallback result_cb, |
1139 | void *cls); | 1272 | void *cls); |
1140 | 1273 | ||
1274 | /** | ||
1275 | * Cancel a state request operation. | ||
1276 | * | ||
1277 | * @param sr | ||
1278 | * Handle for the operation to cancel. | ||
1279 | */ | ||
1280 | void | ||
1281 | GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateRequest *sr); | ||
1282 | |||
1283 | |||
1141 | 1284 | ||
1142 | #if 0 /* keep Emacsens' auto-indent happy */ | 1285 | #if 0 /* keep Emacsens' auto-indent happy */ |
1143 | { | 1286 | { |