src/psyc/psyc_api.c

   1 /*
   2  * This file is part of GNUnet
   3  * (C) 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 psyc/psyc_api.c
  23  * @brief PSYC service; high-level access to the PSYC protocol
  24  *        note that clients of this API are NOT expected to
  25  *        understand the PSYC message format, only the semantics!
  26  *        Parsing (and serializing) the PSYC stream format is done
  27  *        within the implementation of the libgnunetpsyc library,
  28  *        and this API deliberately exposes as little as possible
  29  *        of the actual data stream format to the application!
  30  * @author Gabor X Toth
  31  */
  32
  33 #include "platform.h"
  34 #include "gnunet_util_lib.h"
  35 #include "gnunet_env_lib.h"
  36 #include "gnunet_psyc_service.h"
  37 #include "psyc.h"
  38
  39 #define LOG(kind,...) GNUNET_log_from (kind, "psyc-api",__VA_ARGS__)
  40
  41
  42 struct OperationHandle
  43 {
  44   struct OperationHandle *prev;
  45   struct OperationHandle *next;
  46   const struct GNUNET_MessageHeader *msg;
  47 };
  48
  49 /**
  50  * Handle to access PSYC channel operations for both the master and slaves.
  51  */
  52 struct GNUNET_PSYC_Channel
  53 {
  54   /**
  55    * Configuration to use.
  56    */
  57   const struct GNUNET_CONFIGURATION_Handle *cfg;
  58
  59   /**
  60    * Socket (if available).
  61    */
  62   struct GNUNET_CLIENT_Connection *client;
  63
  64   /**
  65    * Currently pending transmission request, or NULL for none.
  66    */
  67   struct GNUNET_CLIENT_TransmitHandle *th;
  68
  69   /**
  70    * Head of operations to transmit.
  71    */
  72   struct OperationHandle *transmit_head;
  73
  74   /**
  75    * Tail of operations to transmit.
  76    */
  77   struct OperationHandle *transmit_tail;
  78
  79   /**
  80    * Message to send on reconnect.
  81    */
  82   struct GNUNET_MessageHeader *reconnect_msg;
  83
  84   /**
  85    * Task doing exponential back-off trying to reconnect.
  86    */
  87   GNUNET_SCHEDULER_TaskIdentifier reconnect_task;
  88
  89   /**
  90    * Time for next connect retry.
  91    */
  92   struct GNUNET_TIME_Relative reconnect_delay;
  93
  94   GNUNET_PSYC_Method method_cb;
  95
  96   GNUNET_PSYC_JoinCallback join_cb;
  97
  98   void *cb_cls;
  99
 100   /**
 101    * Are we polling for incoming messages right now?
 102    */
 103   int in_receive;
 104
 105   /**
 106    * Are we currently transmitting a message?
 107    */
 108   int in_transmit;
 109 };
 110
 111
 112 /**
 113  * Handle for the master of a PSYC channel.
 114  */
 115 struct GNUNET_PSYC_Master
 116 {
 117   struct GNUNET_PSYC_Channel ch;
 118
 119   GNUNET_PSYC_MasterStartCallback start_cb;
 120
 121   uint64_t max_message_id;
 122 };
 123
 124
 125 /**
 126  * Handle for a PSYC channel slave.
 127  */
 128 struct GNUNET_PSYC_Slave
 129 {
 130   struct GNUNET_PSYC_Channel ch;
 131 };
 132
 133
 134 /**
 135  * Handle that identifies a join request.
 136  *
 137  * Used to match calls to #GNUNET_PSYC_JoinCallback to the
 138  * corresponding calls to GNUNET_PSYC_join_decision().
 139  */
 140 struct GNUNET_PSYC_JoinHandle
 141 {
 142
 143 };
 144
 145
 146 /**
 147  * Handle for a pending PSYC transmission operation.
 148  */
 149 struct GNUNET_PSYC_MasterTransmitHandle
 150 {
 151   struct GNUNET_PSYC_Master *master;
 152   const struct GNUNET_ENV_Environment *env;
 153   GNUNET_PSYC_MasterTransmitNotify notify;
 154   void *notify_cls;
 155   enum GNUNET_PSYC_MasterTransmitFlags flags;
 156 };
 157
 158
 159 /**
 160  * Handle for a pending PSYC transmission operation.
 161  */
 162 struct GNUNET_PSYC_SlaveTransmitHandle
 163 {
 164
 165 };
 166
 167
 168 /**
 169  * Handle to a story telling operation.
 170  */
 171 struct GNUNET_PSYC_Story
 172 {
 173
 174 };
 175
 176
 177 /**
 178  * Handle for a state query operation.
 179  */
 180 struct GNUNET_PSYC_StateQuery
 181 {
 182
 183 };
 184
 185
 186 /**
 187  * Try again to connect to the PSYCstore service.
 188  *
 189  * @param cls handle to the PSYCstore service.
 190  * @param tc scheduler context
 191  */
 192 static void
 193 reconnect (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 194
 195
 196 /**
 197  * Reschedule a connect attempt to the service.
 198  *
 199  * @param h transport service to reconnect
 200  */
 201 static void
 202 reschedule_connect (struct GNUNET_PSYC_Channel *c)
 203 {
 204   GNUNET_assert (c->reconnect_task == GNUNET_SCHEDULER_NO_TASK);
 205
 206   if (NULL != c->th)
 207   {
 208     GNUNET_CLIENT_notify_transmit_ready_cancel (c->th);
 209     c->th = NULL;
 210   }
 211   if (NULL != c->client)
 212   {
 213     GNUNET_CLIENT_disconnect (c->client);
 214     c->client = NULL;
 215   }
 216   c->in_receive = GNUNET_NO;
 217   LOG (GNUNET_ERROR_TYPE_DEBUG,
 218        "Scheduling task to reconnect to PSYCstore service in %s.\n",
 219        GNUNET_STRINGS_relative_time_to_string (c->reconnect_delay, GNUNET_YES));
 220   c->reconnect_task =
 221       GNUNET_SCHEDULER_add_delayed (c->reconnect_delay, &reconnect, c);
 222   c->reconnect_delay = GNUNET_TIME_STD_BACKOFF (c->reconnect_delay);
 223 }
 224
 225
 226 /**
 227  * Schedule transmission of the next message from our queue.
 228  *
 229  * @param h PSYCstore handle
 230  */
 231 static void
 232 transmit_next (struct GNUNET_PSYC_Channel *c);
 233
 234
 235 /**
 236  * Type of a function to call when we receive a message
 237  * from the service.
 238  *
 239  * @param cls closure
 240  * @param msg message received, NULL on timeout or fatal error
 241  */
 242 static void
 243 message_handler (void *cls, const struct GNUNET_MessageHeader *msg)
 244 {
 245   struct GNUNET_PSYC_Channel *ch = cls;
 246   struct GNUNET_PSYC_Master *mst = cls;
 247   struct GNUNET_PSYC_Slave *slv = cls;
 248
 249   if (NULL == msg)
 250   {
 251     reschedule_connect (ch);
 252     return;
 253   }
 254   uint16_t size_eq = 0;
 255   uint16_t size_min = 0;
 256   const uint16_t size = ntohs (msg->size);
 257   const uint16_t type = ntohs (msg->type);
 258
 259   LOG (GNUNET_ERROR_TYPE_DEBUG,
 260        "Received message of type %d from PSYC service\n", type);
 261
 262   switch (type)
 263   {
 264   case GNUNET_MESSAGE_TYPE_PSYC_MASTER_START_ACK:
 265   case GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK:
 266     size_eq = sizeof (struct CountersResult);
 267     break;
 268   }
 269
 270   if (! ((0 < size_eq && size == size_eq)
 271          || (0 < size_min && size >= size_min)))
 272   {
 273     GNUNET_break (0);
 274     reschedule_connect (ch);
 275     return;
 276   }
 277
 278   struct CountersResult *cres;
 279
 280   switch (type)
 281   {
 282   case GNUNET_MESSAGE_TYPE_PSYC_MASTER_START_ACK:
 283     cres = (struct CountersResult *) msg;
 284     mst->max_message_id = GNUNET_ntohll (cres->max_message_id);
 285     if (NULL != mst->start_cb)
 286       mst->start_cb (ch->cb_cls, mst->max_message_id);
 287     break;
 288
 289   case GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK:
 290     cres = (struct CountersResult *) msg;
 291 #if TODO
 292     slv->max_message_id = GNUNET_ntohll (cres->max_message_id);
 293     if (NULL != slv->join_ack_cb)
 294       mst->join_ack_cb (ch->cb_cls, mst->max_message_id);
 295 #endif
 296     break;
 297   }
 298
 299   GNUNET_CLIENT_receive (ch->client, &message_handler, ch,
 300                          GNUNET_TIME_UNIT_FOREVER_REL);
 301 }
 302
 303
 304 /**
 305  * Transmit next message to service.
 306  *
 307  * @param cls The 'struct GNUNET_PSYCSTORE_Handle'.
 308  * @param size Number of bytes available in buf.
 309  * @param buf Where to copy the message.
 310  * @return Number of bytes copied to buf.
 311  */
 312 static size_t
 313 send_next_message (void *cls, size_t size, void *buf)
 314 {
 315   struct GNUNET_PSYC_Channel *ch = cls;
 316   struct OperationHandle *op = ch->transmit_head;
 317   size_t ret;
 318
 319   ch->th = NULL;
 320   if (NULL == op->msg)
 321     return 0;
 322   ret = ntohs (op->msg->size);
 323   if (ret > size)
 324   {
 325     reschedule_connect (ch);
 326     return 0;
 327   }
 328   LOG (GNUNET_ERROR_TYPE_DEBUG,
 329        "Sending message of type %d to PSYCstore service\n",
 330        ntohs (op->msg->type));
 331   memcpy (buf, op->msg, ret);
 332
 333   GNUNET_CONTAINER_DLL_remove (ch->transmit_head, ch->transmit_tail, op);
 334   GNUNET_free (op);
 335
 336   if (NULL != ch->transmit_head)
 337     transmit_next (ch);
 338
 339   if (GNUNET_NO == ch->in_receive)
 340   {
 341     ch->in_receive = GNUNET_YES;
 342     GNUNET_CLIENT_receive (ch->client, &message_handler, ch,
 343                            GNUNET_TIME_UNIT_FOREVER_REL);
 344   }
 345   return ret;
 346 }
 347
 348
 349 /**
 350  * Schedule transmission of the next message from our queue.
 351  *
 352  * @param h PSYCstore handle.
 353  */
 354 static void
 355 transmit_next (struct GNUNET_PSYC_Channel *ch)
 356 {
 357   if (NULL != ch->th || NULL == ch->client)
 358     return;
 359
 360   struct OperationHandle *op = ch->transmit_head;
 361   if (NULL == op)
 362     return;
 363
 364   ch->th = GNUNET_CLIENT_notify_transmit_ready (ch->client,
 365                                                 ntohs (op->msg->size),
 366                                                 GNUNET_TIME_UNIT_FOREVER_REL,
 367                                                 GNUNET_NO,
 368                                                 &send_next_message,
 369                                                 ch);
 370 }
 371
 372
 373 /**
 374  * Try again to connect to the PSYC service.
 375  *
 376  * @param cls Channel handle.
 377  * @param tc Scheduler context.
 378  */
 379 static void
 380 reconnect (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 381 {
 382   struct GNUNET_PSYC_Channel *ch = cls;
 383
 384   ch->reconnect_task = GNUNET_SCHEDULER_NO_TASK;
 385   LOG (GNUNET_ERROR_TYPE_DEBUG,
 386        "Connecting to PSYC service.\n");
 387   GNUNET_assert (NULL == ch->client);
 388   ch->client = GNUNET_CLIENT_connect ("psyc", ch->cfg);
 389   GNUNET_assert (NULL != ch->client);
 390
 391   if (NULL == ch->transmit_head ||
 392       ch->transmit_head->msg->type != ch->reconnect_msg->type)
 393   {
 394     struct OperationHandle *op
 395       = GNUNET_malloc (sizeof (struct OperationHandle)
 396                        + ntohs (ch->reconnect_msg->size));
 397     memcpy (&op[1], ch->reconnect_msg, ntohs (ch->reconnect_msg->size));
 398     op->msg = (struct GNUNET_MessageHeader *) &op[1];
 399     GNUNET_CONTAINER_DLL_insert (ch->transmit_head, ch->transmit_tail, op);
 400   }
 401
 402   transmit_next (ch);
 403 }
 404
 405
 406 /**
 407  * Disconnect from the PSYC service.
 408  *
 409  * @param cls Channel handle.
 410  * @param tc Scheduler context.
 411  */
 412 static void
 413 disconnect (void *c)
 414 {
 415   struct GNUNET_PSYC_Channel *ch = c;
 416   GNUNET_assert (NULL != ch);
 417   GNUNET_assert (ch->transmit_head == ch->transmit_tail);
 418   if (ch->reconnect_task != GNUNET_SCHEDULER_NO_TASK)
 419   {
 420     GNUNET_SCHEDULER_cancel (ch->reconnect_task);
 421     ch->reconnect_task = GNUNET_SCHEDULER_NO_TASK;
 422   }
 423   if (NULL != ch->th)
 424   {
 425     GNUNET_CLIENT_notify_transmit_ready_cancel (ch->th);
 426     ch->th = NULL;
 427   }
 428   if (NULL != ch->client)
 429   {
 430     GNUNET_CLIENT_disconnect (ch->client);
 431     ch->client = NULL;
 432   }
 433   if (NULL != ch->reconnect_msg)
 434     ch->reconnect_msg = NULL;
 435 }
 436
 437
 438 /**
 439  * Start a PSYC master channel.
 440  *
 441  * Will start a multicast group identified by the given ECC key.  Messages
 442  * received from group members will be given to the respective handler methods.
 443  * If a new member wants to join a group, the "join" method handler will be
 444  * invoked; the join handler must then generate a "join" message to approve the
 445  * joining of the new member.  The channel can also change group membership
 446  * without explicit requests.  Note that PSYC doesn't itself "understand" join
 447  * or part messages, the respective methods must call other PSYC functions to
 448  * inform PSYC about the meaning of the respective events.
 449  *
 450  * @param cfg Configuration to use (to connect to PSYC service).
 451  * @param channel_key ECC key that will be used to sign messages for this
 452  *        PSYC session. The public key is used to identify the PSYC channel.
 453  *        Note that end-users will usually not use the private key directly, but
 454  *        rather look it up in GADS for places managed by other users, or select
 455  *        a file with the private key(s) when setting up their own channels
 456  *        FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper
 457  *        one in the future.
 458  * @param policy Channel policy specifying join and history restrictions.
 459  *        Used to automate join decisions.
 460  * @param method Function to invoke on messages received from slaves.
 461  * @param join_cb Function to invoke when a peer wants to join.
 462  * @param cls Closure for @a method and @a join_cb.
 463  * @return Handle for the channel master, NULL on error.
 464  */
 465 struct GNUNET_PSYC_Master *
 466 GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 467                           const struct GNUNET_CRYPTO_EccPrivateKey *channel_key,
 468                           enum GNUNET_PSYC_Policy policy,
 469                           GNUNET_PSYC_Method method,
 470                           GNUNET_PSYC_JoinCallback join_cb,
 471                           GNUNET_PSYC_MasterStartCallback master_started_cb,
 472                           void *cls)
 473 {
 474   struct GNUNET_PSYC_Master *mst = GNUNET_malloc (sizeof (*mst));
 475   struct GNUNET_PSYC_Channel *ch = &mst->ch;
 476   struct MasterStartRequest *req = GNUNET_malloc (sizeof (*req));
 477
 478   req->header.size = htons (sizeof (*req) + sizeof (*channel_key));
 479   req->header.type = htons (GNUNET_MESSAGE_TYPE_PSYC_MASTER_START);
 480   req->channel_key = *channel_key;
 481   req->policy = policy;
 482
 483   ch->cfg = cfg;
 484   ch->reconnect_msg = (struct GNUNET_MessageHeader *) req;
 485   ch->reconnect_delay = GNUNET_TIME_UNIT_ZERO;
 486   ch->reconnect_task = GNUNET_SCHEDULER_add_now (&reconnect, mst);
 487
 488   ch->method_cb = method;
 489   ch->join_cb = join_cb;
 490   ch->cb_cls = cls;
 491   mst->start_cb = master_started_cb;
 492
 493   return mst;
 494 }
 495
 496
 497 /**
 498  * Stop a PSYC master channel.
 499  *
 500  * @param master PSYC channel master to stop.
 501  */
 502 void
 503 GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *mst)
 504 {
 505   disconnect (mst);
 506   GNUNET_free (mst);
 507 }
 508
 509
 510 /**
 511  * Function to call with the decision made for a join request.
 512  *
 513  * Must be called once and only once in response to an invocation of the
 514  * #GNUNET_PSYC_JoinCallback.
 515  *
 516  * @param jh Join request handle.
 517  * @param is_admitted #GNUNET_YES if joining is approved,
 518  *        #GNUNET_NO if it is disapproved.
 519  * @param relay_count Number of relays given.
 520  * @param relays Array of suggested peers that might be useful relays to use
 521  *        when joining the multicast group (essentially a list of peers that
 522  *        are already part of the multicast group and might thus be willing
 523  *        to help with routing).  If empty, only this local peer (which must
 524  *        be the multicast origin) is a good candidate for building the
 525  *        multicast tree.  Note that it is unnecessary to specify our own
 526  *        peer identity in this array.
 527  * @param method_name Method name for the message transmitted with the response.
 528  * @param env Environment containing transient variables for the message, or NULL.
 529  * @param data Data of the message.
 530  * @param data_size Size of @a data.
 531  */
 532 void
 533 GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh,
 534                            int is_admitted,
 535                            unsigned int relay_count,
 536                            const struct GNUNET_PeerIdentity *relays,
 537                            const char *method_name,
 538                            const struct GNUNET_ENV_Environment *env,
 539                            const void *data,
 540                            size_t data_size)
 541 {
 542
 543 }
 544
 545
 546 /* FIXME: split up value into <64K chunks and transmit the continuations in
 547  *        MOD_CONT msgs */
 548 int
 549 send_modifier (void *cls, struct GNUNET_ENV_Modifier *mod)
 550 {
 551   struct GNUNET_PSYC_Channel *ch = cls;
 552   size_t name_size = strlen (mod->name) + 1;
 553   struct GNUNET_PSYC_MessageModifier *pmod;
 554   struct OperationHandle *op = GNUNET_malloc (sizeof (*op) + sizeof (*pmod)
 555                                               + name_size + mod->value_size);
 556   pmod = (struct GNUNET_PSYC_MessageModifier *) &op[1];
 557   op->msg = (struct GNUNET_MessageHeader *) pmod;
 558
 559   pmod->header.type = GNUNET_MESSAGE_TYPE_PSYC_TRANSMIT_MODIFIER;
 560   pmod->header.size = htons (sizeof (*pmod) + name_size + mod->value_size);
 561   pmod->name_size = htons (name_size);
 562   memcpy (&pmod[1], mod->name, name_size);
 563   memcpy ((void *) &pmod[1] + name_size, mod->value, mod->value_size);
 564
 565   GNUNET_CONTAINER_DLL_insert (ch->transmit_head, ch->transmit_tail, op);
 566   return GNUNET_YES;
 567 }
 568
 569
 570 /**
 571  * Send a message to call a method to all members in the PSYC channel.
 572  *
 573  * @param mst Handle to the PSYC channel.
 574  * @param method_name Which method should be invoked.
 575  * @param env Environment containing state operations and transient variables
 576  *            for the message, or NULL.
 577  * @param notify Function to call to obtain the arguments.
 578  * @param notify_cls Closure for @a notify.
 579  * @param flags Flags for the message being transmitted.
 580  * @return Transmission handle, NULL on error (i.e. more than one request
 581  *         queued).
 582  */
 583 struct GNUNET_PSYC_MasterTransmitHandle *
 584 GNUNET_PSYC_master_transmit (struct GNUNET_PSYC_Master *mst,
 585                              const char *method_name,
 586                              const struct GNUNET_ENV_Environment *env,
 587                              GNUNET_PSYC_MasterTransmitNotify notify,
 588                              void *notify_cls,
 589                              enum GNUNET_PSYC_MasterTransmitFlags flags)
 590 {
 591   GNUNET_assert (NULL != mst);
 592   struct GNUNET_PSYC_Channel *ch = &mst->ch;
 593   if (GNUNET_NO != ch->in_transmit)
 594     return NULL;
 595   ch->in_transmit = GNUNET_YES;
 596
 597   struct GNUNET_PSYC_MessageMethod *pmeth;
 598   struct OperationHandle *op = GNUNET_malloc (sizeof (*op) + sizeof (*pmeth));
 599   pmeth = (struct GNUNET_PSYC_MessageMethod *) &op[1];
 600   op->msg = (struct GNUNET_MessageHeader *) pmeth;
 601
 602   pmeth->header.type = GNUNET_MESSAGE_TYPE_PSYC_TRANSMIT_METHOD;
 603   size_t size = strlen (method_name) + 1;
 604   pmeth->header.size = htons (sizeof (*pmeth) + size);
 605   pmeth->flags = htonl (flags);
 606   pmeth->mod_count
 607     = GNUNET_ntohll (GNUNET_ENV_environment_get_mod_count (env));
 608   memcpy (&pmeth[1], method_name, size);
 609
 610   GNUNET_CONTAINER_DLL_insert (ch->transmit_head, ch->transmit_tail, op);
 611
 612   GNUNET_ENV_environment_iterate (env, send_modifier, mst);
 613
 614   struct GNUNET_PSYC_MasterTransmitHandle *th = GNUNET_malloc (sizeof (*th));
 615   th->master = mst;
 616   th->env = env;
 617   th->notify = notify;
 618   th->notify_cls = notify_cls;
 619   return th;
 620 }
 621
 622
 623 /**
 624  * Abort transmission request to the channel.
 625  *
 626  * @param th Handle of the request that is being aborted.
 627  */
 628 void
 629 GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th)
 630 {
 631   struct GNUNET_PSYC_Master *mst = th->master;
 632   struct GNUNET_PSYC_Channel *ch = &mst->ch;
 633   if (GNUNET_NO != ch->in_transmit)
 634     return;
 635
 636
 637 }
 638
 639
 640 /**
 641  * Join a PSYC channel.
 642  *
 643  * The entity joining is always the local peer.  The user must immediately use
 644  * the GNUNET_PSYC_slave_transmit() functions to transmit a @e join_msg to the
 645  * channel; if the join request succeeds, the channel state (and @e recent
 646  * method calls) will be replayed to the joining member.  There is no explicit
 647  * notification on failure (as the channel may simply take days to approve,
 648  * and disapproval is simply being ignored).
 649  *
 650  * @param cfg Configuration to use.
 651  * @param channel_key ECC public key that identifies the channel we wish to join.
 652  * @param slave_key ECC private-public key pair that identifies the slave, and
 653  *        used by multicast to sign the join request and subsequent unicast
 654  *        requests sent to the master.
 655  * @param origin Peer identity of the origin.
 656  * @param relay_count Number of peers in the @a relays array.
 657  * @param relays Peer identities of members of the multicast group, which serve
 658  *        as relays and used to join the group at.
 659  * @param method Function to invoke on messages received from the channel,
 660  *        typically at least contains functions for @e join and @e part.
 661  * @param join_cb Function to invoke when a peer wants to join.
 662  * @param cls Closure for @a method_cb and @a join_cb.
 663  * @param method_name Method name for the join request.
 664  * @param env Environment containing transient variables for the request, or NULL.
 665  * @param data Payload for the join message.
 666  * @param data_size Number of bytes in @a data.
 667  * @return Handle for the slave, NULL on error.
 668  */
 669 struct GNUNET_PSYC_Slave *
 670 GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
 671                         const struct GNUNET_CRYPTO_EccPublicSignKey *channel_key,
 672                         const struct GNUNET_CRYPTO_EccPrivateKey *slave_key,
 673                         const struct GNUNET_PeerIdentity *origin,
 674                         size_t relay_count,
 675                         const struct GNUNET_PeerIdentity *relays,
 676                         GNUNET_PSYC_Method method,
 677                         GNUNET_PSYC_JoinCallback join_cb,
 678                         GNUNET_PSYC_SlaveJoinCallback slave_joined_cb,
 679                         void *cls,
 680                         const char *method_name,
 681                         const struct GNUNET_ENV_Environment *env,
 682                         const void *data,
 683                         size_t data_size)
 684 {
 685   struct GNUNET_PSYC_Slave *slv = GNUNET_malloc (sizeof (*slv));
 686   struct GNUNET_PSYC_Channel *ch = &slv->ch;
 687   struct SlaveJoinRequest *req = GNUNET_malloc (sizeof (*req));
 688
 689   req->header.size = htons (sizeof (*req)
 690                             + sizeof (*channel_key) + sizeof (*slave_key)
 691                             + relay_count * sizeof (*relays));
 692   req->header.type = htons (GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN);
 693   req->channel_key = *channel_key;
 694   req->slave_key = *slave_key;
 695   req->relay_count = relay_count;
 696   memcpy (&req[1], relays, relay_count * sizeof (*relays));
 697
 698   ch->cfg = cfg;
 699   ch->reconnect_msg = (struct GNUNET_MessageHeader *) req;
 700   ch->reconnect_delay = GNUNET_TIME_UNIT_ZERO;
 701   ch->reconnect_task = GNUNET_SCHEDULER_add_now (&reconnect, slv);
 702
 703   return slv;
 704 }
 705
 706
 707 /**
 708  * Part a PSYC channel.
 709  *
 710  * Will terminate the connection to the PSYC service.  Polite clients should
 711  * first explicitly send a @e part request (via GNUNET_PSYC_slave_transmit()).
 712  *
 713  * @param slv Slave handle.
 714  */
 715 void
 716 GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slv)
 717 {
 718   disconnect (slv);
 719   GNUNET_free (slv);
 720 }
 721
 722
 723 /**
 724  * Request a message to be sent to the channel master.
 725  *
 726  * @param slave Slave handle.
 727  * @param method_name Which (PSYC) method should be invoked (on host).
 728  * @param env Environment containing transient variables for the message, or
 729  *            NULL.
 730  * @param notify Function to call when we are allowed to transmit (to get data).
 731  * @param notify_cls Closure for @a notify.
 732  * @param flags Flags for the message being transmitted.
 733  * @return Transmission handle, NULL on error (i.e. more than one request
 734  *         queued).
 735  */
 736 struct GNUNET_PSYC_SlaveTransmitHandle *
 737 GNUNET_PSYC_slave_transmit (struct GNUNET_PSYC_Slave *slave,
 738                             const char *method_name,
 739                             const struct GNUNET_ENV_Environment *env,
 740                             GNUNET_PSYC_SlaveTransmitNotify notify,
 741                             void *notify_cls,
 742                             enum GNUNET_PSYC_SlaveTransmitFlags flags)
 743 {
 744   return NULL;
 745 }
 746
 747
 748 /**
 749  * Abort transmission request to master.
 750  *
 751  * @param th Handle of the request that is being aborted.
 752  */
 753 void
 754 GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th)
 755 {
 756
 757 }
 758
 759
 760 /**
 761  * Convert a channel @a master to a @e channel handle to access the @e channel
 762  * APIs.
 763  *
 764  * @param master Channel master handle.
 765  * @return Channel handle, valid for as long as @a master is valid.
 766  */
 767 struct GNUNET_PSYC_Channel *
 768 GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master)
 769 {
 770   return (struct GNUNET_PSYC_Channel *) master;
 771 }
 772
 773
 774 /**
 775  * Convert @a slave to a @e channel handle to access the @e channel APIs.
 776  *
 777  * @param slave Slave handle.
 778  * @return Channel handle, valid for as long as @a slave is valid.
 779  */
 780 struct GNUNET_PSYC_Channel *
 781 GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave)
 782 {
 783   return (struct GNUNET_PSYC_Channel *) slave;
 784 }
 785
 786
 787 /**
 788  * Add a slave to the channel's membership list.
 789  *
 790  * Note that this will NOT generate any PSYC traffic, it will merely update the
 791  * local database to modify how we react to <em>membership test</em> queries.
 792  * The channel master still needs to explicitly transmit a @e join message to
 793  * notify other channel members and they then also must still call this function
 794  * in their respective methods handling the @e join message.  This way, how @e
 795  * join and @e part operations are exactly implemented is still up to the
 796  * application; for example, there might be a @e part_all method to kick out
 797  * everyone.
 798  *
 799  * Note that channel slaves are explicitly trusted to execute such methods
 800  * correctly; not doing so correctly will result in either denying other slaves
 801  * access or offering access to channel data to non-members.
 802  *
 803  * @param ch Channel handle.
 804  * @param slave_key Identity of channel slave to add.
 805  * @param announced_at ID of the message that announced the membership change.
 806  * @param effective_since Addition of slave is in effect since this message ID.
 807  */
 808 void
 809 GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *ch,
 810                                const struct GNUNET_CRYPTO_EccPublicSignKey
 811                                *slave_key,
 812                                uint64_t announced_at,
 813                                uint64_t effective_since)
 814 {
 815   struct ChannelSlaveAdd *slvadd;
 816   struct OperationHandle *op = GNUNET_malloc (sizeof (*op) + sizeof (*slvadd));
 817   slvadd = (struct ChannelSlaveAdd *) &op[1];
 818   op->msg = (struct GNUNET_MessageHeader *) slvadd;
 819
 820   slvadd->header.type = GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_ADD;
 821   slvadd->header.size = htons (sizeof (*slvadd));
 822   slvadd->announced_at = GNUNET_htonll (announced_at);
 823   slvadd->effective_since = GNUNET_htonll (effective_since);
 824
 825   GNUNET_CONTAINER_DLL_insert (ch->transmit_head, ch->transmit_tail, op);
 826   transmit_next (ch);
 827 }
 828
 829
 830 /**
 831  * Remove a slave from the channel's membership list.
 832  *
 833  * Note that this will NOT generate any PSYC traffic, it will merely update the
 834  * local database to modify how we react to <em>membership test</em> queries.
 835  * The channel master still needs to explicitly transmit a @e part message to
 836  * notify other channel members and they then also must still call this function
 837  * in their respective methods handling the @e part message.  This way, how
 838  * @e join and @e part operations are exactly implemented is still up to the
 839  * application; for example, there might be a @e part_all message to kick out
 840  * everyone.
 841  *
 842  * Note that channel members are explicitly trusted to perform these
 843  * operations correctly; not doing so correctly will result in either
 844  * denying members access or offering access to channel data to
 845  * non-members.
 846  *
 847  * @param ch Channel handle.
 848  * @param slave_key Identity of channel slave to remove.
 849  * @param announced_at ID of the message that announced the membership change.
 850  */
 851 void
 852 GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *ch,
 853                                   const struct GNUNET_CRYPTO_EccPublicSignKey
 854                                   *slave_key,
 855                                   uint64_t announced_at)
 856 {
 857   struct ChannelSlaveRemove *slvrm;
 858   struct OperationHandle *op = GNUNET_malloc (sizeof (*op) + sizeof (*slvrm));
 859   slvrm = (struct ChannelSlaveRemove *) &op[1];
 860   op->msg = (struct GNUNET_MessageHeader *) slvrm;
 861
 862   slvrm->header.type = GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_RM;
 863   slvrm->header.size = htons (sizeof (*slvrm));
 864   slvrm->announced_at = GNUNET_htonll (announced_at);
 865
 866   GNUNET_CONTAINER_DLL_insert (ch->transmit_head, ch->transmit_tail, op);
 867   transmit_next (ch);
 868 }
 869
 870
 871 /**
 872  * Request to be told the message history of the channel.
 873  *
 874  * Historic messages (but NOT the state at the time) will be replayed (given to
 875  * the normal method handlers) if available and if access is permitted.
 876  *
 877  * To get the latest message, use 0 for both the start and end message ID.
 878  *
 879  * @param ch Which channel should be replayed?
 880  * @param start_message_id Earliest interesting point in history.
 881  * @param end_message_id Last (exclusive) interesting point in history.
 882  * @param method Function to invoke on messages received from the story.
 883  * @param finish_cb Function to call when the requested story has been fully
 884  *        told (counting message IDs might not suffice, as some messages
 885  *        might be secret and thus the listener would not know the story is
 886  *        finished without being told explicitly)
 887 {
 888   return NULL;
 889 } once this function
 890  *        has been called, the client must not call
 891  *        GNUNET_PSYC_channel_story_tell_cancel() anymore.
 892  * @param cls Closure for the callbacks.
 893  * @return Handle to cancel story telling operation.
 894  */
 895 struct GNUNET_PSYC_Story *
 896 GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *ch,
 897                                 uint64_t start_message_id,
 898                                 uint64_t end_message_id,
 899                                 GNUNET_PSYC_Method method,
 900                                 GNUNET_PSYC_FinishCallback *finish_cb,
 901                                 void *cls)
 902 {
 903   return NULL;
 904 }
 905
 906
 907 /**
 908  * Abort story telling.
 909  *
 910  * This function must not be called from within method handlers (as given to
 911  * GNUNET_PSYC_slave_join()) of the slave.
 912  *
 913  * @param story Story telling operation to stop.
 914  */
 915 void
 916 GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story)
 917 {
 918
 919 }
 920
 921
 922 /**
 923  * Retrieve the best matching channel state variable.
 924  *
 925  * If the requested variable name is not present in the state, the nearest
 926  * less-specific name is matched; for example, requesting "_a_b" will match "_a"
 927  * if "_a_b" does not exist.
 928  *
 929  * @param channel Channel handle.
 930  * @param full_name Full name of the requested variable, the actual variable
 931  *        returned might have a shorter name..
 932  * @param cb Function called once when a matching state variable is found.
 933  *        Not called if there's no matching state variable.
 934  * @param cb_cls Closure for the callbacks.
 935  * @return Handle that can be used to cancel the query operation.
 936  */
 937 struct GNUNET_PSYC_StateQuery *
 938 GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel,
 939                                const char *full_name,
 940                                GNUNET_PSYC_StateCallback cb,
 941                                void *cb_cls)
 942 {
 943   return NULL;
 944 }
 945
 946
 947 /**
 948  * Return all channel state variables whose name matches a given prefix.
 949  *
 950  * A name matches if it starts with the given @a name_prefix, thus requesting
 951  * the empty prefix ("") will match all values; requesting "_a_b" will also
 952  * return values stored under "_a_b_c".
 953  *
 954  * The @a state_cb is invoked on all matching state variables asynchronously, as
 955  * the state is stored in and retrieved from the PSYCstore,
 956  *
 957  * @param channel Channel handle.
 958  * @param name_prefix Prefix of the state variable name to match.
 959  * @param cb Function to call with the matching state variables.
 960  * @param cb_cls Closure for the callbacks.
 961  * @return Handle that can be used to cancel the query operation.
 962  */
 963 struct GNUNET_PSYC_StateQuery *
 964 GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel,
 965                                       const char *name_prefix,
 966                                       GNUNET_PSYC_StateCallback cb,
 967                                       void *cb_cls)
 968 {
 969   return NULL;
 970 }
 971
 972
 973 /**
 974  * Cancel a state query operation.
 975  *
 976  * @param query Handle for the operation to cancel.
 977  */
 978 void
 979 GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateQuery *query)
 980 {
 981
 982 }
 983
 984
 985 /* end of psyc_api.c */