diff options
author | Gabor X Toth <*@tg-x.net> | 2014-07-30 21:18:13 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2014-07-30 21:18:13 +0000 |
commit | 40884377f3126bbecbfd3243d47224b3094914f9 (patch) | |
tree | 9f32aab9064b199178282a0c9918313e0aa30049 /src/include/gnunet_psyc_service.h | |
parent | 831718fa44b2c56577aa4e36a479fef6debb8cea (diff) | |
download | gnunet-40884377f3126bbecbfd3243d47224b3094914f9.tar.gz gnunet-40884377f3126bbecbfd3243d47224b3094914f9.zip |
psyc, psycstore: retrieve state and history
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 226 |
1 files changed, 137 insertions, 89 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index 7097c46a8..25b405dad 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_service.h | |||
@@ -160,6 +160,11 @@ enum GNUNET_PSYC_Policy | |||
160 | enum GNUNET_PSYC_MessageFlags | 160 | enum GNUNET_PSYC_MessageFlags |
161 | { | 161 | { |
162 | /** | 162 | /** |
163 | * Default / no flags. | ||
164 | */ | ||
165 | GNUNET_PSYC_MESSAGE_DEFAULT = 0, | ||
166 | |||
167 | /** | ||
163 | * Historic message, retrieved from PSYCstore. | 168 | * Historic message, retrieved from PSYCstore. |
164 | */ | 169 | */ |
165 | GNUNET_PSYC_MESSAGE_HISTORIC = 1 << 0, | 170 | GNUNET_PSYC_MESSAGE_HISTORIC = 1 << 0, |
@@ -314,12 +319,12 @@ struct GNUNET_PSYC_CountersResultMessage | |||
314 | /** | 319 | /** |
315 | * Status code for the operation. | 320 | * Status code for the operation. |
316 | */ | 321 | */ |
317 | int32_t result_code GNUNET_PACKED; | 322 | uint32_t result_code GNUNET_PACKED; |
318 | 323 | ||
319 | /** | 324 | /** |
320 | * Last message ID sent to the channel. | 325 | * Last message ID sent to the channel. |
321 | */ | 326 | */ |
322 | uint64_t max_message_id; | 327 | uint64_t max_message_id GNUNET_PACKED; |
323 | }; | 328 | }; |
324 | 329 | ||
325 | 330 | ||
@@ -503,13 +508,24 @@ struct GNUNET_PSYC_Master; | |||
503 | 508 | ||
504 | 509 | ||
505 | /** | 510 | /** |
506 | * Function called after the channel master started. | 511 | * Function called after connected to the PSYC service |
512 | * and the channel master started. | ||
507 | * | 513 | * |
508 | * @param cls Closure. | 514 | * Also called when reconnected to the service |
509 | * @param max_message_id Last message ID sent to the channel. | 515 | * after the connection closed unexpectedly. |
516 | * | ||
517 | * @param cls | ||
518 | * Closure. | ||
519 | * @param result | ||
520 | * #GNUNET_YES if there were already messages sent to the channel, | ||
521 | * #GNUNET_NO if the message history is empty, | ||
522 | * #GNUNET_SYSERR on error. | ||
523 | * @param max_message_id | ||
524 | * Last message ID sent to the channel. | ||
510 | */ | 525 | */ |
511 | typedef void | 526 | typedef void |
512 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id); | 527 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, int result, |
528 | uint64_t max_message_id); | ||
513 | 529 | ||
514 | 530 | ||
515 | /** | 531 | /** |
@@ -720,11 +736,21 @@ struct GNUNET_PSYC_Slave; | |||
720 | /** | 736 | /** |
721 | * Function called after the slave connected to the PSYC service. | 737 | * Function called after the slave connected to the PSYC service. |
722 | * | 738 | * |
723 | * @param cls Closure. | 739 | * Also called when reconnected to the service |
724 | * @param max_message_id Last message ID sent to the channel. | 740 | * after the connection closed unexpectedly. |
741 | * | ||
742 | * @param cls | ||
743 | * Closure. | ||
744 | * @param result | ||
745 | * #GNUNET_YES if there were already messages sent to the channel, | ||
746 | * #GNUNET_NO if the message history is empty, | ||
747 | * #GNUNET_SYSERR on error. | ||
748 | * @param max_message_id | ||
749 | * Last message ID sent to the channel. | ||
725 | */ | 750 | */ |
726 | typedef void | 751 | typedef void |
727 | (*GNUNET_PSYC_SlaveConnectCallback) (void *cls, uint64_t max_message_id); | 752 | (*GNUNET_PSYC_SlaveConnectCallback) (void *cls, int result, |
753 | uint64_t max_message_id); | ||
728 | 754 | ||
729 | 755 | ||
730 | /** | 756 | /** |
@@ -876,6 +902,23 @@ struct GNUNET_PSYC_Channel; | |||
876 | 902 | ||
877 | 903 | ||
878 | /** | 904 | /** |
905 | * Function called with the result of an asynchronous operation. | ||
906 | * | ||
907 | * @param cls | ||
908 | * Closure. | ||
909 | * @param result | ||
910 | * Result of the operation. | ||
911 | * Usually one of #GNUNET_OK, #GNUNET_YES, #GNUNET_NO, or #GNUNET_SYSERR. | ||
912 | * @param err_msg | ||
913 | * Error message. | ||
914 | */ | ||
915 | typedef void | ||
916 | (*GNUNET_PSYC_ResultCallback) (void *cls, | ||
917 | int64_t result, | ||
918 | const char *err_msg); | ||
919 | |||
920 | |||
921 | /** | ||
879 | * Convert a channel @a master to a @e channel handle to access the @e channel | 922 | * Convert a channel @a master to a @e channel handle to access the @e channel |
880 | * APIs. | 923 | * APIs. |
881 | * | 924 | * |
@@ -921,7 +964,9 @@ void | |||
921 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | 964 | GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, |
922 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, | 965 | const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key, |
923 | uint64_t announced_at, | 966 | uint64_t announced_at, |
924 | uint64_t effective_since); | 967 | uint64_t effective_since, |
968 | GNUNET_PSYC_ResultCallback result_cb, | ||
969 | void *cls); | ||
925 | 970 | ||
926 | 971 | ||
927 | /** | 972 | /** |
@@ -949,7 +994,9 @@ void | |||
949 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | 994 | GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, |
950 | const struct GNUNET_CRYPTO_EcdsaPublicKey | 995 | const struct GNUNET_CRYPTO_EcdsaPublicKey |
951 | *slave_key, | 996 | *slave_key, |
952 | uint64_t announced_at); | 997 | uint64_t announced_at, |
998 | GNUNET_PSYC_ResultCallback result_cb, | ||
999 | void *cls); | ||
953 | 1000 | ||
954 | 1001 | ||
955 | /** | 1002 | /** |
@@ -962,74 +1009,69 @@ GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | |||
962 | * @param value_size Number of bytes in @a value. | 1009 | * @param value_size Number of bytes in @a value. |
963 | */ | 1010 | */ |
964 | typedef void | 1011 | typedef void |
965 | (*GNUNET_PSYC_StateCallback) (void *cls, | 1012 | (*GNUNET_PSYC_StateVarCallback) (void *cls, |
966 | const char *name, | 1013 | const char *name, |
967 | const void *value, | 1014 | const void *value, |
968 | size_t value_size); | 1015 | size_t value_size); |
969 | 1016 | ||
970 | 1017 | ||
971 | /** | 1018 | /** |
972 | * Function called when a requested operation has finished. | 1019 | * Request to replay a part of the message history of the channel. |
973 | * | ||
974 | * @param cls Closure. | ||
975 | */ | ||
976 | typedef void | ||
977 | (*GNUNET_PSYC_FinishCallback) (void *cls); | ||
978 | |||
979 | |||
980 | /** | ||
981 | * Handle to a story telling operation. | ||
982 | */ | ||
983 | struct GNUNET_PSYC_Story; | ||
984 | |||
985 | |||
986 | /** | ||
987 | * Request to be told the message history of the channel. | ||
988 | * | 1020 | * |
989 | * Historic messages (but NOT the state at the time) will be replayed (given to | 1021 | * Historic messages (but NOT the state at the time) will be replayed (given to |
990 | * the normal method handlers) if available and if access is permitted. | 1022 | * the normal method handlers) if available and if access is permitted. |
991 | * | 1023 | * |
992 | * To get the latest message, use 0 for both the start and end message ID. | 1024 | * @param channel |
1025 | * Which channel should be replayed? | ||
1026 | * @param start_message_id | ||
1027 | * Earliest interesting point in history. | ||
1028 | * @param end_message_id | ||
1029 | * Last (inclusive) interesting point in history. | ||
1030 | * @param finish_cb | ||
1031 | * Function to call when the requested history has been fully replayed | ||
1032 | * (counting message IDs might not suffice, as some messages might be | ||
1033 | * secret and thus the listener would not know the story is finished | ||
1034 | * without being told explicitly)o once this function has been called, the | ||
1035 | * client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore. | ||
1036 | * @param cls | ||
1037 | * Closure for the callbacks. | ||
993 | * | 1038 | * |
994 | * @param channel Which channel should be replayed? | 1039 | * @return Handle to cancel history replay operation. |
995 | * @param start_message_id Earliest interesting point in history. | ||
996 | * @param end_message_id Last (exclusive) interesting point in history. | ||
997 | * @param message_cb Function to invoke on message parts received from the story. | ||
998 | * @param finish_cb Function to call when the requested story has been fully | ||
999 | * told (counting message IDs might not suffice, as some messages | ||
1000 | * might be secret and thus the listener would not know the story is | ||
1001 | * finished without being told explicitly); once this function | ||
1002 | * has been called, the client must not call | ||
1003 | * GNUNET_PSYC_channel_story_tell_cancel() anymore. | ||
1004 | * @param cls Closure for the callbacks. | ||
1005 | * @return Handle to cancel story telling operation. | ||
1006 | */ | 1040 | */ |
1007 | struct GNUNET_PSYC_Story * | 1041 | void |
1008 | GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel, | 1042 | GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel, |
1009 | uint64_t start_message_id, | 1043 | uint64_t start_message_id, |
1010 | uint64_t end_message_id, | 1044 | uint64_t end_message_id, |
1011 | GNUNET_PSYC_MessageCallback message_cb, | 1045 | GNUNET_PSYC_ResultCallback finish_cb, |
1012 | GNUNET_PSYC_MessagePartCallback message_part_cb, | 1046 | void *cls); |
1013 | GNUNET_PSYC_FinishCallback finish_cb, | ||
1014 | void *cls); | ||
1015 | 1047 | ||
1016 | 1048 | ||
1017 | /** | 1049 | /** |
1018 | * Abort story telling. | 1050 | * Request to replay the latest messages from the message history of the channel. |
1051 | * | ||
1052 | * Historic messages (but NOT the state at the time) will be replayed (given to | ||
1053 | * the normal method handlers) if available and if access is permitted. | ||
1019 | * | 1054 | * |
1020 | * This function must not be called from within method handlers (as given to | 1055 | * @param channel |
1021 | * GNUNET_PSYC_slave_join()) of the slave. | 1056 | * Which channel should be replayed? |
1057 | * @param message_limit | ||
1058 | * Maximum number of messages to replay. | ||
1059 | * @param finish_cb | ||
1060 | * Function to call when the requested history has been fully replayed | ||
1061 | * (counting message IDs might not suffice, as some messages might be | ||
1062 | * secret and thus the listener would not know the story is finished | ||
1063 | * without being told explicitly)o once this function has been called, the | ||
1064 | * client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore. | ||
1065 | * @param cls | ||
1066 | * Closure for the callbacks. | ||
1022 | * | 1067 | * |
1023 | * @param story Story telling operation to stop. | 1068 | * @return Handle to cancel history replay operation. |
1024 | */ | 1069 | */ |
1025 | void | 1070 | void |
1026 | GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story); | 1071 | GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel, |
1027 | 1072 | uint64_t message_limit, | |
1028 | 1073 | GNUNET_PSYC_ResultCallback finish_cb, | |
1029 | /** | 1074 | void *cls); |
1030 | * Handle for a state query operation. | ||
1031 | */ | ||
1032 | struct GNUNET_PSYC_StateQuery; | ||
1033 | 1075 | ||
1034 | 1076 | ||
1035 | /** | 1077 | /** |
@@ -1039,19 +1081,26 @@ struct GNUNET_PSYC_StateQuery; | |||
1039 | * less-specific name is matched; for example, requesting "_a_b" will match "_a" | 1081 | * less-specific name is matched; for example, requesting "_a_b" will match "_a" |
1040 | * if "_a_b" does not exist. | 1082 | * if "_a_b" does not exist. |
1041 | * | 1083 | * |
1042 | * @param channel Channel handle. | 1084 | * @param channel |
1043 | * @param full_name Full name of the requested variable, the actual variable | 1085 | * Channel handle. |
1044 | * returned might have a shorter name.. | 1086 | * @param full_name |
1045 | * @param cb Function called once when a matching state variable is found. | 1087 | * Full name of the requested variable. |
1088 | * The actual variable returned might have a shorter name. | ||
1089 | * @param var_cb | ||
1090 | * Function called once when a matching state variable is found. | ||
1046 | * Not called if there's no matching state variable. | 1091 | * Not called if there's no matching state variable. |
1047 | * @param cb_cls Closure for the callbacks. | 1092 | * @param result_cb |
1048 | * @return Handle that can be used to cancel the query operation. | 1093 | * Function called after the operation finished. |
1094 | * (i.e. all state variables have been returned via @a state_cb) | ||
1095 | * @param cls | ||
1096 | * Closure for the callbacks. | ||
1049 | */ | 1097 | */ |
1050 | struct GNUNET_PSYC_StateQuery * | 1098 | void |
1051 | GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | 1099 | GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, |
1052 | const char *full_name, | 1100 | const char *full_name, |
1053 | GNUNET_PSYC_StateCallback cb, | 1101 | GNUNET_PSYC_StateVarCallback var_cb, |
1054 | void *cb_cls); | 1102 | GNUNET_PSYC_ResultCallback result_cb, |
1103 | void *cls); | ||
1055 | 1104 | ||
1056 | 1105 | ||
1057 | /** | 1106 | /** |
@@ -1064,26 +1113,25 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | |||
1064 | * The @a state_cb is invoked on all matching state variables asynchronously, as | 1113 | * The @a state_cb is invoked on all matching state variables asynchronously, as |
1065 | * the state is stored in and retrieved from the PSYCstore, | 1114 | * the state is stored in and retrieved from the PSYCstore, |
1066 | * | 1115 | * |
1067 | * @param channel Channel handle. | 1116 | * @param channel |
1068 | * @param name_prefix Prefix of the state variable name to match. | 1117 | * Channel handle. |
1069 | * @param cb Function to call with the matching state variables. | 1118 | * @param name_prefix |
1070 | * @param cb_cls Closure for the callbacks. | 1119 | * Prefix of the state variable name to match. |
1071 | * @return Handle that can be used to cancel the query operation. | 1120 | * @param var_cb |
1121 | * Function called once when a matching state variable is found. | ||
1122 | * Not called if there's no matching state variable. | ||
1123 | * @param result_cb | ||
1124 | * Function called after the operation finished. | ||
1125 | * (i.e. all state variables have been returned via @a state_cb) | ||
1126 | * @param cls | ||
1127 | * Closure for the callbacks. | ||
1072 | */ | 1128 | */ |
1073 | struct GNUNET_PSYC_StateQuery * | 1129 | void |
1074 | GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, | 1130 | GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, |
1075 | const char *name_prefix, | 1131 | const char *name_prefix, |
1076 | GNUNET_PSYC_StateCallback cb, | 1132 | GNUNET_PSYC_StateVarCallback var_cb, |
1077 | void *cb_cls); | 1133 | GNUNET_PSYC_ResultCallback result_cb, |
1078 | 1134 | void *cls); | |
1079 | |||
1080 | /** | ||
1081 | * Cancel a state query operation. | ||
1082 | * | ||
1083 | * @param query Handle for the operation to cancel. | ||
1084 | */ | ||
1085 | void | ||
1086 | GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateQuery *query); | ||
1087 | 1135 | ||
1088 | 1136 | ||
1089 | #if 0 /* keep Emacsens' auto-indent happy */ | 1137 | #if 0 /* keep Emacsens' auto-indent happy */ |