src/include/gnunet_nc_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2012-2016 GNUnet e.V.
   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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20 /**
  21  * @author Christian Grothoff
  22  *
  23  * @file
  24  * General-purpose broadcast mechanism for message queues
  25  *
  26  * @defgroup mq  NC library
  27  * General-purpose broadcast mechanism for message queues
  28  *
  29  * @see [Documentation](https://gnunet.org/nc)
  30  *
  31  * @{
  32  */
  33 #ifndef GNUNET_NC_H
  34 #define GNUNET_NC_H
  35
  36
  37 /**
  38  * The notification context is the key datastructure for a convenience
  39  * API used for transmission of notifications to the subscriber until the
  40  * subscriber disconnects (or the notification context is destroyed, in
  41  * which case we disconnect these subscribers).  Essentially, all
  42  * (notification) messages are queued up until the subscriber is able to
  43  * read them.
  44  */
  45 struct GNUNET_NotificationContext;
  46
  47
  48 /**
  49  * Create a new notification context.
  50  *
  51  * @param queue_length maximum number of messages to keep in
  52  *        the notification queue; optional messages are dropped
  53  *        if the queue gets longer than this number of messages
  54  * @return handle to the notification context
  55  */
  56 struct GNUNET_NotificationContext *
  57 GNUNET_notification_context_create (unsigned int queue_length);
  58
  59
  60 /**
  61  * Destroy the context, force disconnect for all subscribers.
  62  *
  63  * @param nc context to destroy.
  64  */
  65 void
  66 GNUNET_notification_context_destroy (struct GNUNET_NotificationContext *nc);
  67
  68
  69 /**
  70  * Add a subscriber to the notification context.
  71  *
  72  * @param nc context to modify
  73  * @param mq message queue add
  74  */
  75 void
  76 GNUNET_notification_context_add (struct GNUNET_NotificationContext *nc,
  77                                  struct GNUNET_MQ_Handle *mq);
  78
  79
  80 /**
  81  * Send a message to all subscribers of this context.
  82  *
  83  * @param nc context to modify
  84  * @param msg message to send
  85  * @param can_drop can this message be dropped due to queue length limitations
  86  */
  87 void
  88 GNUNET_notification_context_broadcast (struct GNUNET_NotificationContext *nc,
  89                                        const struct GNUNET_MessageHeader *msg,
  90                                        int can_drop);
  91
  92 /**
  93  * Return active number of subscribers in this context.
  94  *
  95  * @param nc context to query
  96  * @return number of current subscribers
  97  */
  98 unsigned int
  99 GNUNET_notification_context_get_size (struct GNUNET_NotificationContext *nc);
 100
 101 #endif