src/include/gnunet_set_service.h

   1 // FIXME: copyright, etc.
   2
   3 /**
   4  * The operation that a set set supports.
   5  */
   6 enum GNUNET_SET_Operation
   7 {
   8   /**
   9    * Set intersection, only return elements that are in both sets.
  10    */
  11   GNUNET_SET_OPERATION_INTERSECTION,
  12   /**
  13    * Set union, return all elements that are in at least one of the sets.
  14    */
  15   GNUNET_SET_OPERATION_UNION
  16 };
  17
  18 /**
  19  * Status for the result callback
  20  */
  21 enum GNUNET_SET_Status
  22 {
  23   /**
  24    * Everything went ok.
  25    */
  26   GNUNET_SET_STATUS_OK,
  27   /**
  28    * There was a timeout.
  29    */
  30   GNUNET_SET_STATUS_TIMEOUT,
  31   /*
  32    * The other peer refused to to the operation with us
  33    */
  34   GNUNET_SET_STATUS_REFUSED
  35 };
  36
  37 // FIXME: comment
  38 struct GNUNET_SET_Element
  39 {
  40   /**
  41    * Number of bytes in the buffer pointed to by data.
  42    */
  43   uint16_t size;
  44   /**
  45    * Application-specific element type.
  46    */
  47   uint16_t type;
  48   /**
  49    * Actual data of the element
  50    */
  51   void *data;
  52 };
  53
  54
  55 /**
  56  * Create an empty set, supporting the specified operation.
  57  *
  58  * @param op operation supported by the set
  59  *        Note that the operation has to be specified
  60  *        beforehand, as certain set operations need to maintain
  61  *        data structures spefific to the operation
  62  * @return a handle to the set
  63  */
  64 struct GNUNET_SET_Handle *
  65 GNUNET_SET_create (enum GNUNET_SET_Operation op);
  66
  67
  68 // FIXME: comment
  69 void
  70 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
  71                         const struct GNUNET_SET_Element *element,
  72                         GNUNET_SET_Continuation cont,
  73                         void *cont_cls);
  74
  75
  76 // FIXME: comment
  77 void
  78 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
  79                            const struct GNUNET_SET_Element *element,
  80                            GNUNET_SET_Continuation cont,
  81                            void *cont_cls);
  82
  83
  84 // FIXME: comment
  85 struct GNUNET_SET_Handle *
  86 GNUNET_SET_clone (struct GNUNET_SET_Handle *set);
  87
  88
  89 // FIXME: comment
  90 void
  91 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
  92
  93
  94
  95 /**
  96  * Callback for set operation results. Called for each element
  97  * in the result set.
  98 // FIXME: might want a way to just get the 'additional/removd' elements
  99  *
 100  * @param cls closure
 101  * @param element element, or NULL to indicate that all elements
 102  *        have been passed to the callback
 103  *        Only valid if (status==GNUNET_SET_STATUS_OK) holds.
 104  * @param status see enum GNUNET_SET_Status
 105  */
 106 typedef void
 107 (*GNUNET_SET_ResultIterator) (void *cls,
 108                               struct GNUNET_SET_Element *element,
 109                               enum GNUNET_SET_ResultStatus status);
 110
 111
 112 /**
 113  * Evaluate a set operation with our set and the set of another peer.
 114  *
 115  * @param other_peer peer with the other set
 116  * @param app_id hash for the application using the set
 117  * @param context_msg additional information for the request
 118  * @param result_cb called on error or success
 119  * @param result_cls closure for result_cb
 120  * @return a handle to cancel the operation
 121  */
 122 struct GNUNET_SET_OperationHandle *
 123 GNUNET_SET_evaluate (const struct GNUNET_PeerIdentity *other_peer,
 124                      const struct GNUNET_HashCode *app_id,
 125                      const struct GNUNET_MessageHeader *context_msg,
 126                      struct GNUNET_TIME_Relative timeout,
 127                      GNUNET_SET_ResultIterator result_cb,
 128                      void *result_cls);
 129
 130
 131 /**
 132  * Called when another peer wants to do a set operation with the
 133  * local peer
 134  *
 135  * @param other_peer the other peer
 136  * @param context_msg message with application specific information from
 137  *        the other peer
 138  * @param request request from the other peer, use GNUNET_SET_accept
 139  *        to accept it, otherwise the request will be refused
 140  *        Note that we don't use a return value here, as it is also
 141  *        necessary to specify the set we want to do the operation with,
 142  *        whith sometimes can be derived from the context message.
 143  *        Also necessary to specify the timeout.
 144  */
 145 typedef void
 146 (*GNUNET_SET_ListenCallback) (void *cls,
 147                               const struct GNUNET_PeerIdentity *other_peer,
 148                               const struct GNUNET_MessageHeader *context_msg,
 149                               struct GNUNET_SET_Request *request);
 150
 151
 152 /**
 153  * Wait for set operation requests for the given application id
 154  *
 155  * @param operation operation we want to listen for
 156  * @param app_id id of the application that handles set operation requests
 157  * @param listen_cb called for each incoming request matching the operation
 158  *                  and application id
 159  * @param listen_cls handle for listen_cb
 160  * @return a handle that can be used to cancel the listen operation
 161  */
 162 struct GNUNET_SET_ListenHandle *
 163 GNUNET_SET_listen (enum GNUNET_SET_Operation operation,
 164                    const struct GNUNET_HashCode *app_id,
 165                    GNUNET_SET_ListenCallback listen_cb,
 166                    void *listen_cls);
 167
 168
 169
 170 // FIXME: comment
 171 void
 172 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 173
 174
 175 /**
 176  * Accept a request we got via GNUNET_SET_listen
 177  *
 178  * @param request request to accept
 179  * @param set set used for the requested operation
 180  * @param timeout timeout for the set operation
 181  * @param result_cb callback for the results
 182  * @param cls closure for result_cb
 183  */
 184 struct GNUNET_SET_OperationHandle *
 185 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
 186                    struct GNUNET_SET_Handle *set,
 187                    struct GNUNET_TIME_Relative timeout,
 188                    GNUNET_SET_ResultIterator result_cb,
 189                    void *cls)
 190
 191
 192 // FIXME: comment
 193 void
 194 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *op);
 195
 196