src/set/set_api.c

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2012, 2013 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file set/set_api.c
  23  * @brief api for the set service
  24  * @author Florian Dold
  25  */
  26 #include "platform.h"
  27 #include "gnunet_util_lib.h"
  28 #include "gnunet_protocols.h"
  29 #include "gnunet_client_lib.h"
  30 #include "gnunet_set_service.h"
  31 #include "set.h"
  32
  33
  34 #define LOG(kind,...) GNUNET_log_from (kind, "set-api",__VA_ARGS__)
  35
  36 /**
  37  * Opaque handle to a set.
  38  */
  39 struct GNUNET_SET_Handle
  40 {
  41   struct GNUNET_CLIENT_Connection *client;
  42   struct GNUNET_MQ_Handle *mq;
  43   unsigned int messages_since_ack;
  44   struct GNUNET_SET_OperationHandle *ops_head;
  45   struct GNUNET_SET_OperationHandle *ops_tail;
  46   int destroy_requested;
  47 };
  48
  49
  50 /**
  51  * Opaque handle to a set operation request from another peer.
  52  */
  53 struct GNUNET_SET_Request
  54 {
  55   /**
  56    * Id of the request, used to identify the request when
  57    * accepting/rejecting it.
  58    */
  59   uint32_t accept_id;
  60
  61   /**
  62    * Has the request been accepted already?
  63    * GNUNET_YES/GNUNET_NO
  64    */
  65   int accepted;
  66 };
  67
  68
  69 /**
  70  * Handle to an operation.
  71  * Only known to the service after commiting
  72  * the handle with a set.
  73  */
  74 struct GNUNET_SET_OperationHandle
  75 {
  76   /**
  77    * Function to be called when we have a result,
  78    * or an error.
  79    */
  80   GNUNET_SET_ResultIterator result_cb;
  81
  82   /**
  83    * Closure for result_cb.
  84    */
  85   void *result_cls;
  86
  87   /**
  88    * Local set used for the operation,
  89    * NULL if no set has been provided by conclude yet.
  90    */
  91   struct GNUNET_SET_Handle *set;
  92
  93   /**
  94    * Request ID to identify the operation within the set.
  95    */
  96   uint32_t request_id;
  97
  98   /**
  99    * Message sent to the server on calling conclude,
 100    * NULL if conclude has been called.
 101    */
 102   struct GNUNET_MQ_Envelope *conclude_mqm;
 103
 104   /**
 105    * Address of the request if in the conclude message,
 106    * used to patch the request id into the message when the set is known.
 107    */
 108   uint32_t *request_id_addr;
 109
 110   /**
 111    * Handles are kept in a linked list.
 112    */
 113   struct GNUNET_SET_OperationHandle *prev;
 114
 115   /**
 116    * Handles are kept in a linked list.
 117    */
 118   struct GNUNET_SET_OperationHandle *next;
 119
 120 };
 121
 122
 123 /**
 124  * Opaque handle to a listen operation.
 125  */
 126 struct GNUNET_SET_ListenHandle
 127 {
 128   /**
 129    * Connection to the service.
 130    */
 131   struct GNUNET_CLIENT_Connection *client;
 132
 133   /**
 134    * Message queue for the client.
 135    */
 136   struct GNUNET_MQ_Handle* mq;
 137
 138   /**
 139    * Function to call on a new incoming request,
 140    * or on error.
 141    */
 142   GNUNET_SET_ListenCallback listen_cb;
 143
 144   /**
 145    * Closure for listen_cb.
 146    */
 147   void *listen_cls;
 148 };
 149
 150
 151 /**
 152  * Handle result message for a set operation.
 153  *
 154  * @param cls the set
 155  * @param mh the message
 156  */
 157 static void
 158 handle_result (void *cls, const struct GNUNET_MessageHeader *mh)
 159 {
 160   struct GNUNET_SET_ResultMessage *msg = (struct GNUNET_SET_ResultMessage *) mh;
 161   struct GNUNET_SET_Handle *set = cls;
 162   struct GNUNET_SET_OperationHandle *oh;
 163   struct GNUNET_SET_Element e;
 164   enum GNUNET_SET_Status result_status;
 165
 166   GNUNET_assert (NULL != set);
 167   GNUNET_assert (NULL != set->mq);
 168
 169   result_status = ntohs (msg->result_status);
 170
 171   if (set->messages_since_ack >= GNUNET_SET_ACK_WINDOW/2)
 172   {
 173     struct GNUNET_MQ_Envelope *mqm;
 174     mqm = GNUNET_MQ_msg_header (GNUNET_MESSAGE_TYPE_SET_ACK);
 175     GNUNET_MQ_send (set->mq, mqm);
 176   }
 177   oh = GNUNET_MQ_assoc_get (set->mq, ntohl (msg->request_id));
 178   GNUNET_assert (NULL != oh);
 179   /* status is not STATUS_OK => there's no attached element,
 180    * and this is the last result message we get */
 181   if (GNUNET_SET_STATUS_OK != result_status)
 182   {
 183     GNUNET_MQ_assoc_remove (set->mq, ntohl (msg->request_id));
 184     GNUNET_CONTAINER_DLL_remove (oh->set->ops_head, oh->set->ops_tail, oh);
 185     if (GNUNET_YES == oh->set->destroy_requested)
 186       GNUNET_SET_destroy (oh->set);
 187     if (NULL != oh->result_cb)
 188       oh->result_cb (oh->result_cls, NULL, result_status);
 189     GNUNET_free (oh);
 190     return;
 191   }
 192
 193   e.data = &msg[1];
 194   e.size = ntohs (mh->size) - sizeof (struct GNUNET_SET_ResultMessage);
 195   e.type = msg->element_type;
 196   if (NULL != oh->result_cb)
 197     oh->result_cb (oh->result_cls, &e, result_status);
 198 }
 199
 200 /**
 201  * Handle request message for a listen operation
 202  *
 203  * @param cls the listen handle
 204  * @param mh the message
 205  */
 206 static void
 207 handle_request (void *cls, const struct GNUNET_MessageHeader *mh)
 208 {
 209   struct GNUNET_SET_RequestMessage *msg = (struct GNUNET_SET_RequestMessage *) mh;
 210   struct GNUNET_SET_ListenHandle *lh = cls;
 211   struct GNUNET_SET_Request *req;
 212   struct GNUNET_MessageHeader *context_msg;
 213
 214   LOG (GNUNET_ERROR_TYPE_DEBUG, "processing operation request\n");
 215   req = GNUNET_new (struct GNUNET_SET_Request);
 216   req->accept_id = ntohl (msg->accept_id);
 217   context_msg = GNUNET_MQ_extract_nested_mh (msg);
 218   /* calling GNUNET_SET_accept in the listen cb will set req->accepted */
 219   lh->listen_cb (lh->listen_cls, &msg->peer_id, context_msg, req);
 220
 221   if (GNUNET_NO == req->accepted)
 222   {
 223     struct GNUNET_MQ_Envelope *mqm;
 224     struct GNUNET_SET_AcceptRejectMessage *amsg;
 225
 226     mqm = GNUNET_MQ_msg (amsg, GNUNET_MESSAGE_TYPE_SET_REJECT);
 227     /* no request id, as we refused */
 228     amsg->request_id = htonl (0);
 229     amsg->accept_reject_id = msg->accept_id;
 230     GNUNET_MQ_send (lh->mq, mqm);
 231     GNUNET_free (req);
 232     LOG (GNUNET_ERROR_TYPE_DEBUG, "rejecting request\n");
 233   }
 234
 235   LOG (GNUNET_ERROR_TYPE_DEBUG, "processed op request from service\n");
 236
 237   /* the accept-case is handled in GNUNET_SET_accept,
 238    * as we have the accept message available there */
 239 }
 240
 241
 242 static void
 243 handle_client_listener_error (void *cls, enum GNUNET_MQ_Error error)
 244 {
 245   struct GNUNET_SET_ListenHandle *lh = cls;
 246
 247   lh->listen_cb (lh->listen_cls, NULL, NULL, NULL);
 248 }
 249
 250
 251 static void
 252 handle_client_set_error (void *cls, enum GNUNET_MQ_Error error)
 253 {
 254   struct GNUNET_SET_Handle *set = cls;
 255
 256   while (NULL != set->ops_head)
 257   {
 258     if (NULL != set->ops_head->result_cb)
 259       set->ops_head->result_cb (set->ops_head->result_cls, NULL,
 260                                 GNUNET_SET_STATUS_FAILURE);
 261     GNUNET_SET_operation_cancel (set->ops_head);
 262   }
 263
 264   /* FIXME: there should be a set error handler */
 265 }
 266
 267
 268 /**
 269  * Create an empty set, supporting the specified operation.
 270  *
 271  * @param cfg configuration to use for connecting to the
 272  *        set service
 273  * @param op operation supported by the set
 274  *        Note that the operation has to be specified
 275  *        beforehand, as certain set operations need to maintain
 276  *        data structures spefific to the operation
 277  * @return a handle to the set
 278  */
 279 struct GNUNET_SET_Handle *
 280 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 281                    enum GNUNET_SET_OperationType op)
 282 {
 283   struct GNUNET_SET_Handle *set;
 284   struct GNUNET_MQ_Envelope *mqm;
 285   struct GNUNET_SET_CreateMessage *msg;
 286   static const struct GNUNET_MQ_MessageHandler mq_handlers[] = {
 287     {handle_result, GNUNET_MESSAGE_TYPE_SET_RESULT, 0},
 288     GNUNET_MQ_HANDLERS_END
 289   };
 290
 291   set = GNUNET_new (struct GNUNET_SET_Handle);
 292   set->client = GNUNET_CLIENT_connect ("set", cfg);
 293   LOG (GNUNET_ERROR_TYPE_DEBUG, "set client created\n");
 294   GNUNET_assert (NULL != set->client);
 295   set->mq = GNUNET_MQ_queue_for_connection_client (set->client, mq_handlers,
 296                                                    handle_client_set_error, set);
 297   GNUNET_assert (NULL != set->mq);
 298   mqm = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_SET_CREATE);
 299   msg->operation = htons (op);
 300   GNUNET_MQ_send (set->mq, mqm);
 301   return set;
 302 }
 303
 304
 305 /**
 306  * Add an element to the given set.
 307  * After the element has been added (in the sense of being
 308  * transmitted to the set service), cont will be called.
 309  * Calls to add_element can be queued
 310  *
 311  * @param set set to add element to
 312  * @param element element to add to the set
 313  * @param cont continuation called after the element has been added
 314  * @param cont_cls closure for cont
 315  */
 316 void
 317 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
 318                         const struct GNUNET_SET_Element *element,
 319                         GNUNET_SET_Continuation cont,
 320                         void *cont_cls)
 321 {
 322   struct GNUNET_MQ_Envelope *mqm;
 323   struct GNUNET_SET_ElementMessage *msg;
 324
 325   mqm = GNUNET_MQ_msg_extra (msg, element->size, GNUNET_MESSAGE_TYPE_SET_ADD);
 326   msg->element_type = element->type;
 327   memcpy (&msg[1], element->data, element->size);
 328   GNUNET_MQ_notify_sent (mqm, cont, cont_cls);
 329   GNUNET_MQ_send (set->mq, mqm);
 330 }
 331
 332
 333 /**
 334  * Remove an element to the given set.
 335  * After the element has been removed (in the sense of the
 336  * request being transmitted to the set service), cont will be called.
 337  * Calls to remove_element can be queued
 338  *
 339  * @param set set to remove element from
 340  * @param element element to remove from the set
 341  * @param cont continuation called after the element has been removed
 342  * @param cont_cls closure for cont
 343  */
 344 void
 345 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
 346                            const struct GNUNET_SET_Element *element,
 347                            GNUNET_SET_Continuation cont,
 348                            void *cont_cls)
 349 {
 350   struct GNUNET_MQ_Envelope *mqm;
 351   struct GNUNET_SET_ElementMessage *msg;
 352
 353   mqm = GNUNET_MQ_msg_extra (msg, element->size, GNUNET_MESSAGE_TYPE_SET_REMOVE);
 354   msg->element_type = element->type;
 355   memcpy (&msg[1], element->data, element->size);
 356   GNUNET_MQ_notify_sent (mqm, cont, cont_cls);
 357   GNUNET_MQ_send (set->mq, mqm);
 358 }
 359
 360
 361 /**
 362  * Destroy the set handle, and free all associated resources.
 363  */
 364 void
 365 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set)
 366 {
 367   if (NULL != set->ops_head)
 368   {
 369     set->destroy_requested = GNUNET_YES;
 370     return;
 371   }
 372   GNUNET_CLIENT_disconnect (set->client);
 373   set->client = NULL;
 374   GNUNET_MQ_destroy (set->mq);
 375   set->mq = NULL;
 376 }
 377
 378
 379 /**
 380  * Prepare a set operation to be evaluated with another peer.
 381  * The evaluation will not start until the client provides
 382  * a local set with GNUNET_SET_commit.
 383  *
 384  * @param other_peer peer with the other set
 385  * @param app_id hash for the application using the set
 386  * @param context_msg additional information for the request
 387  * @param salt salt used for the set operation; sometimes set operations
 388  *        fail due to hash collisions, using a different salt for each operation
 389  *        makes it harder for an attacker to exploit this
 390  * @param result_mode specified how results will be returned,
 391  *        see 'GNUNET_SET_ResultMode'.
 392  * @param result_cb called on error or success
 393  * @param result_cls closure for result_cb
 394  * @return a handle to cancel the operation
 395  */
 396 struct GNUNET_SET_OperationHandle *
 397 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
 398                     const struct GNUNET_HashCode *app_id,
 399                     const struct GNUNET_MessageHeader *context_msg,
 400                     uint16_t salt,
 401                     enum GNUNET_SET_ResultMode result_mode,
 402                     GNUNET_SET_ResultIterator result_cb,
 403                     void *result_cls)
 404 {
 405   struct GNUNET_MQ_Envelope *mqm;
 406   struct GNUNET_SET_OperationHandle *oh;
 407   struct GNUNET_SET_EvaluateMessage *msg;
 408
 409   oh = GNUNET_new (struct GNUNET_SET_OperationHandle);
 410   oh->result_cb = result_cb;
 411   oh->result_cls = result_cls;
 412
 413   mqm = GNUNET_MQ_msg_nested_mh (msg, GNUNET_MESSAGE_TYPE_SET_EVALUATE, context_msg);
 414
 415   msg->app_id = *app_id;
 416   msg->target_peer = *other_peer;
 417   msg->salt = salt;
 418   msg->reserved = 0;
 419   oh->conclude_mqm = mqm;
 420   oh->request_id_addr = &msg->request_id;
 421
 422   return oh;
 423 }
 424
 425 /**
 426  * Wait for set operation requests for the given application id
 427  *
 428  * @param cfg configuration to use for connecting to
 429  *            the set service
 430  * @param operation operation we want to listen for
 431  * @param app_id id of the application that handles set operation requests
 432  * @param listen_cb called for each incoming request matching the operation
 433  *                  and application id
 434  * @param listen_cls handle for listen_cb
 435  * @return a handle that can be used to cancel the listen operation
 436  */
 437 struct GNUNET_SET_ListenHandle *
 438 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
 439                    enum GNUNET_SET_OperationType operation,
 440                    const struct GNUNET_HashCode *app_id,
 441                    GNUNET_SET_ListenCallback listen_cb,
 442                    void *listen_cls)
 443 {
 444   struct GNUNET_SET_ListenHandle *lh;
 445   struct GNUNET_MQ_Envelope *mqm;
 446   struct GNUNET_SET_ListenMessage *msg;
 447   static const struct GNUNET_MQ_MessageHandler mq_handlers[] = {
 448     {handle_request, GNUNET_MESSAGE_TYPE_SET_REQUEST},
 449     GNUNET_MQ_HANDLERS_END
 450   };
 451
 452   lh = GNUNET_new (struct GNUNET_SET_ListenHandle);
 453   lh->client = GNUNET_CLIENT_connect ("set", cfg);
 454   lh->listen_cb = listen_cb;
 455   lh->listen_cls = listen_cls;
 456   GNUNET_assert (NULL != lh->client);
 457   lh->mq = GNUNET_MQ_queue_for_connection_client (lh->client, mq_handlers,
 458                                                   handle_client_listener_error, lh);
 459   mqm = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_SET_LISTEN);
 460   msg->operation = htons (operation);
 461   msg->app_id = *app_id;
 462   GNUNET_MQ_send (lh->mq, mqm);
 463
 464   return lh;
 465 }
 466
 467
 468 /**
 469  * Cancel the given listen operation.
 470  *
 471  * @param lh handle for the listen operation
 472  */
 473 void
 474 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh)
 475 {
 476   GNUNET_CLIENT_disconnect (lh->client);
 477   GNUNET_MQ_destroy (lh->mq);
 478   GNUNET_free (lh);
 479 }
 480
 481
 482 /**
 483  * Accept a request we got via GNUNET_SET_listen.  Must be called during
 484  * GNUNET_SET_listen, as the 'struct GNUNET_SET_Request' becomes invalid
 485  * afterwards.
 486  * Call GNUNET_SET_conclude to provide the local set to use for the operation,
 487  * and to begin the exchange with the remote peer.
 488  *
 489  * @param request request to accept
 490  * @param result_mode specified how results will be returned,
 491  *        see 'GNUNET_SET_ResultMode'.
 492  * @param result_cb callback for the results
 493  * @param result_cls closure for result_cb
 494  * @return a handle to cancel the operation
 495  */
 496 struct GNUNET_SET_OperationHandle *
 497 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
 498                    enum GNUNET_SET_ResultMode result_mode,
 499                    GNUNET_SET_ResultIterator result_cb,
 500                    void *result_cls)
 501 {
 502   struct GNUNET_MQ_Envelope *mqm;
 503   struct GNUNET_SET_OperationHandle *oh;
 504   struct GNUNET_SET_AcceptRejectMessage *msg;
 505
 506   GNUNET_assert (NULL != request);
 507   GNUNET_assert (GNUNET_NO == request->accepted);
 508   request->accepted = GNUNET_YES;
 509
 510   oh = GNUNET_new (struct GNUNET_SET_OperationHandle);
 511   oh->result_cb = result_cb;
 512   oh->result_cls = result_cls;
 513
 514   mqm = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_SET_ACCEPT);
 515   msg->accept_reject_id = htonl (request->accept_id);
 516
 517   oh->conclude_mqm = mqm;
 518   oh->request_id_addr = &msg->request_id;
 519
 520   return oh;
 521 }
 522
 523
 524 /**
 525  * Cancel the given set operation.
 526  * We need to send an explicit cancel message, as
 527  * all operations communicate with the set's client
 528  * handle.
 529  *
 530  * @param oh set operation to cancel
 531  */
 532 void
 533 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh)
 534 {
 535   struct GNUNET_MQ_Envelope *mqm;
 536   struct GNUNET_SET_OperationHandle *h_assoc;
 537
 538   GNUNET_assert (NULL != oh->set);
 539
 540   GNUNET_CONTAINER_DLL_remove (oh->set->ops_head, oh->set->ops_tail, oh);
 541   h_assoc = GNUNET_MQ_assoc_remove (oh->set->mq, oh->request_id);
 542   GNUNET_assert (h_assoc == oh);
 543   mqm = GNUNET_MQ_msg_header (GNUNET_MESSAGE_TYPE_SET_CANCEL);
 544   GNUNET_MQ_send (oh->set->mq, mqm);
 545
 546   if (NULL != oh->conclude_mqm)
 547     GNUNET_MQ_discard (oh->conclude_mqm);
 548
 549   if (GNUNET_YES == oh->set->destroy_requested)
 550     GNUNET_SET_destroy (oh->set);
 551
 552   GNUNET_free (oh);
 553 }
 554
 555
 556 /**
 557  * Commit a set to be used with a set operation.
 558  * This function is called once we have fully constructed
 559  * the set that we want to use for the operation.  At this
 560  * time, the P2P protocol can then begin to exchange the
 561  * set information and call the result callback with the
 562  * result information.
 563  *
 564  * @param oh handle to the set operation
 565  * @param set the set to use for the operation
 566  */
 567 void
 568 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
 569                    struct GNUNET_SET_Handle *set)
 570 {
 571   GNUNET_assert (NULL == oh->set);
 572   GNUNET_assert (NULL != oh->conclude_mqm);
 573   oh->set = set;
 574   GNUNET_CONTAINER_DLL_insert (set->ops_head, set->ops_tail, oh);
 575   oh->request_id = GNUNET_MQ_assoc_add (set->mq, oh);
 576   *oh->request_id_addr = htonl (oh->request_id);
 577   GNUNET_MQ_send (set->mq, oh->conclude_mqm);
 578   oh->conclude_mqm = NULL;
 579   oh->request_id_addr = NULL;
 580 }
 581