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/social | |
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/social')
-rw-r--r-- | src/social/social_api.c | 377 |
1 files changed, 213 insertions, 164 deletions
diff --git a/src/social/social_api.c b/src/social/social_api.c index fd6e8f04a..ee13c7d61 100644 --- a/src/social/social_api.c +++ b/src/social/social_api.c | |||
@@ -20,7 +20,7 @@ | |||
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @file social/social_api.c | 22 | * @file social/social_api.c |
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 | */ | 25 | */ |
26 | 26 | ||
@@ -35,7 +35,7 @@ | |||
35 | 35 | ||
36 | 36 | ||
37 | /** | 37 | /** |
38 | * Handle for another user (who is likely pseudonymous) in the network. | 38 | * Handle for a pseudonym of another user in the network. |
39 | */ | 39 | */ |
40 | struct GNUNET_SOCIAL_Nym | 40 | struct GNUNET_SOCIAL_Nym |
41 | { | 41 | { |
@@ -53,9 +53,18 @@ struct GNUNET_SOCIAL_Place | |||
53 | 53 | ||
54 | 54 | ||
55 | /** | 55 | /** |
56 | * Handle for a place that one of our egos hosts. | 56 | * Host handle for a place that we entered. |
57 | */ | 57 | */ |
58 | struct GNUNET_SOCIAL_Home | 58 | struct GNUNET_SOCIAL_Host |
59 | { | ||
60 | |||
61 | }; | ||
62 | |||
63 | |||
64 | /** | ||
65 | * Guest handle for place that we entered. | ||
66 | */ | ||
67 | struct GNUNET_SOCIAL_Guest | ||
59 | { | 68 | { |
60 | 69 | ||
61 | }; | 70 | }; |
@@ -109,6 +118,8 @@ struct GNUNET_SOCIAL_HistoryLesson | |||
109 | }; | 118 | }; |
110 | 119 | ||
111 | 120 | ||
121 | |||
122 | |||
112 | /** | 123 | /** |
113 | * Create a try-and-slice instance. | 124 | * Create a try-and-slice instance. |
114 | * | 125 | * |
@@ -136,8 +147,8 @@ GNUNET_SOCIAL_slicer_create (void) | |||
136 | void | 147 | void |
137 | GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, | 148 | GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, |
138 | const char *method_name, | 149 | const char *method_name, |
139 | GNUNET_SOCIAL_Method method, | 150 | GNUNET_SOCIAL_MethodCallback method_cb, |
140 | void *method_cls) | 151 | void *cls) |
141 | { | 152 | { |
142 | 153 | ||
143 | } | 154 | } |
@@ -153,12 +164,11 @@ GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, | |||
153 | void | 164 | void |
154 | GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer, | 165 | GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer, |
155 | const char *method_name, | 166 | const char *method_name, |
156 | GNUNET_SOCIAL_Method method) | 167 | GNUNET_SOCIAL_MethodCallback method_cb) |
157 | { | 168 | { |
158 | 169 | ||
159 | } | 170 | } |
160 | 171 | ||
161 | |||
162 | /** | 172 | /** |
163 | * Destroy a given try-and-slice instance. | 173 | * Destroy a given try-and-slice instance. |
164 | * | 174 | * |
@@ -172,26 +182,26 @@ GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer) | |||
172 | 182 | ||
173 | 183 | ||
174 | /** | 184 | /** |
175 | * Enter a home where guests (nyms) can be hosted. | 185 | * Enter a place as host. |
176 | * | 186 | * |
177 | * A home is created upon first entering, and exists until | 187 | * A place is created upon first entering, and it is active until permanently |
178 | * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using | 188 | * left using GNUNET_SOCIAL_host_leave(). |
179 | * GNUNET_SOCIAL_home_leave(). | ||
180 | * | 189 | * |
181 | * @param cfg Configuration to contact the social service. | 190 | * @param cfg Configuration to contact the social service. |
182 | * @param home_keyfile File with the private-public key pair of the home, | 191 | * @param place_keyfile File with the private-public key pair of the place, |
183 | * created if the file does not exist; pass NULL for ephemeral homes. | 192 | * created if the file does not exist; pass NULL for ephemeral places. |
184 | * @param policy Policy specifying entry and history restrictions of the home. | 193 | * @param policy Policy specifying entry and history restrictions of the place. |
185 | * @param ego Owner of the home (host). | 194 | * @param ego Identity of the host. |
186 | * @param slicer Slicer to handle guests talking. | 195 | * @param slicer Slicer to handle incoming messages. |
187 | * @param listener_cb Function to handle new nyms that want to enter. | 196 | * @param listener_cb Function to handle new nyms that want to enter. |
188 | * @param farewell_cb Function to handle departing nyms. | 197 | * @param farewell_cb Function to handle departing nyms. |
189 | * @param cls Closure for @a listener_cb and @a farewell_cb. | 198 | * @param cls Closure for @a listener_cb and @a farewell_cb. |
190 | * @return Handle for a new home. | 199 | * |
191 | */ | 200 | * @return Handle for the host. |
192 | struct GNUNET_SOCIAL_Home * | 201 | */ |
193 | GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | 202 | struct GNUNET_SOCIAL_Host * |
194 | const char *home_keyfile, | 203 | GNUNET_SOCIAL_host_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, |
204 | const char *place_keyfile, | ||
195 | enum GNUNET_PSYC_Policy policy, | 205 | enum GNUNET_PSYC_Policy policy, |
196 | struct GNUNET_IDENTITY_Ego *ego, | 206 | struct GNUNET_IDENTITY_Ego *ego, |
197 | struct GNUNET_SOCIAL_Slicer *slicer, | 207 | struct GNUNET_SOCIAL_Slicer *slicer, |
@@ -204,16 +214,16 @@ GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
204 | 214 | ||
205 | 215 | ||
206 | /** | 216 | /** |
207 | * Admit @a nym to the @a home. | 217 | * Admit @a nym to the place. |
208 | * | 218 | * |
209 | * The @a nym reference will remain valid until either the home is destroyed or | 219 | * The @a nym reference will remain valid until either the @a host or @a nym |
210 | * @a nym leaves. | 220 | * leaves the place. |
211 | * | 221 | * |
212 | * @param home Home to allow @a nym to enter. | 222 | * @param host Host of the place. |
213 | * @param nym Handle for the entity that wants to enter. | 223 | * @param nym Handle for the entity that wants to enter. |
214 | */ | 224 | */ |
215 | void | 225 | void |
216 | GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home, | 226 | GNUNET_SOCIAL_host_admit (struct GNUNET_SOCIAL_Host *host, |
217 | struct GNUNET_SOCIAL_Nym *nym) | 227 | struct GNUNET_SOCIAL_Nym *nym) |
218 | { | 228 | { |
219 | 229 | ||
@@ -221,17 +231,17 @@ GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home, | |||
221 | 231 | ||
222 | 232 | ||
223 | /** | 233 | /** |
224 | * Throw @a nym out of the @a home. | 234 | * Throw @a nym out of the place. |
225 | * | 235 | * |
226 | * The @a nym reference will remain valid until the | 236 | * The @a nym reference will remain valid until the |
227 | * #GNUNET_SOCIAL_FarewellCallback is invoked, | 237 | * #GNUNET_SOCIAL_FarewellCallback is invoked, |
228 | * which should be very soon after this call. | 238 | * which should be very soon after this call. |
229 | * | 239 | * |
230 | * @param home Home to eject @a nym from. | 240 | * @param host Host of the place. |
231 | * @param nym Handle for the entity to be ejected. | 241 | * @param nym Handle for the entity to be ejected. |
232 | */ | 242 | */ |
233 | void | 243 | void |
234 | GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | 244 | GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host, |
235 | struct GNUNET_SOCIAL_Nym *nym) | 245 | struct GNUNET_SOCIAL_Nym *nym) |
236 | { | 246 | { |
237 | 247 | ||
@@ -239,9 +249,9 @@ GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | |||
239 | 249 | ||
240 | 250 | ||
241 | /** | 251 | /** |
242 | * Refuse @a nym entry into the @a home. | 252 | * Refuse @a nym entry into the place. |
243 | * | 253 | * |
244 | * @param home Home to disallow @a nym to enter. | 254 | * @param host Host of the place. |
245 | * @param nym Handle for the entity that wanted to enter. | 255 | * @param nym Handle for the entity that wanted to enter. |
246 | * @param method_name Method name for the rejection message. | 256 | * @param method_name Method name for the rejection message. |
247 | * @param env Environment containing variables for the message, or NULL. | 257 | * @param env Environment containing variables for the message, or NULL. |
@@ -249,7 +259,7 @@ GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | |||
249 | * @param data_size Number of bytes in @a data for method. | 259 | * @param data_size Number of bytes in @a data for method. |
250 | */ | 260 | */ |
251 | void | 261 | void |
252 | GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home, | 262 | GNUNET_SOCIAL_host_refuse_entry (struct GNUNET_SOCIAL_Host *host, |
253 | struct GNUNET_SOCIAL_Nym *nym, | 263 | struct GNUNET_SOCIAL_Nym *nym, |
254 | const char *method_name, | 264 | const char *method_name, |
255 | const struct GNUNET_ENV_Environment *env, | 265 | const struct GNUNET_ENV_Environment *env, |
@@ -261,7 +271,7 @@ GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home, | |||
261 | 271 | ||
262 | 272 | ||
263 | /** | 273 | /** |
264 | * Get the public key of a nym. | 274 | * Get the public key of a @a nym. |
265 | * | 275 | * |
266 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). | 276 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). |
267 | * | 277 | * |
@@ -277,23 +287,25 @@ GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym, | |||
277 | 287 | ||
278 | 288 | ||
279 | /** | 289 | /** |
280 | * Obtain the private-public key pair of the home. | 290 | * Obtain the private-public key pair of the host. |
281 | * | 291 | * |
282 | * @param home Home to get the key of. | 292 | * @param host Host to get the key of. |
283 | * @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. | 293 | * @param[out] host_key Set to the private-public key pair of the host. The |
294 | * public part is suitable for storing in GNS within a "PLACE" | ||
295 | * record, along with peer IDs to join at. | ||
284 | */ | 296 | */ |
285 | void | 297 | void |
286 | GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home, | 298 | GNUNET_SOCIAL_host_get_key (struct GNUNET_SOCIAL_Host *host, |
287 | struct GNUNET_CRYPTO_EddsaPrivateKey *home_key) | 299 | struct GNUNET_CRYPTO_EddsaPrivateKey *host_key) |
288 | { | 300 | { |
289 | 301 | ||
290 | } | 302 | } |
291 | 303 | ||
292 | 304 | ||
293 | /** | 305 | /** |
294 | * Advertise @a home under @a name in the GNS zone of the @e ego. | 306 | * Advertise the place in the GNS zone of the @e ego of the @a host. |
295 | * | 307 | * |
296 | * @param home The home to advertise. | 308 | * @param host Host of the place. |
297 | * @param name The name for the PLACE record to put in the zone. | 309 | * @param name The name for the PLACE record to put in the zone. |
298 | * @param peer_count Number of elements in the @a peers array. | 310 | * @param peer_count Number of elements in the @a peers array. |
299 | * @param peers List of peers in the PLACE record that can be used to send join | 311 | * @param peers List of peers in the PLACE record that can be used to send join |
@@ -302,7 +314,7 @@ GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home, | |||
302 | * @param password Password used to encrypt the record. | 314 | * @param password Password used to encrypt the record. |
303 | */ | 315 | */ |
304 | void | 316 | void |
305 | GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home, | 317 | GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host, |
306 | const char *name, | 318 | const char *name, |
307 | size_t peer_count, | 319 | size_t peer_count, |
308 | const struct GNUNET_PeerIdentity *peers, | 320 | const struct GNUNET_PeerIdentity *peers, |
@@ -314,22 +326,23 @@ GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home, | |||
314 | 326 | ||
315 | 327 | ||
316 | /** | 328 | /** |
317 | * Send a message to all nyms that are present in the home. | 329 | * Send a message to all nyms that are present in the place. |
318 | * | 330 | * |
319 | * This function is restricted to the home owner. Nyms can only send requests | 331 | * This function is restricted to the host. Nyms can only send requests |
320 | * to the home owner who can decide to relay it to other guests. | 332 | * to the host who can decide to relay it to everyone in the place. |
321 | * | 333 | * |
322 | * @param home Home to address the announcement to. | 334 | * @param host Host of the place. |
323 | * @param method_name Method to use for the announcement. | 335 | * @param method_name Method to use for the announcement. |
324 | * @param env Environment containing variables for the message and operations on | 336 | * @param env Environment containing variables for the message and operations |
325 | * objects of the home, or NULL. | 337 | * on objects of the place. Can be NULL. |
326 | * @param notify Function to call to get the payload of the announcement. | 338 | * @param notify Function to call to get the payload of the announcement. |
327 | * @param notify_cls Closure for @a notify. | 339 | * @param notify_cls Closure for @a notify. |
328 | * @param flags Flags for this announcement. | 340 | * @param flags Flags for this announcement. |
341 | * | ||
329 | * @return NULL on error (announcement already in progress?). | 342 | * @return NULL on error (announcement already in progress?). |
330 | */ | 343 | */ |
331 | struct GNUNET_SOCIAL_Announcement * | 344 | struct GNUNET_SOCIAL_Announcement * |
332 | GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home, | 345 | GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host, |
333 | const char *method_name, | 346 | const char *method_name, |
334 | const struct GNUNET_ENV_Environment *env, | 347 | const struct GNUNET_ENV_Environment *env, |
335 | GNUNET_CONNECTION_TransmitReadyNotify notify, | 348 | GNUNET_CONNECTION_TransmitReadyNotify notify, |
@@ -346,46 +359,48 @@ GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home, | |||
346 | * @param a The announcement to cancel. | 359 | * @param a The announcement to cancel. |
347 | */ | 360 | */ |
348 | void | 361 | void |
349 | GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a) | 362 | GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a) |
350 | { | 363 | { |
351 | 364 | ||
352 | } | 365 | } |
353 | 366 | ||
354 | 367 | ||
355 | /** | 368 | /** |
356 | * Convert our home to a place so we can access it via the place API. | 369 | * Obtain handle for a hosted place. |
370 | * | ||
371 | * The returned handle can be used to access the place API. | ||
357 | * | 372 | * |
358 | * @param home Handle for the home. | 373 | * @param host Handle for the host. |
359 | * @return Place handle for the same home, valid as long as @a home is valid; | 374 | * |
360 | * do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home! | 375 | * @return Handle for the hosted place, valid as long as @a host is valid. |
361 | */ | 376 | */ |
362 | struct GNUNET_SOCIAL_Place * | 377 | struct GNUNET_SOCIAL_Place * |
363 | GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home) | 378 | GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host) |
364 | { | 379 | { |
365 | return NULL; | 380 | return NULL; |
366 | } | 381 | } |
367 | 382 | ||
368 | 383 | ||
369 | /** | 384 | /** |
370 | * Leave a home. | 385 | * Stop hosting a place. |
371 | |||
372 | * Invalidates home handle. | ||
373 | * Guests will be disconnected until the home is restarted. | ||
374 | * | 386 | * |
375 | * @param home Home to leave. | 387 | * Invalidates host handle. |
376 | * @param keep_active Keep home active after last application disconnected. | 388 | * |
389 | * @param host Host leaving the place. | ||
390 | * @param keep_active Keep the place active after last host disconnected. | ||
377 | */ | 391 | */ |
378 | void | 392 | void |
379 | GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home, int keep_active) | 393 | GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host, int keep_active) |
380 | { | 394 | { |
381 | 395 | ||
382 | } | 396 | } |
383 | 397 | ||
398 | |||
384 | /** | 399 | /** |
385 | * Request entry to a place (home hosted by someone else). | 400 | * Request entry to a place as a guest. |
386 | * | 401 | * |
387 | * @param cfg Configuration to contact the social service. | 402 | * @param cfg Configuration to contact the social service. |
388 | * @param ego Owner of the home (host). | 403 | * @param ego Identity of the guest. |
389 | * @param address GNS name of the place to enter. Either in the form of | 404 | * @param address GNS name of the place to enter. Either in the form of |
390 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to | 405 | * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to |
391 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the | 406 | * the 'PLACE' record of the empty label ("+") in the GNS zone with the |
@@ -396,10 +411,11 @@ GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home, int keep_active) | |||
396 | * @param data Payload for the message to give to the enter callback. | 411 | * @param data Payload for the message to give to the enter callback. |
397 | * @param data_size Number of bytes in @a data. | 412 | * @param data_size Number of bytes in @a data. |
398 | * @param slicer Slicer to use for processing incoming requests from guests. | 413 | * @param slicer Slicer to use for processing incoming requests from guests. |
399 | * @return NULL on errors, otherwise handle to the place. | 414 | * |
415 | * @return NULL on errors, otherwise handle for the guest. | ||
400 | */ | 416 | */ |
401 | struct GNUNET_SOCIAL_Place * | 417 | struct GNUNET_SOCIAL_Guest * |
402 | GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | 418 | GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, |
403 | struct GNUNET_IDENTITY_Ego *ego, | 419 | struct GNUNET_IDENTITY_Ego *ego, |
404 | char *address, | 420 | char *address, |
405 | const char *method_name, | 421 | const char *method_name, |
@@ -412,10 +428,10 @@ GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
412 | } | 428 | } |
413 | 429 | ||
414 | /** | 430 | /** |
415 | * Request entry to a place (home hosted by someone else). | 431 | * Request entry to a place as a guest. |
416 | * | 432 | * |
417 | * @param cfg Configuration to contact the social service. | 433 | * @param cfg Configuration to contact the social service. |
418 | * @param ego Owner of the home (host). | 434 | * @param ego Identity of the guest. |
419 | * @param crypto_address Public key of the place to enter. | 435 | * @param crypto_address Public key of the place to enter. |
420 | * @param origin Peer identity of the origin of the underlying multicast group. | 436 | * @param origin Peer identity of the origin of the underlying multicast group. |
421 | * @param relay_count Number of elements in the @a relays array. | 437 | * @param relay_count Number of elements in the @a relays array. |
@@ -425,10 +441,11 @@ GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
425 | * @param data Payload for the message to give to the enter callback. | 441 | * @param data Payload for the message to give to the enter callback. |
426 | * @param data_size Number of bytes in @a data. | 442 | * @param data_size Number of bytes in @a data. |
427 | * @param slicer Slicer to use for processing incoming requests from guests. | 443 | * @param slicer Slicer to use for processing incoming requests from guests. |
428 | * @return NULL on errors, otherwise handle to the place. | 444 | * |
445 | * @return NULL on errors, otherwise handle for the guest. | ||
429 | */ | 446 | */ |
430 | struct GNUNET_SOCIAL_Place * | 447 | struct GNUNET_SOCIAL_Guest * |
431 | GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, | 448 | GNUNET_SOCIAL_guest_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, |
432 | struct GNUNET_IDENTITY_Ego *ego, | 449 | struct GNUNET_IDENTITY_Ego *ego, |
433 | struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address, | 450 | struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address, |
434 | struct GNUNET_PeerIdentity *origin, | 451 | struct GNUNET_PeerIdentity *origin, |
@@ -445,125 +462,77 @@ GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
445 | 462 | ||
446 | 463 | ||
447 | /** | 464 | /** |
448 | * Watch a place for changed objects. | 465 | * Talk to the host of the place. |
449 | * | 466 | * |
450 | * @param place Place to watch. | 467 | * @param place Place where we want to talk to the host. |
451 | * @param object_filter Object prefix to match. | 468 | * @param method_name Method to invoke on the host. |
452 | * @param state_cb Function to call when an object/state changes. | 469 | * @param env Environment containing variables for the message, or NULL. |
453 | * @param state_cb_cls Closure for callback. | 470 | * @param notify Function to use to get the payload for the method. |
471 | * @param notify_cls Closure for @a notify. | ||
472 | * @param flags Flags for the message being sent. | ||
454 | * | 473 | * |
455 | * @return Handle that can be used to cancel watching. | 474 | * @return NULL if we are already trying to talk to the host, |
475 | * otherwise handle to cancel the request. | ||
456 | */ | 476 | */ |
457 | struct GNUNET_SOCIAL_WatchHandle * | 477 | struct GNUNET_SOCIAL_TalkRequest * |
458 | GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place, | 478 | GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Place *place, |
459 | const char *object_filter, | 479 | const char *method_name, |
460 | GNUNET_PSYC_StateCallback state_cb, | 480 | const struct GNUNET_ENV_Environment *env, |
461 | void *state_cb_cls) | 481 | GNUNET_CONNECTION_TransmitReadyNotify notify, |
482 | void *notify_cls, | ||
483 | enum GNUNET_SOCIAL_TalkFlags flags) | ||
462 | { | 484 | { |
463 | return NULL; | 485 | return NULL; |
464 | } | 486 | } |
465 | 487 | ||
466 | 488 | ||
467 | /** | 489 | /** |
468 | * Cancel watching a place for changed objects. | 490 | * Cancel talking to the host of the place. |
469 | * | 491 | * |
470 | * @param wh Watch handle to cancel. | 492 | * @param tr Talk request to cancel. |
471 | */ | 493 | */ |
472 | void | 494 | void |
473 | GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh) | 495 | GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr) |
474 | { | 496 | { |
475 | 497 | ||
476 | } | 498 | } |
477 | 499 | ||
478 | 500 | ||
479 | /** | 501 | /** |
480 | * Look at objects in the place with a matching name prefix. | 502 | * Leave a place permanently. |
481 | * | ||
482 | * @param place The place to look its objects at. | ||
483 | * @param name_prefix Look at objects with names beginning with this value. | ||
484 | * @param state_cb Function to call for each object found. | ||
485 | * @param state_cb_cls Closure for callback function. | ||
486 | * | 503 | * |
487 | * @return Handle that can be used to stop looking at objects. | 504 | * Notifies the owner of the place about leaving, and destroys the place handle. |
488 | */ | ||
489 | struct GNUNET_SOCIAL_LookHandle * | ||
490 | GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place, | ||
491 | const char *name_prefix, | ||
492 | GNUNET_PSYC_StateCallback state_cb, | ||
493 | void *state_cb_cls) | ||
494 | { | ||
495 | return NULL; | ||
496 | } | ||
497 | |||
498 | |||
499 | /** | ||
500 | * Stop looking at objects. | ||
501 | * | 505 | * |
502 | * @param lh Look handle to stop. | 506 | * @param place Place to leave permanently. |
507 | * @param keep_active Keep place active after last application disconnected. | ||
503 | */ | 508 | */ |
504 | void | 509 | void |
505 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh) | 510 | GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Place *place, int keep_active) |
506 | { | 511 | { |
507 | 512 | ||
508 | } | 513 | } |
509 | 514 | ||
510 | 515 | ||
511 | |||
512 | /** | 516 | /** |
513 | * Look at a particular object in the place. | 517 | * Obtain handle for a place entered as guest. |
514 | * | 518 | * |
515 | * The best matching object is returned (its name might be less specific than | 519 | * The returned handle can be used to access the place API. |
516 | * what was requested). | ||
517 | * | 520 | * |
518 | * @param place The place to look the object at. | 521 | * @param guest Handle for the guest. |
519 | * @param full_name Full name of the object. | ||
520 | * @param value_size Set to the size of the returned value. | ||
521 | * @return NULL if there is no such object at this place. | ||
522 | */ | ||
523 | const void * | ||
524 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place, | ||
525 | const char *full_name, | ||
526 | size_t *value_size) | ||
527 | { | ||
528 | return NULL; | ||
529 | } | ||
530 | |||
531 | |||
532 | /** | ||
533 | * Talk to the host of the place. | ||
534 | * | 522 | * |
535 | * @param place Place where we want to talk to the host. | 523 | * @return Handle for the place, valid as long as @a guest is valid. |
536 | * @param method_name Method to invoke on the host. | ||
537 | * @param env Environment containing variables for the message, or NULL. | ||
538 | * @param notify Function to use to get the payload for the method. | ||
539 | * @param notify_cls Closure for @a notify. | ||
540 | * @param flags Flags for the message being sent. | ||
541 | * @return NULL if we are already trying to talk to the host, | ||
542 | * otherwise handle to cancel the request. | ||
543 | */ | 524 | */ |
544 | struct GNUNET_SOCIAL_TalkRequest * | 525 | struct GNUNET_SOCIAL_Place * |
545 | GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place, | 526 | GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Host *guest) |
546 | const char *method_name, | ||
547 | const struct GNUNET_ENV_Environment *env, | ||
548 | GNUNET_CONNECTION_TransmitReadyNotify notify, | ||
549 | void *notify_cls, | ||
550 | enum GNUNET_SOCIAL_TalkFlags flags) | ||
551 | { | 527 | { |
552 | return NULL; | 528 | return NULL; |
553 | } | 529 | } |
554 | 530 | ||
555 | 531 | ||
556 | /** | 532 | /** |
557 | * Cancel talking to the host of the place. | 533 | * A history lesson. |
558 | * | ||
559 | * @param tr Talk request to cancel. | ||
560 | */ | 534 | */ |
561 | void | 535 | struct GNUNET_SOCIAL_HistoryLesson; |
562 | GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr) | ||
563 | { | ||
564 | |||
565 | } | ||
566 | |||
567 | 536 | ||
568 | /** | 537 | /** |
569 | * Learn about the history of a place. | 538 | * Learn about the history of a place. |
@@ -612,16 +581,96 @@ GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist | |||
612 | } | 581 | } |
613 | 582 | ||
614 | 583 | ||
584 | struct GNUNET_SOCIAL_WatchHandle; | ||
585 | |||
615 | /** | 586 | /** |
616 | * Leave a place permanently. | 587 | * Watch a place for changed objects. |
617 | * | 588 | * |
618 | * Notifies the owner of the place about leaving, and destroys the place handle. | 589 | * @param place Place to watch. |
590 | * @param object_filter Object prefix to match. | ||
591 | * @param state_cb Function to call when an object/state changes. | ||
592 | * @param state_cb_cls Closure for callback. | ||
619 | * | 593 | * |
620 | * @param place Place to leave permanently. | 594 | * @return Handle that can be used to cancel watching. |
621 | * @param keep_active Keep place active after last application disconnected. | 595 | */ |
596 | struct GNUNET_SOCIAL_WatchHandle * | ||
597 | GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place, | ||
598 | const char *object_filter, | ||
599 | GNUNET_PSYC_StateCallback state_cb, | ||
600 | void *state_cb_cls) | ||
601 | { | ||
602 | return NULL; | ||
603 | } | ||
604 | |||
605 | |||
606 | /** | ||
607 | * Cancel watching a place for changed objects. | ||
608 | * | ||
609 | * @param wh Watch handle to cancel. | ||
610 | */ | ||
611 | void | ||
612 | GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh) | ||
613 | { | ||
614 | |||
615 | } | ||
616 | |||
617 | |||
618 | struct GNUNET_SOCIAL_LookHandle; | ||
619 | |||
620 | |||
621 | /** | ||
622 | * Look at objects in the place with a matching name prefix. | ||
623 | * | ||
624 | * @param place The place to look its objects at. | ||
625 | * @param name_prefix Look at objects with names beginning with this value. | ||
626 | * @param state_cb Function to call for each object found. | ||
627 | * @param state_cb_cls Closure for callback function. | ||
628 | * | ||
629 | * @return Handle that can be used to stop looking at objects. | ||
630 | */ | ||
631 | struct GNUNET_SOCIAL_LookHandle * | ||
632 | GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place, | ||
633 | const char *name_prefix, | ||
634 | GNUNET_PSYC_StateCallback state_cb, | ||
635 | void *state_cb_cls) | ||
636 | { | ||
637 | return NULL; | ||
638 | } | ||
639 | |||
640 | |||
641 | /** | ||
642 | * Stop looking at objects. | ||
643 | * | ||
644 | * @param lh Look handle to stop. | ||
622 | */ | 645 | */ |
623 | void | 646 | void |
624 | GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place, int keep_active) | 647 | GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh) |
625 | { | 648 | { |
626 | 649 | ||
627 | } | 650 | } |
651 | |||
652 | |||
653 | |||
654 | /** | ||
655 | * Look at a particular object in the place. | ||
656 | * | ||
657 | * The best matching object is returned (its name might be less specific than | ||
658 | * what was requested). | ||
659 | * | ||
660 | * @param place The place to look the object at. | ||
661 | * @param full_name Full name of the object. | ||
662 | * @param value_size Set to the size of the returned value. | ||
663 | * @return NULL if there is no such object at this place. | ||
664 | */ | ||
665 | const void * | ||
666 | GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place, | ||
667 | const char *full_name, | ||
668 | size_t *value_size) | ||
669 | { | ||
670 | return NULL; | ||
671 | } | ||
672 | |||
673 | |||
674 | |||
675 | |||
676 | /* end of social_api.c */ | ||