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