From 235521e7893c3f6be82103700f5056a4df285afa Mon Sep 17 00:00:00 2001 From: Gabor X Toth <*@tg-x.net> Date: Thu, 12 May 2016 01:50:28 +0000 Subject: [PATCH] social cli docs --- src/social/gnunet-social.c | 156 ++++++++++++++++++++++++++++++++++--- 1 file changed, 146 insertions(+), 10 deletions(-) diff --git a/src/social/gnunet-social.c b/src/social/gnunet-social.c index 9e69208b5..bb6f1e694 100644 --- a/src/social/gnunet-social.c +++ b/src/social/gnunet-social.c @@ -157,6 +157,9 @@ struct GNUNET_SOCIAL_Place *plc; /* DISCONNECT */ +/** + * Callback called after the host or guest place disconnected. + */ static void disconnected (void *cls) { @@ -164,6 +167,9 @@ disconnected (void *cls) } +/** + * Callback called after the application disconnected. + */ static void app_disconnected (void *cls) { @@ -185,6 +191,9 @@ app_disconnected (void *cls) } +/** + * Disconnect from connected GNUnet services. + */ static void disconnect () { @@ -193,9 +202,7 @@ disconnect () } /** - * Terminate the test case (failure). - * - * @param cls NULL + * Callback called when the program failed to finish the requested operation in time. */ static void timeout (void *cls) @@ -219,6 +226,9 @@ schedule_fail (void *cls) } +/** + * Schedule exit with succes result. + */ static void exit_success () { @@ -231,6 +241,9 @@ exit_success () } +/** + * Schedule exit with failure result. + */ static void exit_fail () { @@ -246,6 +259,11 @@ exit_fail () /* LEAVE */ +/** + * Callback notifying about the host has left and stopped hosting the place. + * + * This also indicates the end of the connection to the service. + */ static void host_left () { @@ -255,6 +273,9 @@ host_left () } +/** + * Leave a place permanently and stop hosting a place. + */ static void host_leave () { @@ -264,6 +285,11 @@ host_leave () } +/** + * Callback notifying about the guest has left the place. + * + * This also indicates the end of the connection to the service. + */ static void guest_left (void *cls) { @@ -272,13 +298,15 @@ guest_left (void *cls) } +/** + * Leave a place permanently as guest. + */ static void guest_leave () { struct GNUNET_PSYC_Environment *env = GNUNET_PSYC_env_create (); - // method in the middle of vars? FIXME GNUNET_PSYC_env_add (env, GNUNET_PSYC_OP_SET, - "_notice_place_leave", DATA2ARG ("Leaving.")); + "_message", DATA2ARG ("Leaving.")); GNUNET_SOCIAL_guest_leave (gst, env, guest_left, NULL); GNUNET_PSYC_env_destroy (env); gst = NULL; @@ -296,6 +324,10 @@ struct TransmitClosure } tmit; +/** + * Callback notifying about available buffer space to write message data + * when transmitting messages using host_announce() or guest_talk() + */ static int notify_data (void *cls, uint16_t *data_size, void *data) { @@ -326,6 +358,9 @@ notify_data (void *cls, uint16_t *data_size, void *data) } +/** + * Host announcement - send a message to the place. + */ static void host_announce (const char *method, const char *data, size_t data_size) { @@ -342,6 +377,10 @@ host_announce (const char *method, const char *data, size_t data_size) GNUNET_SOCIAL_ANNOUNCE_NONE); } + +/** + * Assign a state var of @a name to the value of @a data. + */ static void host_assign (const char *name, const char *data, size_t data_size) { @@ -356,6 +395,9 @@ host_assign (const char *name, const char *data, size_t data_size) } +/** + * Guest talk request to host. + */ static void guest_talk (const char *method, const char *data, size_t data_size) @@ -377,6 +419,9 @@ guest_talk (const char *method, /* HISTORY REPLAY */ +/** + * Callback notifying about the end of history replay results. + */ static void recv_history_replay_result (void *cls, int64_t result, const void *data, uint16_t data_size) @@ -393,6 +438,10 @@ recv_history_replay_result (void *cls, int64_t result, } +/** + * Replay history between a given @a start and @a end message IDs, + * optionally filtered by a method @a prefix. + */ static void history_replay (uint64_t start, uint64_t end, const char *prefix) { @@ -404,6 +453,9 @@ history_replay (uint64_t start, uint64_t end, const char *prefix) } +/** + * Replay latest @a limit messages. + */ static void history_replay_latest (uint64_t limit, const char *prefix) { @@ -418,6 +470,9 @@ history_replay_latest (uint64_t limit, const char *prefix) /* LOOK AT/FOR */ +/** + * Callback notifying about the end of state var results. + */ static void look_result (void *cls, int64_t result_code, const void *data, uint16_t data_size) @@ -432,6 +487,9 @@ look_result (void *cls, int64_t result_code, } +/** + * Callback notifying about a state var result. + */ static void look_var (void *cls, const struct GNUNET_MessageHeader *mod, @@ -441,28 +499,37 @@ look_var (void *cls, uint32_t full_value_size) { GNUNET_log (GNUNET_ERROR_TYPE_WARNING, - "look_at_var: %s\n%.*s\n", + "Received var: %s\n%.*s\n", name, value_size, (const char *) value); } +/** + * Look for a state var using exact match of the name. + */ static void -look_at (const char *name) +look_at (const char *full_name) { - GNUNET_SOCIAL_place_look_at (plc, name, look_var, look_result, NULL); + GNUNET_SOCIAL_place_look_at (plc, full_name, look_var, look_result, NULL); } +/** + * Look for state vars by name prefix. + */ static void -look_for (const char *name) +look_for (const char *name_prefix) { - GNUNET_SOCIAL_place_look_for (plc, name, look_var, look_result, NULL); + GNUNET_SOCIAL_place_look_for (plc, name_prefix, look_var, look_result, NULL); } /* SLICER */ +/** + * Callback notifying about the start of a new incoming message. + */ static void slicer_recv_method (void *cls, const struct GNUNET_PSYC_MessageHeader *msg, @@ -477,6 +544,9 @@ slicer_recv_method (void *cls, } +/** + * Callback notifying about an incoming modifier. + */ static void slicer_recv_modifier (void *cls, const struct GNUNET_PSYC_MessageHeader *msg, @@ -495,6 +565,9 @@ slicer_recv_modifier (void *cls, } +/** + * Callback notifying about an incoming data fragment. + */ static void slicer_recv_data (void *cls, const struct GNUNET_PSYC_MessageHeader *msg, @@ -510,6 +583,9 @@ slicer_recv_data (void *cls, } +/** + * Callback notifying about the end of a message. + */ static void slicer_recv_eom (void *cls, const struct GNUNET_PSYC_MessageHeader *msg, @@ -524,6 +600,9 @@ slicer_recv_eom (void *cls, } +/** + * Create a slicer for receiving message parts. + */ static struct GNUNET_PSYC_Slicer * slicer_create () { @@ -540,6 +619,12 @@ slicer_create () /* GUEST ENTER */ +/** + * Callback called when the guest receives an entry decision from the host. + * + * It is called once after using guest_enter() or guest_enter_by_name(), + * in case of a reconnection only the local enter callback is called. + */ static void guest_recv_entry_decision (void *cls, int is_admitted, @@ -572,6 +657,9 @@ guest_recv_entry_decision (void *cls, } +/** + * Callback called after a guest connection is established to the local service. + */ static void guest_recv_local_enter (void *cls, int result, const struct GNUNET_CRYPTO_EddsaPublicKey *pub_key, @@ -590,6 +678,9 @@ guest_recv_local_enter (void *cls, int result, } +/** + * Create entry requset message. + */ static struct GNUNET_PSYC_Message * guest_enter_msg_create () { @@ -604,6 +695,9 @@ guest_enter_msg_create () } +/** + * Enter a place as guest, using its public key and peer ID. + */ static void guest_enter (const struct GNUNET_CRYPTO_EddsaPublicKey *pub_key, const struct GNUNET_PeerIdentity *peer) @@ -628,6 +722,9 @@ guest_enter (const struct GNUNET_CRYPTO_EddsaPublicKey *pub_key, } +/** + * Enter a place as guest using its GNS address. + */ static void guest_enter_by_name (const char *gns_name) { @@ -645,6 +742,11 @@ guest_enter_by_name (const char *gns_name) /* HOST ENTER */ +/** + * Callback called when a @a nym wants to enter the place. + * + * The request needs to be replied with an entry decision. + */ static void host_answer_door (void *cls, struct GNUNET_SOCIAL_Nym *nym, @@ -683,6 +785,9 @@ host_answer_door (void *cls, } +/** + * Callback called when a @a nym has left the place. + */ static void host_farewell (void *cls, const struct GNUNET_SOCIAL_Nym *nym, @@ -699,6 +804,9 @@ host_farewell (void *cls, } +/** + * Callback called after the host entered the place. + */ static void host_entered (void *cls, int result, const struct GNUNET_CRYPTO_EddsaPublicKey *pub_key, @@ -717,6 +825,9 @@ host_entered (void *cls, int result, } +/** + * Enter and start hosting a place. + */ static void host_enter () { @@ -740,6 +851,9 @@ host_enter () /* PLACE RECONNECT */ +/** + * Perform operations common to both host & guest places. + */ static void place_reconnected () { @@ -763,6 +877,9 @@ place_reconnected () } +/** + * Callback called after reconnecting to a host place. + */ static void host_reconnected (void *cls, int result, const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, @@ -786,6 +903,9 @@ host_reconnected (void *cls, int result, } +/** + * Callback called after reconnecting to a guest place. + */ static void guest_reconnected (void *cls, int result, const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key, @@ -809,6 +929,9 @@ guest_reconnected (void *cls, int result, /* APP */ +/** + * Callback called after the ego and place callbacks. + */ static void app_connected (void *cls) { @@ -853,6 +976,9 @@ app_connected (void *cls) } +/** + * Callback notifying about a host place available for reconnection. + */ static void app_recv_host (void *cls, struct GNUNET_SOCIAL_HostConnection *hconn, @@ -877,6 +1003,9 @@ app_recv_host (void *cls, } +/** + * Callback notifying about a guest place available for reconnection. + */ static void app_recv_guest (void *cls, struct GNUNET_SOCIAL_GuestConnection *gconn, @@ -901,6 +1030,9 @@ app_recv_guest (void *cls, } +/** + * Callback notifying about an available ego. + */ static void app_recv_ego (void *cls, struct GNUNET_SOCIAL_Ego *e, @@ -920,6 +1052,10 @@ app_recv_ego (void *cls, } + +/** + * Establish application connection to receive available egos and places. + */ static void app_connect () { -- 2.25.1