src/peerinfo/peerinfo_api.c

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001, 2002, 2004, 2005, 2007, 2009, 2010, 2012 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 peerinfo/peerinfo_api.c
  23  * @brief API to access peerinfo service
  24  * @author Christian Grothoff
  25  */
  26 #include "platform.h"
  27 #include "gnunet_client_lib.h"
  28 #include "gnunet_container_lib.h"
  29 #include "gnunet_peerinfo_service.h"
  30 #include "gnunet_protocols.h"
  31 #include "gnunet_time_lib.h"
  32 #include "peerinfo.h"
  33
  34 #define LOG(kind,...) GNUNET_log_from (kind, "peerinfo-api",__VA_ARGS__)
  35
  36
  37 /**
  38  * Entry in the transmission queue to PEERINFO service.  We use
  39  * the same structure for queueing 'iteration' requests and
  40  * actual 'add' messages.
  41  */
  42 struct GNUNET_PEERINFO_AddContext
  43 {
  44   /**
  45    * This is a linked list.
  46    */
  47   struct GNUNET_PEERINFO_AddContext *next;
  48
  49   /**
  50    * This is a linked list.
  51    */
  52   struct GNUNET_PEERINFO_AddContext *prev;
  53
  54   /**
  55    * Handle to the PEERINFO service.
  56    */
  57   struct GNUNET_PEERINFO_Handle *h;
  58
  59   /**
  60    * Function to call after request has been transmitted, or NULL.
  61    */
  62   GNUNET_PEERINFO_Continuation cont;
  63
  64   /**
  65    * Closure for 'cont'.
  66    */
  67   void *cont_cls;
  68
  69   /**
  70    * Number of bytes of the request message (follows after this struct).
  71    */
  72   size_t size;
  73
  74 };
  75
  76
  77 /**
  78  * Context for an iteration request.
  79  */
  80 struct GNUNET_PEERINFO_IteratorContext
  81 {
  82
  83   /**
  84    * Kept in a DLL.
  85    */
  86   struct GNUNET_PEERINFO_IteratorContext *next;
  87
  88   /**
  89    * Kept in a DLL.
  90    */
  91   struct GNUNET_PEERINFO_IteratorContext *prev;
  92
  93   /**
  94    * Handle to the PEERINFO service.
  95    */
  96   struct GNUNET_PEERINFO_Handle *h;
  97
  98   /**
  99    * Function to call with the results.
 100    */
 101   GNUNET_PEERINFO_Processor callback;
 102
 103   /**
 104    * Closure for 'callback'.
 105    */
 106   void *callback_cls;
 107
 108   /**
 109    * Our entry in the transmission queue.
 110    */
 111   struct GNUNET_PEERINFO_AddContext *ac;
 112
 113   /**
 114    * Task responsible for timeout.
 115    */
 116   GNUNET_SCHEDULER_TaskIdentifier timeout_task;
 117
 118   /**
 119    * Timeout for the operation.
 120    */
 121   struct GNUNET_TIME_Absolute timeout;
 122
 123   /**
 124    * Peer we are interested in (only valid if iteration was restricted to one peer).
 125    */
 126   struct GNUNET_PeerIdentity peer;
 127
 128   /**
 129    * Is 'peer' set?
 130    */
 131   int have_peer;
 132
 133   /**
 134    * Are we now receiving?
 135    */
 136   int in_receive;
 137 };
 138
 139
 140 /**
 141  * Handle to the peerinfo service.
 142  */
 143 struct GNUNET_PEERINFO_Handle
 144 {
 145   /**
 146    * Our configuration.
 147    */
 148   const struct GNUNET_CONFIGURATION_Handle *cfg;
 149
 150   /**
 151    * Connection to the service.
 152    */
 153   struct GNUNET_CLIENT_Connection *client;
 154
 155   /**
 156    * Head of transmission queue.
 157    */
 158   struct GNUNET_PEERINFO_AddContext *ac_head;
 159
 160   /**
 161    * Tail of transmission queue.
 162    */
 163   struct GNUNET_PEERINFO_AddContext *ac_tail;
 164
 165   /**
 166    * Handle for the current transmission request, or NULL if none is pending.
 167    */
 168   struct GNUNET_CLIENT_TransmitHandle *th;
 169
 170   /**
 171    * Head of iterator DLL.
 172    */
 173   struct GNUNET_PEERINFO_IteratorContext *ic_head;
 174
 175   /**
 176    * Tail of iterator DLL.
 177    */
 178   struct GNUNET_PEERINFO_IteratorContext *ic_tail;
 179
 180   /**
 181    * ID for a reconnect task.
 182    */
 183   GNUNET_SCHEDULER_TaskIdentifier r_task;
 184
 185   /**
 186    * Set to GNUNET_YES if we are currently receiving replies from the
 187    * service.
 188    */
 189   int in_receive;
 190
 191 };
 192
 193
 194 /**
 195  * Connect to the peerinfo service.
 196  *
 197  * @param cfg configuration to use
 198  * @return NULL on error (configuration related, actual connection
 199  *         establishment may happen asynchronously).
 200  */
 201 struct GNUNET_PEERINFO_Handle *
 202 GNUNET_PEERINFO_connect (const struct GNUNET_CONFIGURATION_Handle *cfg)
 203 {
 204   struct GNUNET_PEERINFO_Handle *h;
 205
 206   h = GNUNET_malloc (sizeof (struct GNUNET_PEERINFO_Handle));
 207   h->client = GNUNET_CLIENT_connect ("peerinfo", cfg);
 208   h->cfg = cfg;
 209   return h;
 210 }
 211
 212
 213 /**
 214  * Disconnect from the peerinfo service.  Note that all iterators must
 215  * have completed or have been cancelled by the time this function is
 216  * called (otherwise, calling this function is a serious error).
 217  * Furthermore, if 'GNUNET_PEERINFO_add_peer' operations are still
 218  * pending, they will be cancelled silently on disconnect.
 219  *
 220  * @param h handle to disconnect
 221  */
 222 void
 223 GNUNET_PEERINFO_disconnect (struct GNUNET_PEERINFO_Handle *h)
 224 {
 225   struct GNUNET_PEERINFO_AddContext *ac;
 226   struct GNUNET_PEERINFO_IteratorContext *ic;
 227
 228   while (NULL != (ic = h->ic_head))
 229   {
 230     GNUNET_break (GNUNET_YES == ic->in_receive);
 231     ic->in_receive = GNUNET_NO;
 232     GNUNET_PEERINFO_iterate_cancel (ic);
 233   }
 234   while (NULL != (ac = h->ac_head))
 235   {
 236     GNUNET_CONTAINER_DLL_remove (h->ac_head, h->ac_tail, ac);
 237     if (NULL != ac->cont)
 238       ac->cont (ac->cont_cls, _("aborted due to explicit disconnect request"));
 239     GNUNET_free (ac);
 240   }
 241   if (NULL != h->th)
 242   {
 243     GNUNET_CLIENT_notify_transmit_ready_cancel (h->th);
 244     h->th = NULL;
 245   }
 246   if (NULL != h->client)
 247   {
 248     GNUNET_CLIENT_disconnect (h->client);
 249     h->client = NULL;
 250   }
 251   if (GNUNET_SCHEDULER_NO_TASK != h->r_task)
 252   {
 253     GNUNET_SCHEDULER_cancel (h->r_task);
 254     h->r_task = GNUNET_SCHEDULER_NO_TASK;
 255   }
 256   GNUNET_free (h);
 257 }
 258
 259
 260 /**
 261  * Check if we have a request pending in the transmission queue and are
 262  * able to transmit it right now.  If so, schedule transmission.
 263  *
 264  * @param h handle to the service
 265  */
 266 static void
 267 trigger_transmit (struct GNUNET_PEERINFO_Handle *h);
 268
 269
 270 /**
 271  * Close the existing connection to PEERINFO and reconnect.
 272  *
 273  * @param h handle to the service
 274  */
 275 static void
 276 reconnect (struct GNUNET_PEERINFO_Handle *h);
 277
 278
 279 /**
 280  * Task scheduled to re-try connecting to the peerinfo service.
 281  *
 282  * @param cls the 'struct GNUNET_PEERINFO_Handle'
 283  * @param tc scheduler context
 284  */
 285 static void
 286 reconnect_task (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 287 {
 288   struct GNUNET_PEERINFO_Handle *h = cls;
 289
 290   h->r_task = GNUNET_SCHEDULER_NO_TASK;
 291   reconnect (h);
 292 }
 293
 294
 295 /**
 296  * Close the existing connection to PEERINFO and reconnect.
 297  *
 298  * @param h handle to the service
 299  */
 300 static void
 301 reconnect (struct GNUNET_PEERINFO_Handle *h)
 302 {
 303   if (GNUNET_SCHEDULER_NO_TASK != h->r_task)
 304   {
 305     GNUNET_SCHEDULER_cancel (h->r_task);
 306     h->r_task = GNUNET_SCHEDULER_NO_TASK;
 307   }
 308   if (NULL != h->th)
 309   {
 310     GNUNET_CLIENT_notify_transmit_ready_cancel (h->th);
 311     h->th = NULL;
 312   }
 313   if (NULL != h->client)
 314   {
 315     GNUNET_CLIENT_disconnect (h->client);
 316     h->client = NULL;
 317   }
 318   h->in_receive = GNUNET_NO;
 319   h->client = GNUNET_CLIENT_connect ("peerinfo", h->cfg);
 320   if (NULL == h->client)
 321   {
 322     h->r_task =
 323         GNUNET_SCHEDULER_add_delayed (GNUNET_TIME_UNIT_SECONDS, &reconnect_task,
 324                                       h);
 325     return;
 326   }
 327   trigger_transmit (h);
 328 }
 329
 330
 331 /**
 332  * Transmit the request at the head of the transmission queue
 333  * and trigger continuation (if any).
 334  *
 335  * @param cls the 'struct GNUNET_PEERINFO_Handle' (with the queue)
 336  * @param size size of the buffer (0 on error)
 337  * @param buf where to copy the message
 338  * @return number of bytes copied to buf
 339  */
 340 static size_t
 341 do_transmit (void *cls, size_t size, void *buf)
 342 {
 343   struct GNUNET_PEERINFO_Handle *h = cls;
 344   struct GNUNET_PEERINFO_AddContext *ac = h->ac_head;
 345   size_t ret;
 346
 347   h->th = NULL;
 348   if (NULL == ac)
 349     return 0; /* request was cancelled in the meantime */
 350   if (NULL == buf)
 351   {
 352     /* peerinfo service died */
 353     LOG (GNUNET_ERROR_TYPE_DEBUG | GNUNET_ERROR_TYPE_BULK,
 354          "Failed to transmit message to `%s' service.\n", "PEERINFO");
 355     GNUNET_CONTAINER_DLL_remove (h->ac_head, h->ac_tail, ac);
 356     reconnect (h);
 357     if (NULL != ac->cont)
 358       ac->cont (ac->cont_cls, _("failed to transmit request (service down?)"));
 359     GNUNET_free (ac);
 360     return 0;
 361   }
 362   ret = ac->size;
 363   if (size < ret)
 364   {
 365     /* change in head of queue (i.e. cancel + add), try again */
 366     trigger_transmit (h);
 367     return 0;
 368   }
 369   LOG (GNUNET_ERROR_TYPE_DEBUG,
 370        "Transmitting request of size %u to `%s' service.\n", ret, "PEERINFO");
 371   memcpy (buf, &ac[1], ret);
 372   GNUNET_CONTAINER_DLL_remove (h->ac_head, h->ac_tail, ac);
 373   trigger_transmit (h);
 374   if (NULL != ac->cont)
 375     ac->cont (ac->cont_cls, NULL);
 376   GNUNET_free (ac);
 377   return ret;
 378 }
 379
 380
 381 /**
 382  * Check if we have a request pending in the transmission queue and are
 383  * able to transmit it right now.  If so, schedule transmission.
 384  *
 385  * @param h handle to the service
 386  */
 387 static void
 388 trigger_transmit (struct GNUNET_PEERINFO_Handle *h)
 389 {
 390   struct GNUNET_PEERINFO_AddContext *ac;
 391
 392   if (NULL == (ac = h->ac_head))
 393     return; /* no requests queued */
 394   if (NULL != h->th)
 395     return; /* request already pending */
 396   if (GNUNET_YES == h->in_receive)
 397     return; /* still reading replies from last request */
 398   if (NULL == h->client)
 399   {
 400     /* disconnected, try to reconnect */
 401     reconnect (h);
 402     return;
 403   }
 404   h->th =
 405     GNUNET_CLIENT_notify_transmit_ready (h->client, ac->size,
 406                                          GNUNET_TIME_UNIT_FOREVER_REL,
 407                                          GNUNET_YES,
 408                                          &do_transmit, h);
 409 }
 410
 411
 412 /**
 413  * Add a host to the persistent list.  This method operates in
 414  * semi-reliable mode: if the transmission is not completed by
 415  * the time 'GNUNET_PEERINFO_disconnect' is called, it will be
 416  * aborted.  Furthermore, if a second HELLO is added for the
 417  * same peer before the first one was transmitted, PEERINFO may
 418  * merge the two HELLOs prior to transmission to the service.
 419  *
 420  * @param h handle to the peerinfo service
 421  * @param hello the verified (!) HELLO message
 422  * @param cont continuation to call when done, NULL is allowed
 423  * @param cont_cls closure for 'cont'
 424  * @return handle to cancel add operation; all pending
 425  *         'add' operations will be cancelled automatically
 426  *        on disconnect, so it is not necessary to keep this
 427  *        handle (unless 'cont' is NULL and at some point
 428  *        calling 'cont' must be prevented)
 429  */
 430 struct GNUNET_PEERINFO_AddContext *
 431 GNUNET_PEERINFO_add_peer (struct GNUNET_PEERINFO_Handle *h,
 432                           const struct GNUNET_HELLO_Message *hello,
 433                           GNUNET_PEERINFO_Continuation cont,
 434                           void *cont_cls)
 435 {
 436   uint16_t hs = GNUNET_HELLO_size (hello);
 437   struct GNUNET_PEERINFO_AddContext *ac;
 438   struct GNUNET_PeerIdentity peer;
 439
 440   GNUNET_assert (GNUNET_OK == GNUNET_HELLO_get_id (hello, &peer));
 441   LOG (GNUNET_ERROR_TYPE_DEBUG,
 442        "Adding peer `%s' to PEERINFO database (%u bytes of `%s')\n",
 443        GNUNET_i2s (&peer), hs, "HELLO");
 444   ac = GNUNET_malloc (sizeof (struct GNUNET_PEERINFO_AddContext) + hs);
 445   ac->h = h;
 446   ac->size = hs;
 447   ac->cont = cont;
 448   ac->cont_cls = cont_cls;
 449   memcpy (&ac[1], hello, hs);
 450   GNUNET_CONTAINER_DLL_insert_tail (h->ac_head, h->ac_tail, ac);
 451   trigger_transmit (h);
 452   return ac;
 453 }
 454
 455
 456 /**
 457  * Cancel pending 'add' operation.  Must only be called before
 458  * either 'cont' or 'GNUNET_PEERINFO_disconnect' are invoked.
 459  *
 460  * @param ac handle for the add operation to cancel
 461  */
 462 void
 463 GNUNET_PEERINFO_add_peer_cancel (struct GNUNET_PEERINFO_AddContext *ac)
 464 {
 465   struct GNUNET_PEERINFO_Handle *h = ac->h;
 466
 467   GNUNET_CONTAINER_DLL_remove (h->ac_head, h->ac_tail, ac);
 468   GNUNET_free (ac);
 469 }
 470
 471
 472 /**
 473  * Type of a function to call when we receive a message from the
 474  * service.  Call the iterator with the result and (if applicable)
 475  * continue to receive more messages or trigger processing the next
 476  * event (if applicable).
 477  *
 478  * @param cls closure
 479  * @param msg message received, NULL on timeout or fatal error
 480  */
 481 static void
 482 peerinfo_handler (void *cls, const struct GNUNET_MessageHeader *msg)
 483 {
 484   struct GNUNET_PEERINFO_Handle *h = cls;
 485   struct GNUNET_PEERINFO_IteratorContext *ic = h->ic_head;
 486   const struct InfoMessage *im;
 487   const struct GNUNET_HELLO_Message *hello;
 488   GNUNET_PEERINFO_Processor cb;
 489   struct GNUNET_PeerIdentity id;
 490   void *cb_cls;
 491   uint16_t ms;
 492
 493   h->in_receive = GNUNET_NO;
 494   ic->in_receive = GNUNET_NO;
 495   cb = ic->callback;
 496   cb_cls = ic->callback_cls;
 497   if (NULL == msg)
 498   {
 499     /* peerinfo service died, signal error */
 500     GNUNET_PEERINFO_iterate_cancel (ic);
 501     reconnect (h);
 502     if (NULL != cb)
 503       cb (cb_cls, NULL, NULL,
 504           _("Failed to receive response from `PEERINFO' service."));
 505     return;
 506   }
 507   if (GNUNET_MESSAGE_TYPE_PEERINFO_INFO_END == ntohs (msg->type))
 508   {
 509     /* normal end of list of peers, signal end, process next pending request */
 510     LOG (GNUNET_ERROR_TYPE_DEBUG,
 511          "Received end of list of peers from `%s' service\n", "PEERINFO");
 512     GNUNET_PEERINFO_iterate_cancel (ic);
 513     trigger_transmit (h);
 514     if (NULL != cb)
 515       cb (cb_cls, NULL, NULL, NULL);
 516     return;
 517   }
 518   ms = ntohs (msg->size);
 519   if ((ms < sizeof (struct InfoMessage)) ||
 520       (ntohs (msg->type) != GNUNET_MESSAGE_TYPE_PEERINFO_INFO))
 521   {
 522     /* malformed message */
 523     GNUNET_break (0);
 524     GNUNET_PEERINFO_iterate_cancel (ic);
 525     reconnect (h);
 526     if (NULL != cb)
 527       cb (cb_cls, NULL, NULL,
 528           _("Received invalid message from `PEERINFO' service."));
 529     return;
 530   }
 531   im = (const struct InfoMessage *) msg;
 532   GNUNET_break (0 == ntohl (im->reserved));
 533   if ( (GNUNET_YES == ic->have_peer) &&
 534        (0 != memcmp (&ic->peer, &im->peer, sizeof (struct GNUNET_PeerIdentity))) )
 535   {
 536     /* bogus message (from a different iteration call?); out of sequence! */
 537     LOG (GNUNET_ERROR_TYPE_ERROR,
 538          "Received HELLO for peer `%s', expected peer `%s'\n",
 539          GNUNET_h2s (&im->peer.hashPubKey),
 540          GNUNET_i2s (&ic->peer));
 541
 542     GNUNET_break (0);
 543     GNUNET_PEERINFO_iterate_cancel (ic);
 544     reconnect (h);
 545     if (NULL != cb)
 546       cb (cb_cls, NULL, NULL,
 547           _("Received invalid message from `PEERINFO' service."));
 548     return;
 549   }
 550   hello = NULL;
 551   if (ms > sizeof (struct InfoMessage) + sizeof (struct GNUNET_MessageHeader))
 552   {
 553     hello = (const struct GNUNET_HELLO_Message *) &im[1];
 554     if (ms != sizeof (struct InfoMessage) + GNUNET_HELLO_size (hello))
 555     {
 556       /* malformed message */
 557       GNUNET_break (0);
 558       GNUNET_PEERINFO_iterate_cancel (ic);
 559       reconnect (h);
 560       if (NULL != cb)
 561         cb (cb_cls, NULL, NULL,
 562             _("Received invalid message from `PEERINFO' service."));
 563       return;
 564     }
 565     if (GNUNET_OK != GNUNET_HELLO_get_id (hello, &id))
 566     {
 567       /* malformed message */
 568       GNUNET_break (0);
 569       GNUNET_PEERINFO_iterate_cancel (ic);
 570       reconnect (h);
 571       if (NULL != cb)
 572         cb (cb_cls, NULL, NULL,
 573             _("Received invalid message from `PEERINFO' service."));
 574       return;
 575     }
 576     if (0 != memcmp (&im->peer, &id, sizeof (struct GNUNET_PeerIdentity)))
 577     {
 578       /* malformed message */
 579       GNUNET_break (0);
 580       GNUNET_PEERINFO_iterate_cancel (ic);
 581       reconnect (h);
 582       if (NULL != cb)
 583         cb (cb_cls, NULL, NULL,
 584             _("Received invalid message from `PEERINFO' service."));
 585       return;
 586     }
 587   }
 588
 589   /* normal data message */
 590   LOG (GNUNET_ERROR_TYPE_DEBUG,
 591        "Received %u bytes of `%s' information about peer `%s' from `%s' service\n",
 592        (hello == NULL) ? 0 : (unsigned int) GNUNET_HELLO_size (hello), "HELLO",
 593        GNUNET_i2s (&im->peer), "PEERINFO");
 594   h->in_receive = GNUNET_YES;
 595   ic->in_receive = GNUNET_YES;
 596   GNUNET_CLIENT_receive (h->client, &peerinfo_handler, ic,
 597                          GNUNET_TIME_absolute_get_remaining (ic->timeout));
 598   if (NULL != cb)
 599     cb (cb_cls, &im->peer, hello, NULL);
 600 }
 601
 602
 603 /**
 604  * We've transmitted the iteration request.  Now get ready to process
 605  * the results (or handle transmission error).
 606  *
 607  * @param cls the 'struct GNUNET_PEERINFO_IteratorContext'
 608  * @param emsg error message, NULL if transmission worked
 609  */
 610 static void
 611 iterator_start_receive (void *cls, const char *emsg)
 612 {
 613   struct GNUNET_PEERINFO_IteratorContext *ic = cls;
 614   struct GNUNET_PEERINFO_Handle *h = ic->h;
 615   GNUNET_PEERINFO_Processor cb;
 616   void *cb_cls;
 617
 618   ic->ac = NULL;
 619   if (NULL != emsg)
 620   {
 621     cb = ic->callback;
 622     cb_cls = ic->callback_cls;
 623     GNUNET_PEERINFO_iterate_cancel (ic);
 624     reconnect (h);
 625     if (NULL != cb)
 626       cb (cb_cls, NULL, NULL, emsg);
 627     return;
 628   }
 629   LOG (GNUNET_ERROR_TYPE_DEBUG, "Waiting for response from `%s' service.\n",
 630        "PEERINFO");
 631   ic->in_receive = GNUNET_YES;
 632   if (GNUNET_NO == h->in_receive)
 633   {
 634     h->in_receive = GNUNET_YES;
 635     GNUNET_CLIENT_receive (h->client, &peerinfo_handler, h,
 636                            GNUNET_TIME_absolute_get_remaining (ic->timeout));
 637   }
 638 }
 639
 640
 641 /**
 642  * Peerinfo iteration request has timed out.
 643  *
 644  * @param cls the 'struct GNUNET_PEERINFO_IteratorContext*'
 645  * @param tc scheduler context
 646  */
 647 static void
 648 signal_timeout (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 649 {
 650   struct GNUNET_PEERINFO_IteratorContext *ic = cls;
 651   GNUNET_PEERINFO_Processor cb;
 652   void *cb_cls;
 653
 654   ic->timeout_task = GNUNET_SCHEDULER_NO_TASK;
 655   cb = ic->callback;
 656   cb_cls = ic->callback_cls;
 657   GNUNET_PEERINFO_iterate_cancel (ic);
 658   if (NULL != cb)
 659     cb (cb_cls, NULL, NULL,
 660         _("Timeout transmitting iteration request to `PEERINFO' service."));
 661 }
 662
 663
 664 /**
 665  * Call a method for each known matching host and change its trust
 666  * value.  The callback method will be invoked once for each matching
 667  * host and then finally once with a NULL pointer.  After that final
 668  * invocation, the iterator context must no longer be used.
 669  *
 670  * Instead of calling this function with 'peer == NULL' it is often
 671  * better to use 'GNUNET_PEERINFO_notify'.
 672  *
 673  * @param h handle to the peerinfo service
 674  * @param peer restrict iteration to this peer only (can be NULL)
 675  * @param timeout how long to wait until timing out
 676  * @param callback the method to call for each peer
 677  * @param callback_cls closure for callback
 678  * @return iterator context
 679  */
 680 struct GNUNET_PEERINFO_IteratorContext *
 681 GNUNET_PEERINFO_iterate (struct GNUNET_PEERINFO_Handle *h,
 682                          const struct GNUNET_PeerIdentity *peer,
 683                          struct GNUNET_TIME_Relative timeout,
 684                          GNUNET_PEERINFO_Processor callback, void *callback_cls)
 685 {
 686   struct GNUNET_MessageHeader *lapm;
 687   struct ListPeerMessage *lpm;
 688   struct GNUNET_PEERINFO_IteratorContext *ic;
 689   struct GNUNET_PEERINFO_AddContext *ac;
 690
 691   ic = GNUNET_malloc (sizeof (struct GNUNET_PEERINFO_IteratorContext));
 692   if (NULL == peer)
 693   {
 694     LOG (GNUNET_ERROR_TYPE_DEBUG,
 695          "Requesting list of peers from PEERINFO service\n");
 696     ac =
 697         GNUNET_malloc (sizeof (struct GNUNET_PEERINFO_AddContext) +
 698                        sizeof (struct GNUNET_MessageHeader));
 699     ac->size = sizeof (struct GNUNET_MessageHeader);
 700     lapm = (struct GNUNET_MessageHeader *) &ac[1];
 701     lapm->size = htons (sizeof (struct GNUNET_MessageHeader));
 702     lapm->type = htons (GNUNET_MESSAGE_TYPE_PEERINFO_GET_ALL);
 703   }
 704   else
 705   {
 706     LOG (GNUNET_ERROR_TYPE_DEBUG,
 707          "Requesting information on peer `%4s' from PEERINFO service\n",
 708          GNUNET_i2s (peer));
 709     ac =
 710         GNUNET_malloc (sizeof (struct GNUNET_PEERINFO_AddContext) +
 711                        sizeof (struct ListPeerMessage));
 712     ac->size = sizeof (struct ListPeerMessage);
 713     lpm = (struct ListPeerMessage *) &ac[1];
 714     lpm->header.size = htons (sizeof (struct ListPeerMessage));
 715     lpm->header.type = htons (GNUNET_MESSAGE_TYPE_PEERINFO_GET);
 716     memcpy (&lpm->peer, peer, sizeof (struct GNUNET_PeerIdentity));
 717     ic->have_peer = GNUNET_YES;
 718     ic->peer = *peer;
 719   }
 720   ic->h = h;
 721   ic->ac = ac;
 722   ic->callback = callback;
 723   ic->callback_cls = callback_cls;
 724   ic->timeout = GNUNET_TIME_relative_to_absolute (timeout);
 725   ic->timeout_task =
 726       GNUNET_SCHEDULER_add_delayed (timeout, &signal_timeout, ic);
 727   ac->cont = &iterator_start_receive;
 728   ac->cont_cls = ic;
 729   GNUNET_CONTAINER_DLL_insert_tail (h->ac_head, h->ac_tail, ac);
 730   GNUNET_CONTAINER_DLL_insert_tail (h->ic_head,
 731                                     h->ic_tail,
 732                                     ic);
 733   trigger_transmit (h);
 734   return ic;
 735 }
 736
 737
 738 /**
 739  * Cancel an iteration over peer information.
 740  *
 741  * @param ic context of the iterator to cancel
 742  */
 743 void
 744 GNUNET_PEERINFO_iterate_cancel (struct GNUNET_PEERINFO_IteratorContext *ic)
 745 {
 746   struct GNUNET_PEERINFO_Handle *h;
 747
 748   h = ic->h;
 749   GNUNET_CONTAINER_DLL_remove (h->ic_head,
 750                                h->ic_tail,
 751                                ic);
 752   if (GNUNET_SCHEDULER_NO_TASK != ic->timeout_task)
 753   {
 754     GNUNET_SCHEDULER_cancel (ic->timeout_task);
 755     ic->timeout_task = GNUNET_SCHEDULER_NO_TASK;
 756   }
 757   ic->callback = NULL;
 758   if (GNUNET_YES == ic->in_receive)
 759     return;                     /* need to finish processing */
 760   if (NULL != ic->ac)
 761   {
 762     GNUNET_CONTAINER_DLL_remove (h->ac_head, h->ac_tail, ic->ac);
 763     GNUNET_free (ic->ac);
 764   }
 765   GNUNET_free (ic);
 766 }
 767
 768
 769 /* end of peerinfo_api.c */