diff options
author | Gabor X Toth <*@tg-x.net> | 2014-05-27 21:31:53 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2014-05-27 21:31:53 +0000 |
commit | e7356fa5d53b2047a1b087fa61ccf15198aeb0bc (patch) | |
tree | a815df3f353d09542fbd1afe374f92b492877dd1 /src/include/gnunet_social_service.h | |
parent | 5510b78f8b00c0826dfd692cb548b3142000c76f (diff) | |
download | gnunet-e7356fa5d53b2047a1b087fa61ccf15198aeb0bc.tar.gz gnunet-e7356fa5d53b2047a1b087fa61ccf15198aeb0bc.zip |
social: separate host/guest/place API; add missing method cb params; improve docs
Diffstat (limited to 'src/include/gnunet_social_service.h')
-rw-r--r-- | src/include/gnunet_social_service.h | 422 |
1 files changed, 229 insertions, 193 deletions
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h index ba698aee6..e68d84d2f 100644 --- a/src/include/gnunet_social_service.h +++ b/src/include/gnunet_social_service.h | |||
@@ -20,7 +20,7 @@ | |||
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @file include/gnunet_social_service.h | 22 | * @file include/gnunet_social_service.h |
23 | * @brief Social service; implements social functionality using the PSYC service. | 23 | * @brief Social service; implements social interactions using the PSYC service. |
24 | * @author Gabor X Toth | 24 | * @author Gabor X Toth |
25 | * @author Christian Grothoff | 25 | * @author Christian Grothoff |
26 | */ | 26 | */ |
@@ -48,7 +48,7 @@ extern "C" | |||
48 | 48 | ||
49 | 49 | ||
50 | /** | 50 | /** |
51 | * Handle for another user (who is likely pseudonymous) in the network. | 51 | * Handle for a pseudonym of another user in the network. |
52 | */ | 52 | */ |
53 | struct GNUNET_SOCIAL_Nym; | 53 | struct GNUNET_SOCIAL_Nym; |
54 | 54 | ||
@@ -58,9 +58,14 @@ struct GNUNET_SOCIAL_Nym; | |||
58 | struct GNUNET_SOCIAL_Place; | 58 | struct GNUNET_SOCIAL_Place; |
59 | 59 | ||
60 | /** | 60 | /** |
61 | * Handle for a place that one of our egos hosts. | 61 | * Host handle for a place that we entered. |
62 | */ | 62 | */ |
63 | struct GNUNET_SOCIAL_Home; | 63 | struct GNUNET_SOCIAL_Host; |
64 | |||
65 | /** | ||
66 | * Guest handle for place that we entered. | ||
67 | */ | ||
68 | struct GNUNET_SOCIAL_Guest; | ||
64 | 69 | ||
65 | /** | 70 | /** |
66 | * Handle to an implementation of try-and-slice. | 71 | * Handle to an implementation of try-and-slice. |
@@ -69,36 +74,45 @@ struct GNUNET_SOCIAL_Slicer; | |||
69 | 74 | ||
70 | 75 | ||
71 | /** | 76 | /** |
72 | * Method called from SOCIAL upon receiving a message indicating a call | 77 | * Function called upon receiving a message indicating a call to a @e method. |
73 | * to a @e method. | ||
74 | * | 78 | * |
75 | * @param cls Closure. | 79 | * This function is called one or more times for each message until all data |
76 | * @param nym The sender of the message. NULL for the ego's own messages to the home. | 80 | * fragments arrive from the network. |
77 | * @param full_method_name Original method name from PSYC (may be more | 81 | * |
78 | * specific than the registered method name due to try-and-slice matching). | 82 | * @param cls Closure. |
79 | 83 | * @param message_id Message counter, monotonically increasing from 1. | |
80 | * @param message_id Unique message counter for this message | 84 | * @param nym The sender of the message. Can be NULL if the message is not |
81 | * (unique only in combination with the given sender for | 85 | * connected to a pseudonym. |
82 | * this channel). | 86 | * @param flags OR'ed GNUNET_PSYC_MessageFlags |
83 | * @param modifier_count Number of elements in the @a modifiers array. | 87 | * @param method_name Original method name from PSYC (may be more specific |
84 | * @param modifiers Modifiers present in the message. FIXME: use environment instead? | 88 | * than the registered method name due to try-and-slice matching). |
85 | * @param data_offset Byte offset of @a data in the overall data of the method. | 89 | * @param env Environment containing variables for the message and operations |
86 | * @param data Data stream given to the method (might not be zero-terminated | 90 | * on objects of the place, or NULL. |
87 | * if data is binary). | 91 | * Only set for the first call of this function for each @a message_id, |
88 | * @param data_size Number of bytes in @a data. | 92 | * NULL when notifying about further data fragments. |
89 | * @param flags Message flags indicating fragmentation status. | 93 | * @param data_offset Byte offset of @a data in the overall data of the method. |
94 | * @param data_size Number of bytes in @a data. | ||
95 | * @param data Data stream given to the method (might not be zero-terminated | ||
96 | * if data is binary). | ||
97 | * @param end End of message? | ||
98 | * #GNUNET_NO if there are further fragments, | ||
99 | * #GNUNET_YES if this is the last fragment, | ||
100 | * #GNUNET_SYSERR indicates the message was cancelled by the sender. | ||
101 | * | ||
102 | * @return #GNUNET_YES the application keeps @a env for further use, | ||
103 | * #GNUNET_NO @a env is free()'d after the function returns. | ||
90 | */ | 104 | */ |
91 | typedef int | 105 | typedef int |
92 | (*GNUNET_SOCIAL_Method) (void *cls, | 106 | (*GNUNET_SOCIAL_MethodCallback) (void *cls, |
93 | struct GNUNET_SOCIAL_Nym *nym, | 107 | uint64_t message_id, |
94 | const char *full_method_name, | 108 | uint32_t flags, |
95 | uint64_t message_id, | 109 | const struct GNUNET_SOCIAL_Nym *nym, |
96 | size_t modifier_count, | 110 | const char *method_name, |
97 | struct GNUNET_ENV_Modifier *modifiers, | 111 | struct GNUNET_ENV_Environment *env, |
98 | uint64_t data_offset, | 112 | uint64_t data_offset, |
99 | const void *data, | 113 | size_t data_size, |
100 | size_t data_size, | 114 | const void *data, |
101 | enum GNUNET_PSYC_MessageFlags flags); | 115 | int end); |
102 | 116 | ||
103 | 117 | ||
104 | /** | 118 | /** |
@@ -125,8 +139,8 @@ GNUNET_SOCIAL_slicer_create (void); | |||
125 | void | 139 | void |
126 | GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, | 140 | GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, |
127 | const char *method_name, | 141 | const char *method_name, |
128 | GNUNET_SOCIAL_Method method, | 142 | GNUNET_SOCIAL_MethodCallback method_cb, |
129 | void *method_cls); | 143 | void *cls); |
130 | 144 | ||
131 | 145 | ||
132 | /** | 146 | /** |
@@ -139,7 +153,7 @@ GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, | |||
139 | void | 153 | void |
140 | GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer, | 154 | GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer, |
141 | const char *method_name, | 155 | const char *method_name, |
142 | GNUNET_SOCIAL_Method method); | 156 | GNUNET_SOCIAL_MethodCallback method_cb); |
143 | 157 | ||
144 | /** | 158 | /** |
145 | * Destroy a given try-and-slice instance. | 159 | * Destroy a given try-and-slice instance. |
@@ -153,10 +167,10 @@ GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer); | |||
153 | /** | 167 | /** |
154 | * Function called asking for nym to be admitted to the place. | 168 | * Function called asking for nym to be admitted to the place. |
155 | * | 169 | * |
156 | * Should call either GNUNET_SOCIAL_home_admit() or | 170 | * Should call either GNUNET_SOCIAL_host_admit() or |
157 | * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously). If this owner | 171 | * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously). If this host |
158 | * cannot decide, it is fine to call neither function, in which case hopefully | 172 | * cannot decide, it is fine to call neither function, in which case hopefully |
159 | * some other owner of the home exists that will make the decision. The @a nym | 173 | * some other host of the place exists that will make the decision. The @a nym |
160 | * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked | 174 | * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked |
161 | * for it. | 175 | * for it. |
162 | * | 176 | * |
@@ -197,26 +211,26 @@ typedef void | |||
197 | 211 | ||
198 | 212 | ||
199 | /** | 213 | /** |
200 | * Enter a home where guests (nyms) can be hosted. | 214 | * Enter a place as host. |
201 | * | 215 | * |
202 | * A home is created upon first entering, and exists until | 216 | * A place is created upon first entering, and it is active until permanently |
203 | * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using | 217 | * left using GNUNET_SOCIAL_host_leave(). |
204 | * GNUNET_SOCIAL_home_leave(). | ||
205 | * | 218 | * |
206 | * @param cfg Configuration to contact the social service. | 219 | * @param cfg Configuration to contact the social service. |
207 | * @param home_keyfile File with the private-public key pair of the home, | 220 | * @param place_keyfile File with the private-public key pair of the place, |
208 | * created if the file does not exist; pass NULL for ephemeral homes. | 221 | * created if the file does not exist; pass NULL for ephemeral places. |
209 | * @param policy Policy specifying entry and history restrictions of the home. | 222 | * @param policy Policy specifying entry and history restrictions of the place. |
210 | * @param ego Owner of the home (host). | 223 | * @param ego Identity of the host. |
211 | * @param slicer Slicer to handle guests talking. | 224 | * @param slicer Slicer to handle incoming messages. |
212 | * @param listener_cb Function to handle new nyms that want to enter. | 225 | * @param listener_cb Function to handle new nyms that want to enter. |
213 | * @param farewell_cb Function to handle departing nyms. | 226 | * @param farewell_cb Function to handle departing nyms. |
214 | * @param cls Closure for @a listener_cb and @a farewell_cb. | 227 | * @param cls Closure for @a listener_cb and @a farewell_cb. |
215 | * @return Handle for a new home. | 228 | * |
216 | */ | 229 | * @return Handle for the host. |
217 | struct GNUNET_SOCIAL_Home * | 230 | */ |
218 | GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | 231 | struct GNUNET_SOCIAL_Host * |
219 | const char *home_keyfile, | 232 | GNUNET_SOCIAL_host_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, |
233 | const char *place_keyfile, | ||
220 | enum GNUNET_PSYC_Policy policy, | 234 | enum GNUNET_PSYC_Policy policy, |
221 | struct GNUNET_IDENTITY_Ego *ego, | 235 | struct GNUNET_IDENTITY_Ego *ego, |
222 | struct GNUNET_SOCIAL_Slicer *slicer, | 236 | struct GNUNET_SOCIAL_Slicer *slicer, |
@@ -226,38 +240,38 @@ GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
226 | 240 | ||
227 | 241 | ||
228 | /** | 242 | /** |
229 | * Admit @a nym to the @a home. | 243 | * Admit @a nym to the place. |
230 | * | 244 | * |
231 | * The @a nym reference will remain valid until either the home is destroyed or | 245 | * The @a nym reference will remain valid until either the @a host or @a nym |
232 | * @a nym leaves. | 246 | * leaves the place. |
233 | * | 247 | * |
234 | * @param home Home to allow @a nym to enter. | 248 | * @param host Host of the place. |
235 | * @param nym Handle for the entity that wants to enter. | 249 | * @param nym Handle for the entity that wants to enter. |
236 | */ | 250 | */ |
237 | void | 251 | void |
238 | GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home, | 252 | GNUNET_SOCIAL_host_admit (struct GNUNET_SOCIAL_Host *host, |
239 | struct GNUNET_SOCIAL_Nym *nym); | 253 | struct GNUNET_SOCIAL_Nym *nym); |
240 | 254 | ||
241 | 255 | ||
242 | /** | 256 | /** |
243 | * Throw @a nym out of the @a home. | 257 | * Throw @a nym out of the place. |
244 | * | 258 | * |
245 | * The @a nym reference will remain valid until the | 259 | * The @a nym reference will remain valid until the |
246 | * #GNUNET_SOCIAL_FarewellCallback is invoked, | 260 | * #GNUNET_SOCIAL_FarewellCallback is invoked, |
247 | * which should be very soon after this call. | 261 | * which should be very soon after this call. |
248 | * | 262 | * |
249 | * @param home Home to eject @a nym from. | 263 | * @param host Host of the place. |
250 | * @param nym Handle for the entity to be ejected. | 264 | * @param nym Handle for the entity to be ejected. |
251 | */ | 265 | */ |
252 | void | 266 | void |
253 | GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | 267 | GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host, |
254 | struct GNUNET_SOCIAL_Nym *nym); | 268 | struct GNUNET_SOCIAL_Nym *nym); |
255 | 269 | ||
256 | 270 | ||
257 | /** | 271 | /** |
258 | * Refuse @a nym entry into the @a home. | 272 | * Refuse @a nym entry into the place. |
259 | * | 273 | * |
260 | * @param home Home to disallow @a nym to enter. | 274 | * @param host Host of the place. |
261 | * @param nym Handle for the entity that wanted to enter. | 275 | * @param nym Handle for the entity that wanted to enter. |
262 | * @param method_name Method name for the rejection message. | 276 | * @param method_name Method name for the rejection message. |
263 | * @param env Environment containing variables for the message, or NULL. | 277 | * @param env Environment containing variables for the message, or NULL. |
@@ -265,7 +279,7 @@ GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | |||
265 | * @param data_size Number of bytes in @a data for method. | 279 | * @param data_size Number of bytes in @a data for method. |
266 | */ | 280 | */ |
267 | void | 281 | void |
268 | GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home, | 282 | GNUNET_SOCIAL_host_refuse_entry (struct GNUNET_SOCIAL_Host *host, |
269 | struct GNUNET_SOCIAL_Nym *nym, | 283 | struct GNUNET_SOCIAL_Nym *nym, |
270 | const char *method_name, | 284 | const char *method_name, |
271 | const struct GNUNET_ENV_Environment *env, | 285 | const struct GNUNET_ENV_Environment *env, |
@@ -274,7 +288,7 @@ GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home, | |||
274 | 288 | ||
275 | 289 | ||
276 | /** | 290 | /** |
277 | * Get the public key of a nym. | 291 | * Get the public key of a @a nym. |
278 | * | 292 | * |
279 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). | 293 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). |
280 | * | 294 | * |
@@ -287,20 +301,22 @@ GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym, | |||
287 | 301 | ||
288 | 302 | ||
289 | /** | 303 | /** |
290 | * Obtain the private-public key pair of the home. | 304 | * Obtain the private-public key pair of the host. |
291 | * | 305 | * |
292 | * @param home Home to get the key of. | 306 | * @param host Host to get the key of. |
293 | * @param[out] home_key Set to the private-public key pair of the home. The public part is suitable for storing in GNS within a "PLACE" record, along with peer IDs to join at. | 307 | * @param[out] host_key Set to the private-public key pair of the host. The |
308 | * public part is suitable for storing in GNS within a "PLACE" | ||
309 | * record, along with peer IDs to join at. | ||
294 | */ | 310 | */ |
295 | void | 311 | void |
296 | GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home, | 312 | GNUNET_SOCIAL_host_get_key (struct GNUNET_SOCIAL_Host *host, |
297 | struct GNUNET_CRYPTO_EddsaPrivateKey *home_key); | 313 | struct GNUNET_CRYPTO_EddsaPrivateKey *host_key); |
298 | 314 | ||
299 | 315 | ||
300 | /** | 316 | /** |
301 | * Advertise @a home under @a name in the GNS zone of the @e ego. | 317 | * Advertise the place in the GNS zone of the @e ego of the @a host. |
302 | * | 318 | * |
303 | * @param home The home to advertise. | 319 | * @param host Host of the place. |
304 | * @param name The name for the PLACE record to put in the zone. | 320 | * @param name The name for the PLACE record to put in the zone. |
305 | * @param peer_count Number of elements in the @a peers array. | 321 | * @param peer_count Number of elements in the @a peers array. |
306 | * @param peers List of peers in the PLACE record that can be used to send join | 322 | * @param peers List of peers in the PLACE record that can be used to send join |
@@ -309,7 +325,7 @@ GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home, | |||
309 | * @param password Password used to encrypt the record. | 325 | * @param password Password used to encrypt the record. |
310 | */ | 326 | */ |
311 | void | 327 | void |
312 | GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home, | 328 | GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host, |
313 | const char *name, | 329 | const char *name, |
314 | size_t peer_count, | 330 | size_t peer_count, |
315 | const struct GNUNET_PeerIdentity *peers, | 331 | const struct GNUNET_PeerIdentity *peers, |
@@ -318,16 +334,16 @@ GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home, | |||
318 | 334 | ||
319 | 335 | ||
320 | /** | 336 | /** |
321 | * Flags for announcements in a home. | 337 | * Flags for announcements by a host. |
322 | */ | 338 | */ |
323 | enum GNUNET_SOCIAL_AnnounceFlags | 339 | enum GNUNET_SOCIAL_AnnounceFlags |
324 | { | 340 | { |
325 | GNUNET_SOCIAL_ANNOUNCE_NONE = 0, | 341 | GNUNET_SOCIAL_ANNOUNCE_NONE = 0, |
326 | 342 | ||
327 | /** | 343 | /** |
328 | * Whether this announcement removes all objects from the home. | 344 | * Whether this announcement removes all objects from the place. |
329 | * | 345 | * |
330 | * New objects can be still added to the now empty home using the @e env | 346 | * New objects can be still added to the now empty place using the @e env |
331 | * parameter of the same announcement. | 347 | * parameter of the same announcement. |
332 | */ | 348 | */ |
333 | GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0 | 349 | GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0 |
@@ -341,22 +357,23 @@ struct GNUNET_SOCIAL_Announcement; | |||
341 | 357 | ||
342 | 358 | ||
343 | /** | 359 | /** |
344 | * Send a message to all nyms that are present in the home. | 360 | * Send a message to all nyms that are present in the place. |
345 | * | 361 | * |
346 | * This function is restricted to the home owner. Nyms can only send requests | 362 | * This function is restricted to the host. Nyms can only send requests |
347 | * to the home owner who can decide to relay it to other guests. | 363 | * to the host who can decide to relay it to everyone in the place. |
348 | * | 364 | * |
349 | * @param home Home to address the announcement to. | 365 | * @param host Host of the place. |
350 | * @param method_name Method to use for the announcement. | 366 | * @param method_name Method to use for the announcement. |
351 | * @param env Environment containing variables for the message and operations on | 367 | * @param env Environment containing variables for the message and operations |
352 | * objects of the home, or NULL. | 368 | * on objects of the place. Can be NULL. |
353 | * @param notify Function to call to get the payload of the announcement. | 369 | * @param notify Function to call to get the payload of the announcement. |
354 | * @param notify_cls Closure for @a notify. | 370 | * @param notify_cls Closure for @a notify. |
355 | * @param flags Flags for this announcement. | 371 | * @param flags Flags for this announcement. |
372 | * | ||
356 | * @return NULL on error (announcement already in progress?). | 373 | * @return NULL on error (announcement already in progress?). |
357 | */ | 374 | */ |
358 | struct GNUNET_SOCIAL_Announcement * | 375 | struct GNUNET_SOCIAL_Announcement * |
359 | GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home, | 376 | GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host, |
360 | const char *method_name, | 377 | const char *method_name, |
361 | const struct GNUNET_ENV_Environment *env, | 378 | const struct GNUNET_ENV_Environment *env, |
362 | GNUNET_CONNECTION_TransmitReadyNotify notify, | 379 | GNUNET_CONNECTION_TransmitReadyNotify notify, |
@@ -370,37 +387,39 @@ GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home, | |||
370 | * @param a The announcement to cancel. | 387 | * @param a The announcement to cancel. |
371 | */ | 388 | */ |
372 | void | 389 | void |
373 | GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); | 390 | GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); |
374 | 391 | ||
375 | 392 | ||
376 | /** | 393 | /** |
377 | * Convert our home to a place so we can access it via the place API. | 394 | * Obtain handle for a hosted place. |
395 | * | ||
396 | * The returned handle can be used to access the place API. | ||
378 | * | 397 | * |
379 | * @param home Handle for the home. | 398 | * @param host Handle for the host. |
380 | * @return Place handle for the same home, valid as long as @a home is valid; | 399 | * |
381 | * do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home! | 400 | * @return Handle for the hosted place, valid as long as @a host is valid. |
382 | */ | 401 | */ |
383 | struct GNUNET_SOCIAL_Place * | 402 | struct GNUNET_SOCIAL_Place * |
384 | GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home); | 403 | GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host); |
385 | 404 | ||
386 | 405 | ||
387 | /** | 406 | /** |
388 | * Leave a home. | 407 | * Stop hosting a place. |
389 | 408 | * | |
390 | * Invalidates home handle. | 409 | * Invalidates host handle. |
391 | * Guests will be disconnected until the home is restarted. | ||
392 | * | 410 | * |
393 | * @param home Home to leave. | 411 | * @param host Host leaving the place. |
394 | * @param keep_active Keep home active after last application disconnected. | 412 | * @param keep_active Keep the place active after last host disconnected. |
395 | */ | 413 | */ |
396 | void | 414 | void |
397 | GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home, int keep_active); | 415 | GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host, int keep_active); |
416 | |||
398 | 417 | ||
399 | /** | 418 | /** |
400 | * Request entry to a place (home hosted by someone else). | 419 | * Request entry to a place as a guest. |
401 | * | 420 | * |
402 | * @param cfg Configuration to contact the social service. | 421 | * @param cfg Configuration to contact the social service. |
403 | * @param ego Owner of the home (host). | 422 | * @param ego Identity of the guest. |
404 | * @param address GNS name of the place to enter. Either in the form of | 423 | * @param address GNS name of the place to enter. Either in the form of |
405 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to | 424 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to |
406 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the | 425 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the |
@@ -411,10 +430,11 @@ GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home, int keep_active); | |||
411 | * @param data Payload for the message to give to the enter callback. | 430 | * @param data Payload for the message to give to the enter callback. |
412 | * @param data_size Number of bytes in @a data. | 431 | * @param data_size Number of bytes in @a data. |
413 | * @param slicer Slicer to use for processing incoming requests from guests. | 432 | * @param slicer Slicer to use for processing incoming requests from guests. |
414 | * @return NULL on errors, otherwise handle to the place. | 433 | * |
434 | * @return NULL on errors, otherwise handle for the guest. | ||
415 | */ | 435 | */ |
416 | struct GNUNET_SOCIAL_Place * | 436 | struct GNUNET_SOCIAL_Guest * |
417 | GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | 437 | GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, |
418 | struct GNUNET_IDENTITY_Ego *ego, | 438 | struct GNUNET_IDENTITY_Ego *ego, |
419 | char *address, | 439 | char *address, |
420 | const char *method_name, | 440 | const char *method_name, |
@@ -424,10 +444,10 @@ GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
424 | struct GNUNET_SOCIAL_Slicer *slicer); | 444 | struct GNUNET_SOCIAL_Slicer *slicer); |
425 | 445 | ||
426 | /** | 446 | /** |
427 | * Request entry to a place (home hosted by someone else). | 447 | * Request entry to a place as a guest. |
428 | * | 448 | * |
429 | * @param cfg Configuration to contact the social service. | 449 | * @param cfg Configuration to contact the social service. |
430 | * @param ego Owner of the home (host). | 450 | * @param ego Identity of the guest. |
431 | * @param crypto_address Public key of the place to enter. | 451 | * @param crypto_address Public key of the place to enter. |
432 | * @param origin Peer identity of the origin of the underlying multicast group. | 452 | * @param origin Peer identity of the origin of the underlying multicast group. |
433 | * @param relay_count Number of elements in the @a relays array. | 453 | * @param relay_count Number of elements in the @a relays array. |
@@ -437,10 +457,11 @@ GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
437 | * @param data Payload for the message to give to the enter callback. | 457 | * @param data Payload for the message to give to the enter callback. |
438 | * @param data_size Number of bytes in @a data. | 458 | * @param data_size Number of bytes in @a data. |
439 | * @param slicer Slicer to use for processing incoming requests from guests. | 459 | * @param slicer Slicer to use for processing incoming requests from guests. |
440 | * @return NULL on errors, otherwise handle to the place. | 460 | * |
461 | * @return NULL on errors, otherwise handle for the guest. | ||
441 | */ | 462 | */ |
442 | struct GNUNET_SOCIAL_Place * | 463 | struct GNUNET_SOCIAL_Guest * |
443 | GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, | 464 | GNUNET_SOCIAL_guest_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, |
444 | struct GNUNET_IDENTITY_Ego *ego, | 465 | struct GNUNET_IDENTITY_Ego *ego, |
445 | struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address, | 466 | struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address, |
446 | struct GNUNET_PeerIdentity *origin, | 467 | struct GNUNET_PeerIdentity *origin, |
@@ -453,81 +474,6 @@ GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
453 | struct GNUNET_SOCIAL_Slicer *slicer); | 474 | struct GNUNET_SOCIAL_Slicer *slicer); |
454 | 475 | ||
455 | 476 | ||
456 | struct GNUNET_SOCIAL_WatchHandle; | ||
457 | |||
458 | /** | ||
459 | * Watch a place for changed objects. | ||
460 | * | ||
461 | * @param place Place to watch. | ||
462 | * @param object_filter Object prefix to match. | ||
463 | * @param state_cb Function to call when an object/state changes. | ||
464 | * @param state_cb_cls Closure for callback. | ||
465 | * | ||
466 | * @return Handle that can be used to cancel watching. | ||
467 | */ | ||
468 | struct GNUNET_SOCIAL_WatchHandle * | ||
469 | GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place, | ||
470 | const char *object_filter, | ||
471 | GNUNET_PSYC_StateCallback state_cb, | ||
472 | void *state_cb_cls); | ||
473 | |||
474 | |||
475 | /** | ||
476 | * Cancel watching a place for changed objects. | ||
477 | * | ||
478 | * @param wh Watch handle to cancel. | ||
479 | */ | ||
480 | void | ||
481 | GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh); | ||
482 | |||
483 | |||
484 | struct GNUNET_SOCIAL_LookHandle; | ||
485 | |||
486 | |||
487 | /** | ||
488 | * Look at objects in the place with a matching name prefix. | ||
489 | * | ||
490 | * @param place The place to look its objects at. | ||
491 | * @param name_prefix Look at objects with names beginning with this value. | ||
492 | * @param state_cb Function to call for each object found. | ||
493 | * @param state_cb_cls Closure for callback function. | ||
494 | * | ||
495 | * @return Handle that can be used to stop looking at objects. | ||
496 | */ | ||
497 | struct GNUNET_SOCIAL_LookHandle * | ||
498 | GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place, | ||
499 | const char *name_prefix, | ||
500 | GNUNET_PSYC_StateCallback state_cb, | ||
501 | void *state_cb_cls); | ||
502 | |||
503 | |||
504 | /** | ||
505 | * Stop looking at objects. | ||
506 | * | ||
507 | * @param lh Look handle to stop. | ||
508 | */ | ||
509 | void | ||
510 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh); | ||
511 | |||
512 | |||
513 | |||
514 | /** | ||
515 | * Look at a particular object in the place. | ||
516 | * | ||
517 | * The best matching object is returned (its name might be less specific than | ||
518 | * what was requested). | ||
519 | * | ||
520 | * @param place The place to look the object at. | ||
521 | * @param full_name Full name of the object. | ||
522 | * @param value_size Set to the size of the returned value. | ||
523 | * @return NULL if there is no such object at this place. | ||
524 | */ | ||
525 | const void * | ||
526 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place, | ||
527 | const char *full_name, | ||
528 | size_t *value_size); | ||
529 | |||
530 | |||
531 | /** | 477 | /** |
532 | * Flags for talking to the host of a place. | 478 | * Flags for talking to the host of a place. |
533 | */ | 479 | */ |
@@ -542,6 +488,7 @@ enum GNUNET_SOCIAL_TalkFlags | |||
542 | */ | 488 | */ |
543 | struct GNUNET_SOCIAL_TalkRequest; | 489 | struct GNUNET_SOCIAL_TalkRequest; |
544 | 490 | ||
491 | |||
545 | /** | 492 | /** |
546 | * Talk to the host of the place. | 493 | * Talk to the host of the place. |
547 | * | 494 | * |
@@ -551,11 +498,12 @@ struct GNUNET_SOCIAL_TalkRequest; | |||
551 | * @param notify Function to use to get the payload for the method. | 498 | * @param notify Function to use to get the payload for the method. |
552 | * @param notify_cls Closure for @a notify. | 499 | * @param notify_cls Closure for @a notify. |
553 | * @param flags Flags for the message being sent. | 500 | * @param flags Flags for the message being sent. |
501 | * | ||
554 | * @return NULL if we are already trying to talk to the host, | 502 | * @return NULL if we are already trying to talk to the host, |
555 | * otherwise handle to cancel the request. | 503 | * otherwise handle to cancel the request. |
556 | */ | 504 | */ |
557 | struct GNUNET_SOCIAL_TalkRequest * | 505 | struct GNUNET_SOCIAL_TalkRequest * |
558 | GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place, | 506 | GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Place *place, |
559 | const char *method_name, | 507 | const char *method_name, |
560 | const struct GNUNET_ENV_Environment *env, | 508 | const struct GNUNET_ENV_Environment *env, |
561 | GNUNET_CONNECTION_TransmitReadyNotify notify, | 509 | GNUNET_CONNECTION_TransmitReadyNotify notify, |
@@ -569,7 +517,32 @@ GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place, | |||
569 | * @param tr Talk request to cancel. | 517 | * @param tr Talk request to cancel. |
570 | */ | 518 | */ |
571 | void | 519 | void |
572 | GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); | 520 | GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); |
521 | |||
522 | |||
523 | /** | ||
524 | * Leave a place permanently. | ||
525 | * | ||
526 | * Notifies the owner of the place about leaving, and destroys the place handle. | ||
527 | * | ||
528 | * @param place Place to leave permanently. | ||
529 | * @param keep_active Keep place active after last application disconnected. | ||
530 | */ | ||
531 | void | ||
532 | GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Place *place, int keep_active); | ||
533 | |||
534 | |||
535 | /** | ||
536 | * Obtain handle for a place entered as guest. | ||
537 | * | ||
538 | * The returned handle can be used to access the place API. | ||
539 | * | ||
540 | * @param guest Handle for the guest. | ||
541 | * | ||
542 | * @return Handle for the place, valid as long as @a guest is valid. | ||
543 | */ | ||
544 | struct GNUNET_SOCIAL_Place * | ||
545 | GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Host *guest); | ||
573 | 546 | ||
574 | 547 | ||
575 | /** | 548 | /** |
@@ -618,16 +591,79 @@ void | |||
618 | GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist); | 591 | GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist); |
619 | 592 | ||
620 | 593 | ||
594 | struct GNUNET_SOCIAL_WatchHandle; | ||
595 | |||
621 | /** | 596 | /** |
622 | * Leave a place permanently. | 597 | * Watch a place for changed objects. |
623 | * | 598 | * |
624 | * Notifies the owner of the place about leaving, and destroys the place handle. | 599 | * @param place Place to watch. |
600 | * @param object_filter Object prefix to match. | ||
601 | * @param state_cb Function to call when an object/state changes. | ||
602 | * @param state_cb_cls Closure for callback. | ||
625 | * | 603 | * |
626 | * @param place Place to leave permanently. | 604 | * @return Handle that can be used to cancel watching. |
627 | * @param keep_active Keep place active after last application disconnected. | 605 | */ |
606 | struct GNUNET_SOCIAL_WatchHandle * | ||
607 | GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place, | ||
608 | const char *object_filter, | ||
609 | GNUNET_PSYC_StateCallback state_cb, | ||
610 | void *state_cb_cls); | ||
611 | |||
612 | |||
613 | /** | ||
614 | * Cancel watching a place for changed objects. | ||
615 | * | ||
616 | * @param wh Watch handle to cancel. | ||
628 | */ | 617 | */ |
629 | void | 618 | void |
630 | GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place, int keep_active); | 619 | GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh); |
620 | |||
621 | |||
622 | struct GNUNET_SOCIAL_LookHandle; | ||
623 | |||
624 | |||
625 | /** | ||
626 | * Look at objects in the place with a matching name prefix. | ||
627 | * | ||
628 | * @param place The place to look its objects at. | ||
629 | * @param name_prefix Look at objects with names beginning with this value. | ||
630 | * @param state_cb Function to call for each object found. | ||
631 | * @param state_cb_cls Closure for callback function. | ||
632 | * | ||
633 | * @return Handle that can be used to stop looking at objects. | ||
634 | */ | ||
635 | struct GNUNET_SOCIAL_LookHandle * | ||
636 | GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place, | ||
637 | const char *name_prefix, | ||
638 | GNUNET_PSYC_StateCallback state_cb, | ||
639 | void *state_cb_cls); | ||
640 | |||
641 | |||
642 | /** | ||
643 | * Stop looking at objects. | ||
644 | * | ||
645 | * @param lh Look handle to stop. | ||
646 | */ | ||
647 | void | ||
648 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh); | ||
649 | |||
650 | |||
651 | |||
652 | /** | ||
653 | * Look at a particular object in the place. | ||
654 | * | ||
655 | * The best matching object is returned (its name might be less specific than | ||
656 | * what was requested). | ||
657 | * | ||
658 | * @param place The place to look the object at. | ||
659 | * @param full_name Full name of the object. | ||
660 | * @param value_size Set to the size of the returned value. | ||
661 | * @return NULL if there is no such object at this place. | ||
662 | */ | ||
663 | const void * | ||
664 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place, | ||
665 | const char *full_name, | ||
666 | size_t *value_size); | ||
631 | 667 | ||
632 | 668 | ||
633 | #if 0 /* keep Emacsens' auto-indent happy */ | 669 | #if 0 /* keep Emacsens' auto-indent happy */ |