src/include/gnunet_set_service.h

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