[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r27633 - gnunet/src/include
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] r27633 - gnunet/src/include |
|
Date: |
Wed, 26 Jun 2013 19:12:59 +0200 |
Author: tg
Date: 2013-06-26 19:12:59 +0200 (Wed, 26 Jun 2013)
New Revision: 27633
Modified:
gnunet/src/include/gnunet_multicast_service.h
gnunet/src/include/gnunet_psyc_service.h
gnunet/src/include/gnunet_psycstore_service.h
gnunet/src/include/gnunet_social_service.h
Log:
psyc apis: use more doxygen syntax, added some missing docs
Modified: gnunet/src/include/gnunet_multicast_service.h
===================================================================
--- gnunet/src/include/gnunet_multicast_service.h 2013-06-26 17:03:04 UTC
(rev 27632)
+++ gnunet/src/include/gnunet_multicast_service.h 2013-06-26 17:12:59 UTC
(rev 27633)
@@ -18,7 +18,7 @@
Boston, MA 02111-1307, USA.
*/
-/**
+/**
* @file include/gnunet_multicast_service.h
* @brief multicast service; establish tunnels to distant peers
* @author Christian Grothoff
@@ -38,35 +38,35 @@
#include "gnunet_util_lib.h"
#include "gnunet_transport_service.h"
-/**
+/**
* Version number of GNUnet-multicast API.
*/
#define GNUNET_MULTICAST_VERSION 0x00000000
-/**
+/**
* Opaque handle for a multicast group member.
*/
struct GNUNET_MULTICAST_Member;
-/**
+/**
* Handle for the origin of a multicast group.
*/
struct GNUNET_MULTICAST_Origin;
-/**
+/**
* Group membership policies.
*/
enum GNUNET_MULTICAST_JoinPolicy
{
- /**
- * Anyone can join the group, without announcing his presence; all
- * messages are always public and can be distributed freely. Joins
- * may be announced, but this is not required.
+ /**
+ * Anyone can join the group, without announcing his presence;
+ * all messages are always public and can be distributed freely.
+ * Joins may be announced, but this is not required.
*/
GNUNET_MULTICAST_JP_ANONYMOUS = 0,
- /**
+ /**
* Origin must approve membership to the group, messages must only be
* distributed to current group members. This includes the group
* state as well as transient messages.
@@ -74,13 +74,13 @@
GNUNET_MULTICAST_JP_PRIVATE = 1
#if IDEAS_FOR_FUTURE
- /**
+ /**
* Anyone can freely join the group (no approval required); however,
* transient messages must only be distributed to current group
* members, so the origin must still acknowledge that the member
* joined before transient messages are delivered. As approval is
- * guaranteed, the presistent group state can de synchronized freely
- * immediately, prior to origin confirmation
+ * guaranteed, the presistent group state can be synchronized freely
+ * immediately, prior to origin confirmation.
*/
GNUNET_MULTICAST_JP_OPEN = 2
#endif
@@ -88,45 +88,46 @@
};
-/**
+/**
* Opaque handle to a replay request from the multicast service.
*/
struct GNUNET_MULTICAST_ReplayHandle;
-/**
+/**
* Functions with this signature are called whenever the multicast
* service needs a message to be replayed. Implementations of this
- * function MUST call 'GNUNET_MULTICAST_replay' ONCE (with a message
+ * function MUST call GNUNET_MULTICAST_replay() ONCE (with a message
* or an error); however, if the origin is destroyed or the group is
* left, the replay handle must no longer be used.
*
- * @param cls closure (set from GNUNET_MULTICAST_origin_start/join)
- * @param message_id which message should be replayed
- * @param rh handle to pass to message transmit function
+ * @param cls Closure (set from GNUNET_MULTICAST_origin_start()
+ * or GNUNET_MULTICAST_member_join()).
+ * @param message_id Which message should be replayed.
+ * @param rh Handle to pass to message transmit function.
*/
typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls,
uint64_t message_id,
struct
GNUNET_MULTICAST_ReplayHandle *rh);
-/**
+/**
* Possible error codes during replay.
*/
enum GNUNET_MULTICAST_ReplayErrorCode
{
-
- /**
+
+ /**
* Everything is fine.
*/
GNUNET_MULTICAST_REC_OK = 0,
- /**
+ /**
* Message has been discarded (likely transient message that was too old).
*/
GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1,
- /**
+ /**
* Message ID counter was larger than the highest counter this
* replay function has ever encountered; thus it is likely the
* origin never sent it and we're at the HEAD of the multicast
@@ -134,7 +135,7 @@
*/
GNUNET_MULTICAST_REC_PAST_HEAD = 2,
- /**
+ /**
* Internal error (i.e. database error). Try some other peer.
*/
GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3
@@ -144,80 +145,81 @@
GNUNET_NETWORK_STRUCT_BEGIN
-/**
- * Header of a multicast message. This format is public as the replay
- * mechanism must replay messages using the same format. This is
- * needed as we want to integrity-check messages within the multicast
- * layer to avoid multicasting mal-formed messages.
+/**
+ * Header of a multicast message.
+ *
+ * This format is public as the replay mechanism must replay messages using the
+ * same format. This is needed as we want to integrity-check messages within
+ * the multicast layer to avoid multicasting mal-formed messages.
*/
struct GNUNET_MULTICAST_MessageHeader
{
- /**
+ /**
* Header for all multicast messages from the origin.
*/
struct GNUNET_MessageHeader header;
- /**
- * How many hops has this message taken since the origin?
- * (helpful to determine shortest paths to the origin for responses
- * among honest peers; updated at each hop and thus not signed
- * and not secure)
+ /**
+ * Number of hops this message has taken since the origin.
+ *
+ * Helpful to determine shortest paths to the origin for responses among
+ * honest peers; updated at each hop and thus not signed and not secure.
*/
uint32_t hop_counter GNUNET_PACKED;
- /**
- * ECC signature of the message. Signature must match the public
- * key of the multicast group.
+ /**
+ * ECC signature of the message.
+ *
+ * Signature must match the public key of the multicast group.
*/
struct GNUNET_CRYPTO_EccSignature signature;
- /**
+ /**
* Signature of the multicast message.
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
- /**
+ /**
* Number of the message, monotonically increasing.
*/
uint64_t message_id GNUNET_PACKED;
- /**
- * Counter that monotonically increases whenever a member
- * leaves the group.
+ /**
+ * Counter that monotonically increases whenever a member leaves the group.
*/
uint64_t group_generation GNUNET_PACKED;
- /**
- * Difference between the current message_id and the message_id of
- * the preceeding non-transient message. Zero for transient
- * messages, UINT64_MAX for the first message, or any other message
- * creating a full state reset by the origin. By subtracting
- * 'state_delta' from 'message_id', it is possible to calculate the
- * message ID of the preceeding non-transient message and thus
- * quickly traverse all state changes up to the last full state
- * reset by the origin. This is useful as it allows joining clients
- * to quickly reassemble the state while skipping over transient
- * messages (and doing so without having to trust intermediaries to
- * do it right, as the indices in the chain are signed). If the
- * state chain is getting too long, the origin can choose to
- * originate a state message with a state_delta of UINT64_MAX,
- * thereby starting a new chain. The origin will then have to
- * re-create the full state with state update messages following the
- * state reset message.
+ /**
+ * Difference between the current @a message_id and the @a message_id of the
+ * preceeding non-transient message.
+ *
+ * Zero for transient messages, @c UINT64_MAX for the first message, or any
+ * other message creating a full state reset by the origin. By subtracting
+ * @a state_delta from @a message_id, it is possible to calculate the message
+ * ID of the preceeding non-transient message and thus quickly traverse all
+ * state changes up to the last full state reset by the origin. This is
+ * useful as it allows joining clients to quickly reassemble the state while
+ * skipping over transient messages (and doing so without having to trust
+ * intermediaries to do it right, as the indices in the chain are signed).
If
+ * the state chain is getting too long, the origin can choose to originate a
+ * state message with a state_delta of UINT64_MAX, thereby starting a new
+ * chain. The origin will then have to re-create the full state with state
+ * update messages following the state reset message.
*
- * Open question: needed in multicast, or just have this in PSYC;
- * still might be useful for selective fetching of messages.
- * Still, that again should that not be done by PSYC?
+ * Open question: needed in multicast, or just have this in PSYC; still might
+ * be useful for selective fetching of messages. Still, that again should
+ * that not be done by PSYC?
*/
uint64_t state_delta GNUNET_PACKED;
- /**
- * Header for the message body. Three message types are
- * specifically understood by multicast, namely "peer join", "peer
- * leave", and "group terminated". Multicast will use those
- * messages to update its list of candidates for content
- * distribution. All other message types are application-specific.
+ /**
+ * Header for the message body.
+ *
+ * Three message types are specifically understood by multicast, namely "peer
+ * join", "peer leave", and "group terminated". Multicast will use those
+ * messages to update its list of candidates for content distribution. All
+ * other message types are application-specific.
*/
struct GNUNET_MessageHeader body;
@@ -227,12 +229,12 @@
GNUNET_NETWORK_STRUCT_END
-/**
+/**
* Replay a message from the multicast group.
*
- * @param rh replay handle identifying which replay operation was requested
- * @param msg replayed message, NULL if unknown/error
- * @param ec error code
+ * @param rh Replay handle identifying which replay operation was requested.
+ * @param msg Replayed message, NULL if unknown/error.
+ * @param ec Error code.
*/
void
GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
@@ -240,28 +242,31 @@
enum GNUNET_MULTICAST_ReplayErrorCode ec);
-/**
- * Handle that identifies a join request (to match calls to the
- * 'GNUNET_MULTICAST_MembershipChangeCallback' to the corresponding
- * calls to 'GNUNET_MULTICAST_join_decision').
+/**
+ * Handle that identifies a join request.
+ *
+ * Used to match calls to #GNUNET_MULTICAST_MembershipChangeCallback to the
+ * corresponding calls to GNUNET_MULTICAST_join_decision().
*/
struct GNUNET_MULTICAST_JoinHande;
-/**
- * Function to call with the decision made for a membership change
- * request. Must be called once and only once in response to an
- * invocation of the 'GNUNET_MULTICAST_MembershipChangeCallback'.
+/**
+ * Function to call with the decision made for a membership change request.
*
- * @param jh join request handle
- * @param join_response message to send in response to the joining peer;
+ * Must be called once and only once in response to an invocation of the
+ * #GNUNET_MULTICAST_MembershipChangeCallback.
+ *
+ * @param jh Join request handle.
+ * @param join_response Message to send in response to the joining peer;
* can also be used to redirect the peer to a different group at the
* application layer; this response is to be transmitted to the
* peer that issued the request even if admission is denied.
- * @param is_admitted GNUNET_OK if joining is approved, GNUNET_SYSERR if it is
disapproved;
- * GNUNET_NO for peers leaving
- * @param relay_count number of relays given
- * @param relays array of suggested peers that might be useful relays to use
+ * @param is_admitted #GNUNET_OK if joining is approved,
+ * #GNUNET_SYSERR if it is disapproved;
+ * #GNUNET_NO for peers leaving.
+ * @param relay_count Number of relays given.
+ * @param relays Array of suggested peers that might be useful relays to use
* when joining the multicast group (essentially a list of peers that
* are already part of the multicast group and might thus be willing
* to help with routing). If empty, only this local peer (which must
@@ -277,19 +282,21 @@
const struct GNUNET_PeerIdentity *relays);
-/**
- * Method called whenever another peer wants to join or has left a
- * multicast group. Implementations of this function must call
- * 'GNUNET_MULTICAST_join_decision' with the decision.
+/**
+ * Method called whenever another peer wants to join or has left a multicast
+ * group.
*
- * @param cls closure
- * @param peer identity of the peer that wants to join or leave
- * @param join_req application-dependent join message from the new user
- * (might, for example, contain a user
+ * Implementations of this function must call GNUNET_MULTICAST_join_decision()
+ * with the decision.
+ *
+ * @param cls Closure.
+ * @param peer Identity of the peer that wants to join or leave.
+ * @param join_req Application-dependent join message from the new user
+ * (might, for example, contain a user,
* bind user identity/pseudonym to peer identity, application-level
- * message to origin, etc.)
- * @param is_joining GNUNET_YES if the peer wants to join, GNUNET_NO if the
peer left
- * @param jh join handle to pass to 'GNUNET_MULTICAST_join_decison'
+ * message to origin, etc.).
+ * @param is_joining #GNUNET_YES if the peer wants to join, #GNUNET_NO if the
peer left.
+ * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison().
*/
typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
const struct
GNUNET_PeerIdentity *peer,
@@ -298,31 +305,31 @@
struct
GNUNET_MULTICAST_JoinHandle *jh);
-/**
+/**
* Handle to pass back for the answer of a membership test.
*/
struct GNUNET_MULTICAST_MembershipTestHandle;
-/**
+/**
* Call informing multicast about the decision taken for membership test.
*
- * @param mth handle that was given for the query
- * @param decision GNUNET_YES if peer was a member, GNUNET_NO if peer was not
a member,
- * GNUNET_SYSERR if we cannot answer the membership test
+ * @param mth Handle that was given for the query.
+ * @param decision #GNUNET_YES if peer was a member, #GNUNET_NO if peer was
not a member,
+ * #GNUNET_SYSERR if we cannot answer the membership test.
*/
void
GNUNET_MULTICAST_membership_test_answer (struct
GNUNET_MULTICAST_MembershipTestHandle *mth,
int decision);
-/**
+/**
* Method called to test if a member was in the group at a particular time.
*
- * @param cls closure
- * @param peer identity of the peer that we want to test
- * @param message_id message ID for which we want to do the test
- * @param mth handle to give to 'GNUNET_MULTICAST_membership_test_answer'
+ * @param cls Closure.
+ * @param peer Identity of the peer that we want to test.
+ * @param message_id Message ID for which we want to do the test.
+ * @param mth Handle to give to GNUNET_MULTICAST_membership_test_answer().
*/
typedef void (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls,
const struct
GNUNET_PeerIdentity *peer,
@@ -330,14 +337,14 @@
struct
GNUNET_MULTICAST_MembershipTestHandle *mth);
-/**
+/**
* Function called whenever a group member has transmitted a message
* to the origin (other than joining or leaving).
*
- * @param cls closure (set from GNUNET_MULTICAST_origin_start)
- * @param sender identity of the sender
- * @param response_id unique counter for the response from this sender to this
origin
- * @param msg message to the origin
+ * @param cls Closure (set from GNUNET_MULTICAST_origin_start).
+ * @param sender Identity of the sender.
+ * @param response_id Unique counter for the response from this sender to this
origin.
+ * @param msg Message to the origin.
*/
typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls,
const struct
GNUNET_PeerIdentity *sender,
@@ -345,48 +352,51 @@
const struct
GNUNET_MessageHeader *msg);
-/**
+/**
* Function called whenever a group member is receiving a message from
* the origin. If admission to the group is denied, this function is
- * called once with the response of the 'origin' (as given to
- * 'GNUNET_MULTICAST_join_decision') and then a second time with "NULL"
+ * called once with the response of the @e origin (as given to
+ * GNUNET_MULTICAST_join_decision()) and then a second time with NULL
* to indicate that the connection failed for good.
*
- * @param cls closure (set from GNUNET_MULTICAST_member_join)
- * @param message_id unique number of the message, 0 for response to join
request,
+ * @param cls Closure (set from GNUNET_MULTICAST_member_join())
+ * @param message_id Unique number of the message, 0 for response to join
request,
* normal message IDs in either direction start at 1.
- * @param msg message from the origin, NULL if the origin shut down
- * (or we were kicked out, and we should thus call
GNUNET_MULTICAST_member_leave next)
+ * @param msg Message from the origin, NULL if the origin shut down
+ * (or we were kicked out, and we should thus call
+ * GNUNET_MULTICAST_member_leave() next)
*/
typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls,
uint64_t message_id,
const struct
GNUNET_MULTICAST_MessageHeader *msg);
-/**
- * Start a multicast group. Will advertise the origin in the P2P
- * overlay network under the respective public key so that other peer
- * can find this peer to join it. Peers that issue
- * 'GNUNET_MULTICAST_member_join' can then transmit a join request to
- * either an existing group member (if the 'join_policy' is
- * permissive) or to the origin. If the joining is approved, the
- * member is cleared for 'replay' and will begin to receive messages
- * transmitted to the group. If joining is disapproved, the failed
- * candidate will be given a response. Members in the group can send
- * messages to the origin (one at a time).
+/**
+ * Start a multicast group.
*
- * @param cfg configuration to use
- * @param cls closure for the various callbacks that follow
+ * Will advertise the origin in the P2P overlay network under the respective
+ * public key so that other peer can find this peer to join it. Peers that
+ * issue GNUNET_MULTICAST_member_join() can then transmit a join request to
+ * either an existing group member (if the @a join_policy is permissive) or to
+ * the origin. If the joining is approved, the member is cleared for @e replay
+ * and will begin to receive messages transmitted to the group. If joining is
+ * disapproved, the failed candidate will be given a response. Members in the
+ * group can send messages to the origin (one at a time).
+ *
+ * @param cfg Configuration to use.
+ * @param cls Closure for the various callbacks that follow.
* @param priv_key ECC key that will be used to sign messages for this
* multicast session; public key is used to identify the
* multicast group; FIXME: we'll likely want to use
- * NOT the p521 curve here, but a cheaper one in the future
- * @param join_policy what is the membership policy of the group?
- * @param replay_cb function that can be called to replay a message
- * @param test_cb function multicast can use to test group membership
- * @param join_cb function called to approve / disapprove joining of a peer
- * @param response_cb function called with messages from group members
- * @return handle for the origin, NULL on error
+ * NOT the p521 curve here, but a cheaper one in the future.
+ * @param join_policy What is the membership policy of the group?
+ * @param replay_cb Function that can be called to replay a message.
+ * @param test_cb Function multicast can use to test group membership.
+ * @param join_cb Function called to approve / disapprove joining of a peer,
+ * and to inform about a leaving member.
+ * @param leave_cb Function called to inform about a leaving member.
+ * @param response_cb Function called with messages from group members.
+ * @return Handle for the origin, NULL on error.
*/
struct GNUNET_MULTICAST_Origin *
GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
@@ -399,21 +409,21 @@
GNUNET_MULTICAST_ResponseCallback response_cb);
-/**
+/**
* Handle for a request to send a message to all multicast group members
* (from the origin).
*/
struct GNUNET_MULTICAST_MulticastRequest;
-/**
+/**
* Send a message to the multicast group.
*
- * @param origin handle to the multicast group
- * @param size number of bytes to transmit
- * @param cb function to call to get the message
- * @param cb_cls closure for 'cb'
- * @return NULL on error (i.e. request already pending)
+ * @param origin Handle to the multicast group.
+ * @param size Number of bytes to transmit.
+ * @param cb Function to call to get the message.
+ * @param cb_cls Closure for @a cb.
+ * @return NULL on error (i.e. request already pending).
*/
struct GNUNET_MULTICAST_MulticastRequest *
GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin,
@@ -422,16 +432,16 @@
void *cb_cls);
-/**
+/**
* Cancel request for message transmission to multicast group.
*
- * @param mr request to cancel
+ * @param mr Request to cancel.
*/
void
GNUNET_MULTICAST_origin_to_all_cancel (struct
GNUNET_MULTICAST_MulticastRequest *mr);
-/**
+/**
* End a multicast group.
*
* @param origin multicast group to terminate
@@ -440,41 +450,42 @@
GNUNET_MULTICAST_origin_end (struct GNUNET_MULTICAST_Origin *origin);
-/**
- * Join a multicast group. The entity joining is always the local
- * peer. Further information about the candidate can be provided in
- * the 'join_req' message. If the join fails, the 'message_cb' is
- * invoked with a (failure) response and then with 'NULL'. If the
- * join succeeds, outstanding (state) messages and ongoing multicast
- * messages will be given to the 'message_cb' until the member decides
- * to leave the group. The 'test_cb' and 'replay_cb' functions may be
- * called at anytime by the multicast service to support relaying
- * messages to other members of the group.
+/**
+ * Join a multicast group.
*
- * @param cfg configuration to use
- * @param cls closure for callbacks
- * @param pub_key ECC key that identifies the group
- * @param max_known_message_id largest known message ID to the replay service;
+ * The entity joining is always the local peer. Further information about the
+ * candidate can be provided in the @a join_req message. If the join fails,
the
+ * @a message_cb is invoked with a (failure) response and then with NULL. If
+ * the join succeeds, outstanding (state) messages and ongoing multicast
+ * messages will be given to the @a message_cb until the member decides to
leave
+ * the group. The @a test_cb and @a replay_cb functions may be called at
+ * anytime by the multicast service to support relaying messages to other
+ * members of the group.
+ *
+ * @param cfg Configuration to use.
+ * @param cls Closure for callbacks.
+ * @param pub_key ECC key that identifies the group.
+ * @param max_known_message_id Largest known message ID to the replay service;
* all messages with IDs larger than this ID will be replayed if
* possible (lower IDs will be considered known and thus only
- * be replayed upon explicit request)
- * @param max_known_state_message_id largest known message ID with a non-zero
- * value for the 'state_delta'; state messages with
+ * be replayed upon explicit request).
+ * @param max_known_state_message_id Largest known message ID with a non-zero
+ * value for the @e state_delta; state messages with
* larger IDs than this value will be replayed with high priority
* (lower IDs will be considered known and thus only
- * be replayed upon explicit request)
- * @param replay_cb function that can be called to replay messages
+ * be replayed upon explicit request).
+ * @param replay_cb Function that can be called to replay messages
* this peer already knows from this group; NULL if this
- * client is unable to support replay
- * @param test_cb function multicast can use to test group membership
- * @param message_cb function to be called for all messages we
- * receive from the group, excluding those our replay_cb
- * already has
- * @param join_req application-dependent join message to be passed to origin
+ * client is unable to support replay.
+ * @param test_cb Function multicast can use to test group membership.
+ * @param message_cb Function to be called for all messages we
+ * receive from the group, excluding those our @a replay_cb
+ * already has.
+ * @param join_req Application-dependent join message to be passed to origin
* (might, for example, contain a user
* bind user identity/pseudonym to peer identity, application-level
- * message to origin, etc.)
- * @return handle for the member, NULL on error
+ * message to origin, etc.).
+ * @return Handle for the member, NULL on error.
*/
struct GNUNET_MULTICAST_Member *
GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
@@ -488,22 +499,23 @@
const struct GNUNET_MessageHeader *join_req);
-/**
+/**
* Handle for a replay request.
*/
struct GNUNET_MULTICAST_ReplayRequest;
-/**
- * Request a message to be replayed. Useful if messages below
- * the 'max_known_*_id's given when joining are needed and not
- * known to the client.
+/**
+ * Request a message to be replayed.
*
- * @param member membership handle
- * @param message_id ID of a message that this client would like to see
replayed
- * @param message_cb function to be called for the replayed message
- * @param message_cb_cls closure for 'message_cb'
- * @return replay request handle, NULL on error
+ * Useful if messages below the @e max_known_*_id's given when joining are
+ * needed and not known to the client.
+ *
+ * @param member Membership handle.
+ * @param message_id ID of a message that this client would like to see
replayed.
+ * @param message_cb Function to be called for the replayed message.
+ * @param message_cb_cls Closure for @a message_cb.
+ * @return Replay request handle, NULL on error.
*/
struct GNUNET_MULTICAST_ReplayRequest *
GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
@@ -512,38 +524,38 @@
void *message_cb_cls);
-/**
+/**
* Cancel a replay request.
*
- * @param rr request to cancel
+ * @param rr Request to cancel.
*/
void
GNUNET_MULTICAST_member_request_replay_cancel (struct
GNUNET_MULTICAST_ReplayRequest *rr);
-/**
- * Leave a mutlicast group.
+/**
+ * Leave a multicast group.
*
- * @param member membership handle
+ * @param member Membership handle.
*/
void
GNUNET_MULTICAST_member_leave (struct GNUNET_MULTICAST_Member *member);
-/**
+/**
* Handle for a message to be delivered to the origin.
*/
struct GNUNET_MULTICAST_ResponseRequest;
-/**
+/**
* Send a message to the origin of the multicast group.
*
- * @param member membership handle
- * @param size number of bytes we want to send to origin
- * @param cb callback to call to get the message
- * @param cb_cls closure for 'cb'
- * @return handle to cancel request, NULL on error (i.e. request already
pending)
+ * @param member Membership handle.
+ * @param size Number of bytes we want to send to origin.
+ * @param cb Callback to call to get the message.
+ * @param cb_cls Closure for @a cb.
+ * @return Handle to cancel request, NULL on error (i.e. request already
pending).
*/
struct GNUNET_MULTICAST_ResponseRequest *
GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member,
@@ -552,10 +564,10 @@
void *cb_cls);
-/**
+/**
* Cancel request for message transmission to origin.
*
- * @param rr request to cancel
+ * @param rr Request to cancel.
*/
void
GNUNET_MULTICAST_member_to_origin_cancel (struct
GNUNET_MULTICAST_ResponseRequest *rr);
Modified: gnunet/src/include/gnunet_psyc_service.h
===================================================================
--- gnunet/src/include/gnunet_psyc_service.h 2013-06-26 17:03:04 UTC (rev
27632)
+++ gnunet/src/include/gnunet_psyc_service.h 2013-06-26 17:12:59 UTC (rev
27633)
@@ -18,7 +18,7 @@
Boston, MA 02111-1307, USA.
*/
-/**
+/**
* @file include/gnunet_psyc_service.h
* @brief PSYC service; high-level access to the PSYC protocol
* note that clients of this API are NOT expected to
@@ -88,53 +88,53 @@
#include "gnunet_multicast_service.h"
-/**
+/**
* Version number of GNUnet-PSYC API.
*/
#define GNUNET_PSYC_VERSION 0x00000000
-/**
+/**
* Information flags for data fragments set via PSYC.
*/
enum GNUNET_PSYC_FragmentStatus
{
- /**
+ /**
* This is the first part of data for the given method call.
*/
GNUNET_PSYC_FS_FIRST = 1,
- /**
+ /**
* This is the last part of data for the given method call.
*/
GNUNET_PSYC_FS_LAST = 2,
- /**
+ /**
* OR'ed flags if payload is not fragmented.
*/
GNUNET_PSYC_FS_NOT_FRAGMENTED = (GNUNET_PSYC_FS_FIRST | GNUNET_PSYC_FS_LAST)
};
-/**
+/**
* Method called from PSYC upon receiving a message indicating a call
- * to a 'method'.
+ * to a @e method.
*
- * @param cls closure
- * @param full_method_name original method name from PSYC (may be more
- * specific than the registered method name due to try-and-slice
matching)
- * @param sender who transmitted the message (origin, except for messages
- * from one of the members to the origin)
- * @param message_id unique message counter for this message;
+ * @param cls Closure.
+ * @param full_method_name Original method name from PSYC (may be more
+ * specific than the registered method name due to try-and-slice
matching).
+ * @param sender Who transmitted the message (origin, except for messages
+ * from one of the members to the origin).
+ * @param message_id Unique message counter for this message;
* (unique only in combination with the given sender for
- * this channel)
- * @param group_generation group generation counter for this message
+ * this channel).
+ * @param group_generation Group generation counter for this message
* (always zero for messages from members to channel owner);
FIXME: needed?
- * @param data_off byte offset of 'data' in the overall data of the method
- * @param data_size number of bytes in 'data';
- * @param data data stream given to the method (might not be zero-terminated
- * if data is binary)
- * @param frag fragmentation status for the data
+ * @param data_off Byte offset of @a data in the overall data of the method.
+ * @param data_size Number of bytes in @a data.
+ * @param data Data stream given to the method (might not be zero-terminated
+ * if data is binary).
+ * @param frag Fragmentation status for the data.
*/
typedef int (*GNUNET_PSYC_Method)(void *cls,
const char *full_method_name,
@@ -147,28 +147,28 @@
enum GNUNET_PSYC_FragmentStatus frag);
-/**
+/**
* Handle for the channel of a PSYC group.
*/
struct GNUNET_PSYC_Channel;
-/**
- * Start a PSYC channel. Will create a multicast group identified by
- * the given ECC key. Messages recevied from group members will be
- * given to the respective handler methods. If a new member wants to
- * join a group, the "join" method handler will be invoked; the join
- * handler must then generate a "join" message to approve the joining
- * of the new member. The channel can also change group membership
- * without explicit requests. Note that PSYC doesn't itself "understand"
- * join or leave messages, the respective methods must call other
- * PSYC functions to inform PSYC about the meaning of the respective
- * events.
+/**
+ * Create a PSYC channel.
*
- * @param cfg configuration to use (to connect to PSYC service)
- * @param method functions to invoke on messages received from members,
- * typcially at least contains functions for 'join' and 'leave'.
- * @param method_cls closure for 'method'
+ * Will create a multicast group identified by the given ECC key. Messages
+ * received from group members will be given to the respective handler methods.
+ * If a new member wants to join a group, the "join" method handler will be
+ * invoked; the join handler must then generate a "join" message to approve the
+ * joining of the new member. The channel can also change group membership
+ * without explicit requests. Note that PSYC doesn't itself "understand" join
+ * or leave messages, the respective methods must call other PSYC functions to
+ * inform PSYC about the meaning of the respective events.
+ *
+ * @param cfg Configuration to use (to connect to PSYC service).
+ * @param method Function to invoke on messages received from members,
+ * typcially at least contains functions for @e join and @e
leave.
+ * @param method_cls Closure for @a method.
* @param priv_key ECC key that will be used to sign messages for this
* PSYC session; public key is used to identify the
* PSYC group; FIXME: we'll likely want to use
@@ -177,46 +177,46 @@
* directly, but rather look it up in GADS for groups
* managed by other users, or select a file with the private
* key(s) when setting up their own channels
- * @param join_policy what is the membership policy of the group?
+ * @param join_policy What is the membership policy of the group?
* Used to automate group management decisions.
- * @return handle for the channel, NULL on error
+ * @return Handle for the channel, NULL on error.
*/
struct GNUNET_PSYC_Channel *
-GNUNET_PSYC_channel_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
- GNUNET_PSYC_Method method,
- void *method_cls,
- const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
- enum GNUNET_MULTICAST_JoinPolicy join_policy);
+GNUNET_PSYC_channel_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ GNUNET_PSYC_Method method,
+ void *method_cls,
+ const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
+ enum GNUNET_MULTICAST_JoinPolicy join_policy);
-/**
+/**
* Possible operations on PSYC state (persistent) and variables (per message).
*/
enum GNUNET_PSYC_Operator
{
- /**
+ /**
* Replace the full state with the new value ("=").
*/
GNUNET_PSYC_SOT_SET_STATE = 0,
- /**
+ /**
* Delete the complete entry from the state (given data must be
- * empty). Equivalent to 'SET' with emtpy data, but more
+ * empty). Equivalent to @a SET with empty data, but more
* explicit ("=");
*/
GNUNET_PSYC_SOT_DELETE = 0,
- /**
+ /**
* Set the value of a variable to a new value (":").
*/
GNUNET_PSYC_SOT_SET_VARIABLE,
- /**
+ /**
* Add the given value to the set of values in the state ("+").
*/
GNUNET_PSYC_SOT_ADD_STATE,
- /**
+ /**
* Remove the given value from the set of values in the state ("-").
*/
GNUNET_PSYC_SOT_REMOVE_STATE
@@ -224,23 +224,23 @@
};
-/**
- * Update channel state (or set a variable). The state of a channel
- * must fit into the memory of each member (and the channel); large
- * values that require streaming must only be passed as the stream
- * arguments to methods. State updates might not be transmitted to
- * group members until the next call to
- * 'GNUNET_PSYC_channel_notify_transmit_ready'. Variable updates must
- * be given just before the call to the respective method that needs
- * the variables.
+/**
+ * Update channel state (or set a variable).
*
- * @param channel handle to the PSYC group / channel
- * @param full_state_name name of the field in the channel state to change
- * @param type kind of update operation (add, remove, replace, delete)
- * @param data_size number of bytes in data
- * @param data new state value
- * @return GNUNET_OK on success, GNUNET_SYSERR on internal error
- * (i.e. state too large)
+ * The state of a channel must fit into the memory of each member (and the
+ * channel); large values that require streaming must only be passed as the
+ * stream arguments to methods. State updates might not be transmitted to
group
+ * members until the next call to GNUNET_PSYC_channel_notify_transmit_ready().
+ * Variable updates must be given just before the call to the respective method
+ * that needs the variables.
+ *
+ * @param channel Handle to the PSYC group / channel.
+ * @param full_state_name Name of the field in the channel state to change.
+ * @param type Kind of update operation (add, remove, replace, delete).
+ * @param data_size Number of bytes in data.
+ * @param data New state value.
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on internal error
+ * (i.e. state too large).
*/
int
GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel,
@@ -250,24 +250,25 @@
const void *data);
-/**
- * Function called to provide data for a transmission via PSYC. Note
- * that returning GNUNET_OK or GNUNET_SYSERR (but not GNUNET_NO)
+/**
+ * Function called to provide data for a transmission via PSYC.
+ *
+ * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO)
* invalidates the respective transmission handle.
*
- * @param cls closure
- * @param message_id set to the unique message ID that was generated for
- * this message
- * @param group_generation set to the group generation used for this
- * message
- * @param data_size initially set to the number of bytes available in 'data',
- * should be set to the number of bytes written to data (IN/OUT)
- * @param data where to write the body of the message to give to the method;
- * function must copy at most '*data_size' bytes to 'data'.
- * @return GNUNET_SYSERR on error (fatal, aborts transmission)
- * GNUNET_NO on success, if more data is to be transmitted later
- * (should be used if 'data_size' was not big enough to take all the
data)
- * GNUNET_YES if this completes the transmission (all data supplied)
+ * @param cls Closure.
+ * @param message_id Set to the unique message ID that was generated for
+ * this message.
+ * @param group_generation Set to the group generation used for this
+ * message.
+ * @param data_size[in,out] Initially set to the number of bytes available in
@a data,
+ * should be set to the number of bytes written to data (IN/OUT).
+ * @param data[out] Where to write the body of the message to give to the
method;
+ * function must copy at most @a *data_size bytes to @a data.
+ * @return #GNUNET_SYSERR on error (fatal, aborts transmission)
+ * #GNUNET_NO on success, if more data is to be transmitted later
+ * (should be used if @a *data_size was not big enough to take all the
data)
+ * #GNUNET_YES if this completes the transmission (all data supplied)
*/
typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls,
uint64_t message_id,
@@ -276,22 +277,22 @@
void *data);
-/**
+/**
* Handle for a pending PSYC transmission operation.
*/
struct GNUNET_PSYC_ChannelTransmitHandle;
-/**
+/**
* Send a message to call a method to all members in the PSYC channel.
*
- * @param channel handle to the PSYC multicast group
- * @param increment_group_generation GNUNET_YES if we need to increment
- * the group generation counter after transmitting this message
- * @param full_method_name which method should be invoked
- * @param notify function to call to obtain the arguments
- * @param notify_cls closure for 'notify'
- * @return transmission handle, NULL on error (i.e. more than one request
queued)
+ * @param channel Handle to the PSYC multicast group.
+ * @param increment_group_generation #GNUNET_YES if we need to increment
+ * the group generation counter after transmitting this message.
+ * @param full_method_name Which method should be invoked.
+ * @param notify Function to call to obtain the arguments.
+ * @param notify_cls Closure for @a notify.
+ * @return Transmission handle, NULL on error (i.e. more than one request
queued).
*/
struct GNUNET_PSYC_ChannelTransmitHandle *
GNUNET_PSYC_channel_notify_transmit_ready (struct GNUNET_PSYC_Channel *channel,
@@ -301,69 +302,70 @@
void *notify_cls);
-/**
+/**
* Abort transmission request to channel.
*
- * @param th handle of the request that is being aborted
+ * @param th Handle of the request that is being aborted.
*/
void
GNUNET_PSYC_channel_notify_transmit_ready_cancel (struct
GNUNET_PSYC_ChannelTransmitHandle *th);
-/**
- * End a PSYC channel.
+/**
+ * Destroy a PSYC channel.
*
- * @param channel PSYC channel to terminate
+ * @param channel PSYC channel to terminate.
*/
-void
-GNUNET_PSYC_channel_end (struct GNUNET_PSYC_Channel *channel);
+tvoid
+GNUNET_PSYC_channel_destroy (struct GNUNET_PSYC_Channel *channel);
-/**
+/**
* Handle to access PSYC group operations for all members.
*/
struct GNUNET_PSYC_Group;
-/**
- * Convert 'channel' to a 'group' handle to access the 'group' APIs.
+/**
+ * Convert @a channel to a @e group handle to access the @e group APIs.
*
- * @param channel channel handle
- * @return group handle, valid for as long as 'channel' is valid
+ * @param channel Channel handle.
+ * @return Group handle, valid for as long as @a channel is valid.
*/
struct GNUNET_PSYC_Group *
GNUNET_PSYC_channel_get_group (struct GNUNET_PSYC_Channel *channel);
-/**
- * Convert 'member' to a 'group' handle to access the 'group' APIs.
+/**
+ * Convert @a member to a @e group handle to access the @e group APIs.
*
- * @param member membership handle
- * @return group handle, valid for as long as 'member' is valid
+ * @param member Membership handle.
+ * @return Group handle, valid for as long as @a member is valid.
*/
struct GNUNET_PSYC_Group *
GNUNET_PSYC_member_get_group (struct GNUNET_PSYC_Member *member);
-/**
- * Add a member to the group. Note that this will NOT generate any
- * PSYC traffic, it will merely update the local data base to modify
- * how we react to 'membership test' queries. The channel still needs to
- * explicitly transmit a 'join' message to notify other group members
- * and they then also must still call this function in their respective
- * methods handling the 'join' message. This way, how 'join' and 'leave'
- * operations are exactly implemented is still up to the application;
- * for example, there might be a 'leave_all' method to kick out everyone.
+/**
+ * Add a member to the group.
*
+ * Note that this will NOT generate any PSYC traffic, it will merely update the
+ * local data base to modify how we react to <em>membership test</em> queries.
The
+ * channel still needs to explicitly transmit a @e join message to notify other
+ * group members and they then also must still call this function in their
+ * respective methods handling the @e join message. This way, how @e join and
+ * @e leave operations are exactly implemented is still up to the application;
+ * for example, there might be a @e leave_all method to kick out everyone.
+ *
* Note that group members are explicitly trusted to execute such
* methods correctly; not doing so correctly will result in either
* denying members access or offering access to group data to
* non-members.
*
- * @param group group handle
- * @param member which peer to add
- * @param message_id message ID for the message that changed the membership
- * @param group_generation the generation ID where the change went into effect
+ * @param group Group handle.
+ * @param member Which peer to add.
+ * @param message_id Message ID for the message that changed the membership.
+ * @param group_generation The generation ID where the change went into effect.
*/
void
GNUNET_PSYC_group_member_add (struct GNUNET_PSYC_Group *group,
@@ -372,25 +374,26 @@
uint64_t group_generation);
-/**
- * Remove a member from the group. Note that this will NOT generate any
- * PSYC traffic, it will merely update the local data base to modify
- * how we react to 'membership test' queries. The channel still needs to
- * explicitly transmit a 'leave' message to notify other group members
- * and they then also must still call this function in their respective
- * methods handling the 'leave' message. This way, how 'join' and 'leave'
- * operations are exactly implemented is still up to the application;
- * for example, there might be a 'leave_all' message to kick out everyone.
+/**
+ * Remove a member from the group.
*
+ * Note that this will NOT generate any PSYC traffic, it will merely update the
+ * local data base to modify how we react to <em>membership test</em> queries.
The
+ * channel still needs to explicitly transmit a @e leave message to notify
other
+ * group members and they then also must still call this function in their
+ * respective methods handling the @e leave message. This way, how @e join and
+ * @e leave operations are exactly implemented is still up to the application;
+ * for example, there might be a @e leave_all message to kick out everyone.
+ *
* Note that group members are explicitly trusted to perform these
* operations correctly; not doing so correctly will result in either
* denying members access or offering access to group data to
* non-members.
*
- * @param group group handle
- * @param member which peer to remove
- * @param message_id message ID for the message that changed the membership
- * @param group_generation the generation ID where the change went into effect
+ * @param group Group handle.
+ * @param member Which peer to remove.
+ * @param message_id Message ID for the message that changed the membership.
+ * @param group_generation The generation ID where the change went into effect.
*/
void
GNUNET_PSYC_group_member_remove (struct GNUNET_PSYC_Group *group,
@@ -399,16 +402,16 @@
uint64_t group_generation);
-/**
- * Function called to inform a member about state changes for a
- * channel. Note that (for sets) only the delta is communicated, not
- * the full state.
+/**
+ * Function called to inform a member about state changes for a channel.
*
- * @param cls closure
- * @param full_state_name full name of the state
- * @param type how to interpret the change
- * @param state_value information about the new state
- * @param state_value_size number of bytes in 'state_value'
+ * Note that (for sets) only the delta is communicated, not the full state.
+ *
+ * @param cls Closure.
+ * @param full_state_name Full name of the state.
+ * @param type How to interpret the change.
+ * @param state_value Information about the new state.
+ * @param state_value_size Number of bytes in @a state_value.
*/
typedef void (*GNUNET_PSYC_StateCallback)(void *cls,
const char *full_state_name,
@@ -417,48 +420,49 @@
size_t state_value_size);
-/**
+/**
* Descriptor for an event handler handling PSYC state updates.
*/
struct GNUNET_PSYC_StateHandler
{
- /**
- * Name of the state this handler calls about, used in try-and-slice
matching.
+ /**
+ * Name of the state variable this handler calls about, used in
try-and-slice matching.
*/
const char *state_name;
- /**
+ /**
* Function to call whenever the respective state changes.
*/
GNUNET_PSYC_StateCallback event_handler;
- /**
- * Closure for the 'event_handler' function.
+ /**
+ * Closure for the @a event_handler function.
*/
void *event_handler_cls;
};
-/**
- * Join a PSYC group. The entity joining is always the local peer.
- * The user must immediately use the 'GNUNET_PSYC_member_send_to_host'
- * (and possibly 'GNUNET_PSYC_member_host_variable_set') functions to
- * transmit a 'join_msg' to the channel; if the join request succeeds,
- * the channel state (and 'recent' method calls) will be replayed to
- * the joining member. There is no explicit notification on failure
- * (as the channel may simply take days to approve, and disapproval is
- * simply being ignored).
+/**
+ * Join a PSYC group.
*
- * @param cfg configuration to use
+ * The entity joining is always the local peer. The user must immediately use
+ * the GNUNET_PSYC_member_send_to_host() (and possibly
+ * GNUNET_PSYC_member_host_variable_set()) functions to transmit a @e join_msg
to
+ * the channel; if the join request succeeds, the channel state (and @e recent
+ * method calls) will be replayed to the joining member. There is no explicit
+ * notification on failure (as the channel may simply take days to approve, and
+ * disapproval is simply being ignored).
+ *
+ * @param cfg Configuration to use.
* @param pub_key ECC key that identifies the channel we wish to join
- * @param method function to invoke on messages received from the channel,
- * typcially at least contains functions for 'join' and 'leave'.
- * @param method_cls closure for 'method'
- * @param state_count number of state handlers
- * @param state_handlers array of state event handlers
- * @return handle for the member, NULL on error
+ * @param method Function to invoke on messages received from the channel,
+ * typically at least contains functions for @e join and @e
leave.
+ * @param method_cls Closure for @a method.
+ * @param state_count Number of @a state_handlers.
+ * @param state_handlers Array of state event handlers.
+ * @return Handle for the member, NULL on error.
*/
struct GNUNET_PSYC_Member *
GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
@@ -469,51 +473,54 @@
struct GNUNET_PSYC_StateHandler *state_handlers);
-/**
- * Leave a multicast group. Will terminate the connection to the PSYC
- * service. Polite clients should first explicitly send a 'leave'
- * request (via 'GNUNET_PSYC_member_send_to_host').
+/**
+ * Leave a multicast group.
*
+ * Will terminate the connection to the PSYC service. Polite clients should
+ * first explicitly send a @e leave request (via
+ * GNUNET_PSYC_member_send_to_host()).
+ *
* @param member membership handle
*/
void
GNUNET_PSYC_member_leave (struct GNUNET_PSYC_Member *member);
-/**
+/**
* Function called to provide data for a transmission to the channel
- * owner (aka the 'host' of the channel). Note that returning
- * GNUNET_OK or GNUNET_SYSERR (but not GNUNET_NO) invalidates the
- * respective transmission handle.
+ * owner (aka the @e host of the channel).
*
- * @param cls closure
- * @param data_size initially set to the number of bytes available in 'data',
- * should be set to the number of bytes written to data (IN/OUT)
- * @param data where to write the body of the message to give to the method;
- * function must copy at most '*data_size' bytes to 'data'.
- * @return GNUNET_SYSERR on error (fatal, aborts transmission)
- * GNUNET_NO on success, if more data is to be transmitted later
- * GNUNET_YES if this completes the transmission (all data supplied)
+ * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO)
+ * invalidates the respective transmission handle.
+ *
+ * @param cls Closure.
+ * @param data_size[in,out] Initially set to the number of bytes available in
@a data,
+ * should be set to the number of bytes written to data (IN/OUT).
+ * @param data[out] Where to write the body of the message to give to the
method;
+ * function must copy at most @a *data_size bytes to @a data.
+ * @return #GNUNET_SYSERR on error (fatal, aborts transmission).
+ * #GNUNET_NO on success, if more data is to be transmitted later.
+ * #GNUNET_YES if this completes the transmission (all data supplied).
*/
typedef int (*GNUNET_PSYC_OriginReadyNotify)(void *cls,
size_t *data_size,
char *data);
-/**
+/**
* Handle for a pending PSYC transmission operation.
*/
struct GNUNET_PSYC_OriginTransmitHandle;
-/**
+/**
* Request a message to be sent to the channel origin.
*
- * @param member membership handle
- * @param method_name which (PSYC) method should be invoked (on host)
- * @param notify function to call when we are allowed to transmit (to get data)
- * @param notify_cls closure for 'notify'
- * @return transmission handle, NULL on error (i.e. more than one request
queued)
+ * @param member Membership handle.
+ * @param method_name Which (PSYC) method should be invoked (on host).
+ * @param notify Function to call when we are allowed to transmit (to get
data).
+ * @param notify_cls Closure for @a notify.
+ * @return Transmission handle, NULL on error (i.e. more than one request
queued).
*/
struct GNUNET_PSYC_OriginTransmitHandle *
GNUNET_PSYC_member_send_to_origin (struct GNUNET_PSYC_Member *member,
@@ -522,17 +529,19 @@
void *notify_cls);
-/**
+/**
* Set a (temporary, ":") variable for the next message being transmitted
- * via 'GNUNET_PSYC_member_send_to_host'. If 'GNUNET_PSYC_member_send_to_host'
- * is called and then cancelled, all variables that were set using this
- * function will be unset (lost/forgotten). To clear a variable state after
- * setting it, you can also call this function again with NULL/0 for the value.
+ * via GNUNET_PSYC_member_send_to_host().
*
- * @param member membership handle
- * @param variable_name name of the variable to set
- * @param value value to set for the given variable
- * @param value_size number of bytes in 'value'
+ * If GNUNET_PSYC_member_send_to_host() is called and then cancelled, all
+ * variables that were set using this function will be unset (lost/forgotten).
+ * To clear a variable state after setting it, you can also call this function
+ * again with NULL/0 for the @a value.
+ *
+ * @param member Membership handle.
+ * @param variable_name Name of the variable to set.
+ * @param value Value to set for the given variable.
+ * @param value_size Number of bytes in @a value.
*/
uint64_t
GNUNET_PSYC_member_origin_variable_set (struct GNUNET_PSYC_Member *member,
@@ -541,40 +550,40 @@
size_t value_size);
-/**
+/**
* Abort transmission request to origin.
*
- * @param th handle of the request that is being aborted
+ * @param th Handle of the request that is being aborted.
*/
void
GNUNET_PSYC_member_send_to_origin_cancel (struct
GNUNET_PSYC_OriginTransmitHandle *th);
-/**
+/**
* Handle to a story telling operation.
*/
struct GNUNET_PSYC_Story;
-/**
- * Request to be told the message history of the channel. Historic
- * messages (but NOT the state at the time) will be replayed (given to
- * the normal method handlers) if available and if access is
- * permitted.
+/**
+ * Request to be told the message history of the channel.
*
- * @param member which channel should be replayed?
- * @param start earliest interesting point in history
- * @param end last (exclusive) interesting point in history
- * @param method function to invoke on messages received from the story
- * @param method_cls closure for 'method'
- * @param finish_cb function to call when the requested story has been fully
+ * Historic messages (but NOT the state at the time) will be replayed (given to
+ * the normal method handlers) if available and if access is permitted.
+ *
+ * @param member Which channel should be replayed?
+ * @param start Earliest interesting point in history.
+ * @param end Last (exclusive) interesting point in history.
+ * @param method Function to invoke on messages received from the story.
+ * @param method_cls Closure for @a method.
+ * @param finish_cb Function to call when the requested story has been fully
* told (counting message IDs might not suffice, as some messages
* might be secret and thus the listener would not know the story is
* finished without being told explicitly); once this function
* has been called, the client must not call
- * 'GNUNET_PSYC_member_story_tell_cancel' anymore
- * @param finish_cb_cls closure to finish_cb
- * @return handle to cancel story telling operation
+ * GNUNET_PSYC_member_story_tell_cancel() anymore.
+ * @param finish_cb_cls Closure to finish_cb.
+ * @return Handle to cancel story telling operation.
*/
struct GNUNET_PSYC_Story *
GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member,
@@ -586,35 +595,37 @@
void *finish_cb_cls);
-/**
- * Abort story telling. This function must not be called from within
- * method handlers (as given to 'GNUNET_PSYC_member_join') of the
- * member.
+/**
+ * Abort story telling.
*
- * @param story story telling operation to stop
+ * This function must not be called from within method handlers (as given to
+ * GNUNET_PSYC_member_join()) of the member.
+ *
+ * @param story Story telling operation to stop.
*/
void
GNUNET_PSYC_member_story_tell_cancel (struct GNUNET_PSYC_Story *story);
-/**
- * Call the given callback on all matching values (including
- * variables) in the channel state. The callback is invoked
- * synchronously on all matching states (as the state is fully
- * replicated in the library in this process; channel states should be
+/**
+ * Call the given callback on all matching values (including variables) in the
+ * channel state.
+ *
+ * The callback is invoked synchronously on all matching states (as the state
is
+ * fully replicated in the library in this process; channel states should be
* small, large data is to be passed as streaming data to methods).
*
- * A name matches if it includes the 'state_name' prefix, thus
- * requesting the empty state ("") will match all values; requesting
- * "a_b" will also return values stored under "a_b_c".
+ * A name matches if it includes the @a state_name prefix, thus requesting the
+ * empty state ("") will match all values; requesting "a_b" will also return
+ * values stored under "a_b_c".
*
- * @param member membership handle
- * @param state_name name of the state to query (full name
- * might be longer, this is only the prefix that must match)
- * @param cb function to call on the matching state values
- * @param cb_cls closure for 'cb'
- * @return message ID for which the state was returned (last seen
- * message ID)
+ * @param member Membership handle.
+ * @param state_name Name of the state to query (full name
+ * might be longer, this is only the prefix that must match).
+ * @param cb Function to call on the matching state values.
+ * @param cb_cls Closure for @a cb.
+ * @return Message ID for which the state was returned (last seen
+ * message ID).
*/
uint64_t
GNUNET_PSYC_member_state_get_all (struct GNUNET_PSYC_Member *member,
@@ -623,23 +634,24 @@
void *cb_cls);
-/**
+/**
* Obtain the current value of the best-matching value in the state
- * (including variables). Note that variables are only valid during a
- * GNUNET_PSYC_Method invocation, as variables are only valid for the
- * duration of a method invocation.
+ * (including variables).
*
+ * Note that variables are only valid during a #GNUNET_PSYC_Method invocation,
as
+ * variables are only valid for the duration of a method invocation.
+ *
* If the requested variable name does not have an exact state in
* the state, the nearest less-specific name is matched; for example,
* requesting "a_b" will match "a" if "a_b" does not exist.
*
- * @param member membership handle
- * @param variable_name name of the variable to query
- * @param return_value_size set to number of bytes in variable,
+ * @param member Membership handle.
+ * @param variable_name Name of the variable to query.
+ * @param return_value_size Set to number of bytes in variable,
* needed as variables might contain binary data and
- * might also not be 0-terminated; set to 0 on errors
+ * might also not be 0-terminated; set to 0 on errors.
* @return NULL on error (no matching state or variable), pointer
- to the respective value otherwise
+ to the respective value otherwise.
*/
const void *
GNUNET_PSYC_member_state_get (struct GNUNET_PSYC_Member *member,
Modified: gnunet/src/include/gnunet_psycstore_service.h
===================================================================
--- gnunet/src/include/gnunet_psycstore_service.h 2013-06-26 17:03:04 UTC
(rev 27632)
+++ gnunet/src/include/gnunet_psycstore_service.h 2013-06-26 17:12:59 UTC
(rev 27633)
@@ -18,10 +18,10 @@
Boston, MA 02111-1307, USA.
*/
-/**
+/**
* @file include/gnunet_psycstore_service.h
* @brief PSYCstore service; implements persistent storage for the PSYC service
- * @author tg
+ * @author tg(x)
* @author Christian Grothoff
*/
#ifndef GNUNET_PSYCSTORE_SERVICE_H
@@ -37,18 +37,18 @@
#include "gnunet_util_lib.h"
-/**
+/**
* Version number of GNUnet PSYCstore API.
*/
#define GNUNET_PSYCSTORE_VERSION 0x00000000
-/**
+/**
* Handle for a PSYCstore
*/
struct GNUNET_PSYCSTORE_Handle;
-/**
+/**
* Connect to the PSYCstore service.
*
* @param cfg Configuration to use.
@@ -59,7 +59,7 @@
GNUNET_PSYCSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
-/**
+/**
* Disconnect from the PSYCstore service.
*
* @param h Handle for the connection.
@@ -68,22 +68,23 @@
GNUNET_PSYCSTORE_disconnect (struct GNUNET_PSYCSTORE_Handle *h);
-/**
+/**
* Handle for an operation on the PSYCSTORE (useful to cancel the operation).
*/
struct GNUNET_PSYCSTORE_OperationHandle;
-/**
- *
- * @param result GNUNET_SYSERR on error,
- * GNUNET_YES on success or if the peer was a member,
- * GNUNET_NO if the peer was not a member
+/**
+ * Function called with the result of an asynchronous operation.
+; *
+ * @param result #GNUNET_SYSERR on error,
+ * #GNUNET_YES on success or if the peer was a member,
+ * #GNUNET_NO if the peer was not a member
*/
typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
int result);
-/**
+/**
* Store join/leave events for a PSYC channel in order to be able to answer
* membership test queries later.
*
@@ -91,7 +92,7 @@
* @param channel_id ID of the channel where the event happened.
* @param message_id ID of the message in which this event was announced.
* @param peer Identity of joining/leaving peer.
- * @param did_join GNUNET_YES on join, GNUNET_NO on leave.
+ * @param did_join #GNUNET_YES on join, #GNUNET_NO on leave.
* @param ccb Callback to call with the result of the storage operation.
* @param ccb_cls Closure for the callback.
*
@@ -107,12 +108,13 @@
void *ccb_cls);
-/**
+/**
* Test if a peer was a member of the channel when the message with the
- * specified ID was sent to the channel. This is useful in case of
- * retransmissions to check if the peer was authorized to see the requested
- * message.
+ * specified ID was sent to the channel.
*
+ * This is useful in case of retransmissions to check if the peer was
authorized
+ * to see the requested message.
+ *
* @param h Handle for the PSYCstore.
* @param channel_id The channel we are interested in.
* @param message_id Message ID to check.
@@ -121,7 +123,8 @@
* @param ccb_cls Closure for the callback.
*
* @return Operation handle that can be used to cancel the operation.
- */struct GNUNET_PSYCSTORE_OperationHandle *
+ */
+struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
uint64_t message_id,
@@ -130,6 +133,17 @@
void *ccb_cls);
+/**
+ * Store a message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel the message belongs to.
+ * @param message_id Message ID to store.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
@@ -138,11 +152,29 @@
void *ccb_cls);
+/**
+ * Function called with the result of a GNUNET_PSYCSTORE_message_get() call.
+ *
+ * @param cls Closure.
+ * @param message_id ID of the message.
+ * @param message The retrieved message.
+ */
typedef void (*GNUNET_PSYCSTORE_MessageResultCallback)(void *cls,
uint64_t message_id,
const struct
GNUNET_MULTICAST_MessageHeader *message);
+/**
+ * Retrieve a message by ID.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param message_id Message ID to check.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
@@ -151,6 +183,16 @@
void *rcb_cls);
+/**
+ * Get latest message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
@@ -158,30 +200,73 @@
void *rcb_cls);
+/**
+ * Store a state variable.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_state_set (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
- const char *state_name,
+ const char *name,
size_t size,
const void *value,
GNUNET_PSYCSTORE_ContinuationCallback ccb,
void *ccb_cls);
+/**
+ * Function called with the value of a state variable.
+ *
+ * @param cls Closure.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+t *
+ */
typedef void (*GNUNET_PSYCSTORE_StateResultCallback)(void *cls,
- const char *state_name,
+ const char *name,
size_t size,
const void *value);
+/**
+ * Retrieve the given state variable for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable to get.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
- const char *state_name,
+ const char *name,
GNUNET_PSYCSTORE_StateResultCallback rcb,
void *rcb_cls);
+/**
+ * Retrieve all state variables for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
struct GNUNET_PSYCSTORE_OperationHandle *
GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
const struct GNUNET_HashCode *channel_id,
@@ -189,6 +274,11 @@
void *rcb_cls);
+/**
+ * Cancel an operation.
+ *
+ * @param oh Handle for the operation to cancel.
+ */
void
GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle
*oh);
Modified: gnunet/src/include/gnunet_social_service.h
===================================================================
--- gnunet/src/include/gnunet_social_service.h 2013-06-26 17:03:04 UTC (rev
27632)
+++ gnunet/src/include/gnunet_social_service.h 2013-06-26 17:12:59 UTC (rev
27633)
@@ -21,7 +21,7 @@
/**
* @file include/gnunet_social_service.h
* @brief Social service; implements social functionality using the PSYC
service.
- * @author tg
+ * @author tg(x)
* @author Christian Grothoff
*/
#ifndef GNUNET_SOCIAL_SERVICE_H
@@ -74,7 +74,7 @@
/**
* Method called from SOCIAL upon receiving a message indicating a call
- * to a 'method'.
+ * to a @a method.
*
* @param cls Closure.
* @param full_method_name Original method name from PSYC (may be more
@@ -83,11 +83,11 @@
* @param message_id Unique message counter for this message
* (unique only in combination with the given sender for
* this channel).
- * @param data_off Byte offset of 'data' in the overall data of the method.
- * @param data_size Number of bytes in 'data'.
- * @param data data stream given to the method (might not be zero-terminated
- * if data is binary)
- * @param frag fragmentation status for the data
+ * @param data_off Byte offset of @a data in the overall data of the method.
+ * @param data_size Number of bytes in @a data.
+ * @param data Data stream given to the method (might not be zero-terminated
+ * if data is binary).
+ * @param frag Fragmentation status for the data.
*/
typedef int (*GNUNET_SOCIAL_Method)(void *cls,
const char *full_method_name,
@@ -142,9 +142,9 @@
* Create an ego using the private key from the given file. If the file does
* not exist, a fresh key is created.
*
- * @param keyfile name of the file with the private key for the ego,
- * NULL for ephemeral egos
- * @return handle to the ego, NULL on error
+ * @param keyfile Name of the file with the private key for the ego,
+ * NULL for ephemeral egos.
+ * @return Handle to the ego, NULL on error.
*/
struct GNUNET_SOCIAL_Ego *
GNUNET_SOCIAL_ego_create (const char *keyfile);
@@ -153,7 +153,7 @@
/**
* Destroy a handle to an ego.
*
- * @param ego ego to destroy
+ * @param ego Ego to destroy.
*/
void
GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
@@ -162,16 +162,16 @@
/**
* Function called asking for nym to be admitted to the place.
*
- * Should call either 'GNUNET_SOCIAL_home_admit' or
- * 'GNUNET_SOCIAL_home_reject_entry' (possibly asynchronously). If this owner
+ * Should call either GNUNET_SOCIAL_home_admit() or
+ * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously). If this owner
* cannot decide, it is fine to call neither function, in which case hopefully
- * some other owner of the home exists that will make the decision. The 'nym'
- * reference remains valid until the 'GNUNET_SOCIAL_FarewellCallback' is
invoked
+ * some other owner of the home exists that will make the decision. The @a nym
+ * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
* for it.
*
* @param cls Closure.
* @param nym Handle for the user who wants to join.
- * @param join_msg_size Number of bytes in 'join_msg'.
+ * @param join_msg_size Number of bytes in @a join_msg.
* @param join_msg Payload given on join (e.g. a password).
*/
typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
@@ -181,10 +181,10 @@
/**
- * Function called when a 'nym' leaves the place.
+ * Function called when a @a nym leaves the place.
*
- * This is also called if the 'nym' was never given permission to enter
- * (i.e. the 'nym' stopped asking to get in).
+ * This is also called if the @a nym was never given permission to enter
+ * (i.e. the @a nym stopped asking to get in).
*
* @param cls Closure.
* @param nym Handle for the user who left.
@@ -197,8 +197,8 @@
* Enter a home where guests (nyms) can be hosted.
*
* A home is created upon first entering, and exists until
- * 'GNUNET_SOCIAL_home_destroy' is called. It can also be left temporarily
using
- * 'GNUNET_SOCIAL_home_leave'.
+ * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily
using
+ * GNUNET_SOCIAL_home_leave().
*
* @param cfg Configuration to contact the social service.
* @param home_keyfile File with the private key for the home,
@@ -209,7 +209,7 @@
* @param slicer Slicer to handle guests talking.
* @param listener_cb Function to handle new nyms that want to join.
* @param farewell_cb Function to handle departing nyms.
- * @param cls Closure for 'listener_cb' and 'farewell_cb'.
+ * @param cls Closure for @a listener_cb and @a farewell_cb.
* @return Handle for a new home.
*/
struct GNUNET_SOCIAL_Home *
@@ -224,12 +224,12 @@
/**
- * Admit 'nym' to the 'home'.
+ * Admit @a nym to the @a home.
*
- * The 'nym' reference will remain valid until either the home is destroyed or
- * 'nym' leaves.
+ * The @a nym reference will remain valid until either the home is destroyed or
+ * @a nym leaves.
*
- * @param home Home to allow 'nym' to join.
+ * @param home Home to allow @a nym to join.
* @param nym Handle for the entity that wants to join.
*/
void
@@ -238,10 +238,10 @@
/**
- * Throw 'nym' out of the 'home'.
+ * Throw @a nym out of the @a home.
*
- * The 'nym' reference will remain valid until the
- * 'GNUNET_SOCIAL_FarewellCallback' is invoked,
+ * The @a nym reference will remain valid until the
+ * #GNUNET_SOCIAL_FarewellCallback is invoked,
* which should be very soon after this call.
*
* @param home Home to eject nym from.
@@ -253,12 +253,12 @@
/**
- * Refuse 'nym' entry into the 'home'.
+ * Refuse @a nym entry into the @a home.
*
- * @param home Home to disallow 'nym' to join.
+ * @param home Home to disallow @a nym to join.
* @param nym Handle for the entity that wanted to join.
* @param method Method name to invoke on caller.
- * @param message_size Number of bytes in 'message' for method.
+ * @param message_size Number of bytes in @a message for method.
* @param message Rejection message to send back.
*
* FIXME: allow setting variables as well for the message
@@ -274,7 +274,7 @@
/**
* Get the identity of a user.
*
- * Suitable, for example, to be used with 'GNUNET_NAMESTORE_zone_to_name'.
+ * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
*
* @param nym Pseudonym to map to a cryptographic identifier.
* @param identity Set to the identity of the nym (short hash of the public
key).
@@ -299,13 +299,13 @@
/**
* (Re)decorate the home by changing objects in it.
*
- * If the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then the decoration only
+ * If the operation is #GNUNET_PSYC_SOT_SET_VARIABLE then the decoration only
* applies to the next announcement by the home owner.
*
* @param home The home to decorate.
* @param operation Operation to perform on the object.
* @param object_name Name of the object to modify.
- * @param object_value_size Size of the given 'object_value'.
+ * @param object_value_size Size of the given @a object_value.
* @param object_value Value to use for the modification.
*/
void
@@ -330,7 +330,7 @@
* @param home Home to address the announcement to.
* @param full_method_name Method to use for the announcement.
* @param notify Function to call to get the payload of the announcement.
- * @param notify_cls Closure for 'notify'.
+ * @param notify_cls Closure for @a notify.
* @return NULL on error (announcement already in progress?).
*/
struct GNUNET_SOCIAL_Announcement *
@@ -353,8 +353,8 @@
* Convert our home to a place so we can access it via the place API.
*
* @param home Handle for the home.
- * @return Place handle for the same home, valid as long as 'home' is valid;
- * do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your
home!m
+ * @return Place handle for the same home, valid as long as @a home is valid;
+ * do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your
home!
*/
struct GNUNET_SOCIAL_Place *
GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
@@ -392,7 +392,7 @@
* key already; 'HEX.zkey' however would refer to
* the 'PLACE' record in the GADS zone with the public key
* 'HEX'.
- * @param join_msg_size Number of bytes in 'join_msg'.
+ * @param join_msg_size Number of bytes in @a join_msg.
* @param join_msg Message to give to the join callback.
* @return NULL on errors, otherwise handle to the place.
*/
@@ -411,11 +411,11 @@
* Watch a place for changed objects.
*
* @param place Place to watch.
- * @param object_filter Object prefix to match. if
- * @param state_cb
- * @param state_cb_cls
+ * @param object_filter Object prefix to match.
+ * @param state_cb Function to call when an object/state changes.
+ * @param state_cb_cls Closure for callback.
*
- * @return
+ * @return Handle that can be used to cancel watching.
*/
struct GNUNET_SOCIAL_WatchHandle *
GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
@@ -424,6 +424,11 @@
void *state_cb_cls);
+/**
+ * Cancel watching a place for changed objects.
+ *
+ * @param wh Watch handle to cancel.
+ */
void
GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
@@ -464,6 +469,8 @@
/**
* Stop looking at objects.
+ *
+ * @param lh Look handle to stop.
*/
void
GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
@@ -492,7 +499,7 @@
*
* @param place Place to talk in.
* @param variable_name Name of variable to set.
- * @param value_size Number of bytes in 'value'.
+ * @param value_size Number of bytes in @a value.
* @param value Value of variable.
*/
void
@@ -514,7 +521,7 @@
* @param place Place where we want to talk to the host.
* @param method_name Method to invoke on the host.
* @param cb Function to use to get the payload for the method.
- * @param cb_cls Closure for 'cb'.
+ * @param cb_cls Closure for @a cb.
* @return NULL if we are already trying to talk to the host,
* otherwise handle to cancel the request.
*/
@@ -530,9 +537,9 @@
* FIXME: look up nym in GADS and talk to its place.
*
* @param nym Nym we want to talk to.
- * @param method_name Method to invoke on the nym.
+ * @param method_name Method to invoke on the @a nym.
* @param cb Function to use to get the payload for the method.
- * @param cb_cls Closure for 'cb'.
+ * @param cb_cls Closure for @a cb.
* @return NULL if we are already trying to talk to the host,
* otherwise handle to cancel the request.
*/
@@ -593,13 +600,13 @@
/**
* Leave a place (destroys the place handle).
*
- * Can either move our user into an 'away' state (in which we continue to
record
+ * Can either move our user into an @e away state (in which we continue to
record
* ongoing conversations and state changes if our peer is running), or leave
the
* place entirely and stop following the conversation.
*
* @param place Place to leave.
- * @param keep_following GNUNET_YES to ask the social service to continue
- * to follow the conversation, GNUNET_NO to fully leave the place.
+ * @param keep_following #GNUNET_YES to ask the social service to continue
+ * to follow the conversation, #GNUNET_NO to fully leave the place.
*/
void
GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place,
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r27633 - gnunet/src/include,
gnunet <=