projects
/
oweals
/
gnunet.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
more work on tng
[oweals/gnunet.git]
/
src
/
include
/
gnunet_social_service.h
diff --git
a/src/include/gnunet_social_service.h
b/src/include/gnunet_social_service.h
index b8b452dfab52a064f7d6ab72b3a59588cb2da0d9..7faa336d6a5a7109cd1d3d15a139a21c4583ae74 100644
(file)
--- a/
src/include/gnunet_social_service.h
+++ b/
src/include/gnunet_social_service.h
@@
-2,20
+2,20
@@
This file is part of GNUnet.
Copyright (C) 2013 GNUnet e.V.
This file is part of GNUnet.
Copyright (C) 2013 GNUnet e.V.
- GNUnet is free software
; you can redistribute it and/or modify
-
it under the terms of the GNU
General Public License as published
- by the Free Software Foundation
; either version 3, or (at your
- option) any later version.
+ GNUnet is free software
: you can redistribute it and/or modify it
+
under the terms of the GNU Affero
General Public License as published
+ by the Free Software Foundation
, either version 3 of the License,
+ o
r (at your o
ption) any later version.
GNUnet is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
GNUnet is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
- You should have received a copy of the GNU General Public License
- along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
- Boston, MA 02110-1301, USA.
+ SPDX-License-Identifier: AGPL3.0-or-later
*/
/**
*/
/**
@@
-86,7
+86,7
@@
or process it using a message handler function.
A client first establishes an _application connection_ to the service using
GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
A client first establishes an _application connection_ to the service using
GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
-public keys of subscribed places and available egos
and
in response.
+public keys of subscribed places and available egos in response.
## Reconnecting to places
## Reconnecting to places
@@
-112,13
+112,13
@@
When leaving a place its network connections are closed and all applications are
# Message methods
# Message methods
-## _
messag
e
+## _
convers
e
-
A message sent to the
place.
+
Human conversation in a private or public
place.
### Environment
### Environment
-#### _id_reply
_to
+#### _id_reply
Message ID this message is in reply to.
#### _id_thread
Message ID this message is in reply to.
#### _id_thread
@@
-127,10
+127,14
@@
Thread ID, the first message ID in the thread.
#### _nym_author
Nym of the author.
#### _nym_author
Nym of the author.
+FIXME: Are nyms a different data type from egos and person entities?
+Do they have a different format than any other entity address?
+Questions and thoughts on how to fix this in "questions.org"
+
#### _sig_author
Signature of the message body and its variables by the author.
#### _sig_author
Signature of the message body and its variables by the author.
-## Data
+##
#
Data
Message body.
Message body.
@@
-148,11
+152,18
@@
e.g. files under a given size.
##### _gns_place
GNS name of the place in a globally unique .zkey zone
##### _gns_place
GNS name of the place in a globally unique .zkey zone
+FIXME: A custom _gns PSYC data type should be avoidable by parsing
+and interpreting PSYC uniforms appropriately.
+Thoughts on this in "questions.org"
+
#### Without GNS
##### _key_pub_place
Public key of place
#### Without GNS
##### _key_pub_place
Public key of place
+FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic
+addressing. Questions and thoughts on how to fix this in "questions.org"
+
##### _peer_origin
Peer ID of origin
##### _peer_origin
Peer ID of origin
@@
-170,7
+181,7
@@
The environment of _notice_place above, plus the following:
#### _size_file
Size of file
#### _size_file
Size of file
-#### _
mim
e_file
+#### _
typ
e_file
MIME type of file
#### _name_file
MIME type of file
#### _name_file
@@
-182,15
+193,15
@@
Description of file
## _file
Messages with a _file method contain a file,
## _file
Messages with a _file method contain a file,
-which is saved to disk upon rece
ipt
at the following location:
-$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<
message_id
>
+which is saved to disk upon rece
ption
at the following location:
+$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<
H(message_id)
>
### Environment
#### _size_file
Size of file
### Environment
#### _size_file
Size of file
-#### _
mim
e_file
+#### _
typ
e_file
MIME type of file
#### _name_file
MIME type of file
#### _name_file
@@
-296,25
+307,39
@@
typedef void
/**
/**
- * Entry status of a place.
+ * Entry status of a place
per application
.
*/
*/
-enum GNUNET_SOCIAL_PlaceState
+enum GNUNET_SOCIAL_
App
PlaceState
{
/**
{
/**
- * Place was once entered but left since.
+ * The place was once entered by the ego, but left since.
+ * It's possible to establish a local connection to the place
+ * without re-entering to fetch history from the PSYCstore.
+ * @see enum GNUNET_PSYC_SlaveJoinFlags and GNUNET_SOCIAL_guest_enter()
*/
GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
*/
GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
+
/**
/**
- * Place is entered but not subscribed.
+ * The place is entered by the ego,
+ * but this application is not subscribed to it.
*/
GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
*/
GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
+
/**
/**
- * Place is entered and subscribed.
+ * The place is entered by the ego and
+ * and this application is subscribed to it.
*/
GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
};
*/
GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
};
+/**
+ * Called after receiving initial list of egos and places.
+ */
+typedef void
+(*GNUNET_SOCIAL_AppConnectedCallback) (void *cls);
+
+
/**
* Notification about a home.
*
/**
* Notification about a home.
*
@@
-327,14
+352,14
@@
enum GNUNET_SOCIAL_PlaceState
* @param place_pub_key
* Public key of the place.
* @param place_state
* @param place_pub_key
* Public key of the place.
* @param place_state
- * @see enum GNUNET_SOCIAL_PlaceState
+ * @see enum GNUNET_SOCIAL_
App
PlaceState
*/
typedef void
(*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
struct GNUNET_SOCIAL_HostConnection *hconn,
struct GNUNET_SOCIAL_Ego *ego,
const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
*/
typedef void
(*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
struct GNUNET_SOCIAL_HostConnection *hconn,
struct GNUNET_SOCIAL_Ego *ego,
const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
- enum GNUNET_SOCIAL_PlaceState place_state);
+ enum GNUNET_SOCIAL_
App
PlaceState place_state);
/**
* Notification about a place.
/**
* Notification about a place.
@@
-348,20
+373,20
@@
typedef void
* @param place_pub_key
* Public key of the place.
* @param place_state
* @param place_pub_key
* Public key of the place.
* @param place_state
- * @see enum GNUNET_SOCIAL_PlaceState
+ * @see enum GNUNET_SOCIAL_
App
PlaceState
*/
typedef void
(*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
struct GNUNET_SOCIAL_GuestConnection *gconn,
struct GNUNET_SOCIAL_Ego *ego,
const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
*/
typedef void
(*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
struct GNUNET_SOCIAL_GuestConnection *gconn,
struct GNUNET_SOCIAL_Ego *ego,
const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
- enum GNUNET_SOCIAL_PlaceState place_state);
+ enum GNUNET_SOCIAL_
App
PlaceState place_state);
/**
* Establish application connection to the social service.
*
/**
* Establish application connection to the social service.
*
- * The @host_
place_cb and @guest_place
_cb functions are
+ * The @host_
cb and @guest
_cb functions are
* initially called for each entered places,
* then later each time a new place is entered with the current app ID.
*
* initially called for each entered places,
* then later each time a new place is entered with the current app ID.
*
@@
-384,17
+409,24
@@
GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
GNUNET_SOCIAL_AppEgoCallback ego_cb,
GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
GNUNET_SOCIAL_AppEgoCallback ego_cb,
GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
+ GNUNET_SOCIAL_AppConnectedCallback connected_cb,
void *cls);
/**
* Disconnect app.
*
void *cls);
/**
* Disconnect app.
*
- * @param c
- * App handle.
+ * @param app
+ * Application handle.
+ * @param disconnect_cb
+ * Disconnect callback.
+ * @param disconnect_cls
+ * Disconnect closure.
*/
void
*/
void
-GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app);
+GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app,
+ GNUNET_ContinuationCallback disconnect_cb,
+ void *disconnect_cls);
/**
/**
@@
-457,21
+489,28
@@
GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
* reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
* for it.
*
* reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
* for it.
*
- * @param cls Closure.
- * @param nym Handle for the user who wants to enter.
- * @param method_name Method name in the entry request.
- * @param variable_count Number of elements in the @a variables array.
- * @param variables Variables present in the message.
- * @param data_size Number of bytes in @a data.
- * @param data Payload given on enter (e.g. a password).
+ * @param cls
+ * Closure.
+ * @param nym
+ * Handle for the user who wants to enter.
+ * @param method_name
+ * Method name in the entry request.
+ * @param variable_count
+ * Number of elements in the @a variables array.
+ * @param variables
+ * Variables present in the message.
+ * @param data
+ * Payload given on enter (e.g. a password).
+ * @param data_size
+ * Number of bytes in @a data.
*/
typedef void
(*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
struct GNUNET_SOCIAL_Nym *nym,
const char *method_name,
struct GNUNET_PSYC_Environment *env,
*/
typedef void
(*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
struct GNUNET_SOCIAL_Nym *nym,
const char *method_name,
struct GNUNET_PSYC_Environment *env,
-
size_t data_size
,
-
const void *data
);
+
const void *data
,
+
size_t data_size
);
/**
/**
@@
-589,14
+628,8
@@
GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn,
* #GNUNET_YES if @a nym is admitted,
* #GNUNET_NO if @a nym is refused entry,
* #GNUNET_SYSERR if we cannot answer the request.
* #GNUNET_YES if @a nym is admitted,
* #GNUNET_NO if @a nym is refused entry,
* #GNUNET_SYSERR if we cannot answer the request.
- * @param method_name
- * Method name for the rejection message.
- * @param env
- * Environment containing variables for the message, or NULL.
- * @param data
- * Data for the rejection message to send back.
- * @param data_size
- * Number of bytes in @a data for method.
+ * @param entry_resp
+ * Entry response message, or NULL.
* @return #GNUNET_OK on success,
* #GNUNET_SYSERR if the message is too large.
*/
* @return #GNUNET_OK on success,
* #GNUNET_SYSERR if the message is too large.
*/
@@
-782,7
+815,7
@@
GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst,
/**
* Stop hosting a home.
*
/**
* Stop hosting a home.
*
- * Sends a _notice_place_clos
ed
announcement to the home.
+ * Sends a _notice_place_clos
ing
announcement to the home.
* Invalidates host handle.
*
* @param hst
* Invalidates host handle.
*
* @param hst
@@
-860,14
+893,8
@@
typedef void
* Number of elements in the @a relays array.
* @param relays
* Relays for the underlying multicast group.
* Number of elements in the @a relays array.
* @param relays
* Relays for the underlying multicast group.
- * @param method_name
- * Method name for the message.
- * @param env
- * Environment containing variables for the message, or NULL.
- * @param data
- * Payload for the message to give to the enter callback.
- * @param data_size
- * Number of bytes in @a data.
+ * @param entry_msg
+ * Entry message.
* @param slicer
* Slicer to use for processing incoming requests from guests.
*
* @param slicer
* Slicer to use for processing incoming requests from guests.
*
@@
-1190,8
+1217,6
@@
struct GNUNET_SOCIAL_LookHandle;
* The place to look the object at.
* @param full_name
* Full name of the object.
* The place to look the object at.
* @param full_name
* Full name of the object.
- * @param value_size
- * Set to the size of the returned value.
*
* @return NULL if there is no such object at this place.
*/
*
* @return NULL if there is no such object at this place.
*/