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 it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 /**
  19  * @author Christian Grothoff
  20  *
  21  * @file
  22  * General-purpose broadcast mechanism for message queues
  23  *
  24  * @defgroup mq  NC library
  25  * General-purpose broadcast mechanism for message queues
  26  *
  27  * @see [Documentation](https://gnunet.org/nc)
  28  *
  29  * @{
  30  */
  31 #ifndef GNUNET_NC_H
  32 #define GNUNET_NC_H
  33
  34
  35 /**
  36  * The notification context is the key datastructure for a convenience
  37  * API used for transmission of notifications to the subscriber until the
  38  * subscriber disconnects (or the notification context is destroyed, in
  39  * which case we disconnect these subscribers).  Essentially, all
  40  * (notification) messages are queued up until the subscriber is able to
  41  * read them.
  42  */
  43 struct GNUNET_NotificationContext;
  44
  45
  46 /**
  47  * Create a new notification context.
  48  *
  49  * @param queue_length maximum number of messages to keep in
  50  *        the notification queue; optional messages are dropped
  51  *        if the queue gets longer than this number of messages
  52  * @return handle to the notification context
  53  */
  54 struct GNUNET_NotificationContext *
  55 GNUNET_notification_context_create (unsigned int queue_length);
  56
  57
  58 /**
  59  * Destroy the context, force disconnect for all subscribers.
  60  *
  61  * @param nc context to destroy.
  62  */
  63 void
  64 GNUNET_notification_context_destroy (struct GNUNET_NotificationContext *nc);
  65
  66
  67 /**
  68  * Add a subscriber to the notification context.
  69  *
  70  * @param nc context to modify
  71  * @param mq message queue add
  72  */
  73 void
  74 GNUNET_notification_context_add (struct GNUNET_NotificationContext *nc,
  75                                  struct GNUNET_MQ_Handle *mq);
  76
  77
  78 /**
  79  * Send a message to all subscribers of this context.
  80  *
  81  * @param nc context to modify
  82  * @param msg message to send
  83  * @param can_drop can this message be dropped due to queue length limitations
  84  */
  85 void
  86 GNUNET_notification_context_broadcast (struct GNUNET_NotificationContext *nc,
  87                                        const struct GNUNET_MessageHeader *msg,
  88                                        int can_drop);
  89
  90 /**
  91  * Return active number of subscribers in this context.
  92  *
  93  * @param nc context to query
  94  * @return number of current subscribers
  95  */
  96 unsigned int
  97 GNUNET_notification_context_get_size (struct GNUNET_NotificationContext *nc);
  98
  99 #endif