src/include/gnunet_reclaim_attribute_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2017 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      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Martin Schanzenbach
  23  *
  24  * @file
  25  * Identity attribute definitions
  26  *
  27  * @defgroup reclaim-attribute reclaim attributes
  28  * @{
  29  */
  30 #ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  31 #define GNUNET_RECLAIM_ATTRIBUTE_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #if 0 /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_util_lib.h"
  41
  42
  43 /**
  44  * No value attribute.
  45  */
  46 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_NONE 0
  47
  48 /**
  49  * String attribute.
  50  */
  51 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_STRING 1
  52
  53
  54 /**
  55  * An attribute.
  56  */
  57 struct GNUNET_RECLAIM_ATTRIBUTE_Claim
  58 {
  59   /**
  60    * ID
  61    */
  62   uint64_t id;
  63
  64   /**
  65    * Type of Claim
  66    */
  67   uint32_t type;
  68
  69   /**
  70    * Version
  71    */
  72   uint32_t version;
  73   /**
  74    * The name of the attribute. Note "name" must never be individually
  75    * free'd
  76    */
  77   const char *name;
  78
  79   /**
  80    * Number of bytes in @e data.
  81    */
  82   size_t data_size;
  83
  84   /**
  85    * Binary value stored as attribute value.  Note: "data" must never
  86    * be individually 'malloc'ed, but instead always points into some
  87    * existing data area.
  88    */
  89   const void *data;
  90 };
  91
  92
  93 /**
  94  * A list of GNUNET_RECLAIM_ATTRIBUTE_Claim structures.
  95  */
  96 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList
  97 {
  98   /**
  99    * List head
 100    */
 101   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_head;
 102
 103   /**
 104    * List tail
 105    */
 106   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_tail;
 107 };
 108
 109
 110 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
 111 {
 112   /**
 113    * DLL
 114    */
 115   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *prev;
 116
 117   /**
 118    * DLL
 119    */
 120   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *next;
 121
 122   /**
 123    * The attribute claim
 124    */
 125   struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim;
 126 };
 127
 128
 129 /**
 130  * Create a new attribute claim.
 131  *
 132  * @param attr_name the attribute name
 133  * @param type the attribute type
 134  * @param data the attribute value
 135  * @param data_size the attribute value size
 136  * @return the new attribute
 137  */
 138 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 139 GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char *attr_name,
 140                                     uint32_t type,
 141                                     const void *data,
 142                                     size_t data_size);
 143
 144
 145 /**
 146  * Get required size for serialization buffer
 147  *
 148  * @param attrs the attribute list to serialize
 149  * @return the required buffer size
 150  */
 151 size_t
 152 GNUNET_RECLAIM_ATTRIBUTE_list_serialize_get_size (
 153   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 154
 155
 156 /**
 157  * Destroy claim list
 158  *
 159  * @param attrs list to destroy
 160  */
 161 void
 162 GNUNET_RECLAIM_ATTRIBUTE_list_destroy (
 163   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 164
 165
 166 /**
 167  * Add a new attribute to a claim list
 168  *
 169  * @param attr_name the name of the new attribute claim
 170  * @param type the type of the claim
 171  * @param data claim payload
 172  * @param data_size claim payload size
 173  */
 174 void
 175 GNUNET_RECLAIM_ATTRIBUTE_list_add (
 176   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 177   const char *attr_name,
 178   uint32_t type,
 179   const void *data,
 180   size_t data_size);
 181
 182
 183 /**
 184  * Serialize an attribute list
 185  *
 186  * @param attrs the attribute list to serialize
 187  * @param result the serialized attribute
 188  * @return length of serialized data
 189  */
 190 size_t
 191 GNUNET_RECLAIM_ATTRIBUTE_list_serialize (
 192   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 193   char *result);
 194
 195
 196 /**
 197  * Deserialize an attribute list
 198  *
 199  * @param data the serialized attribute list
 200  * @param data_size the length of the serialized data
 201  * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
 202  */
 203 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
 204 GNUNET_RECLAIM_ATTRIBUTE_list_deserialize (const char *data, size_t data_size);
 205
 206
 207 /**
 208  * Get required size for serialization buffer
 209  *
 210  * @param attr the attribute to serialize
 211  * @return the required buffer size
 212  */
 213 size_t
 214 GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (
 215   const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
 216
 217
 218 /**
 219  * Serialize an attribute
 220  *
 221  * @param attr the attribute to serialize
 222  * @param result the serialized attribute
 223  * @return length of serialized data
 224  */
 225 size_t
 226 GNUNET_RECLAIM_ATTRIBUTE_serialize (
 227   const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
 228   char *result);
 229
 230
 231 /**
 232  * Deserialize an attribute
 233  *
 234  * @param data the serialized attribute
 235  * @param data_size the length of the serialized data
 236  *
 237  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
 238  */
 239 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
 240 GNUNET_RECLAIM_ATTRIBUTE_deserialize (const char *data, size_t data_size);
 241
 242
 243 /**
 244  * Make a (deep) copy of a claim list
 245  * @param attrs claim list to copy
 246  * @return copied claim list
 247  */
 248 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
 249 GNUNET_RECLAIM_ATTRIBUTE_list_dup (
 250   const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 251
 252
 253 /**
 254  * Convert a type name to the corresponding number
 255  *
 256  * @param typename name to convert
 257  * @return corresponding number, UINT32_MAX on error
 258  */
 259 uint32_t
 260 GNUNET_RECLAIM_ATTRIBUTE_typename_to_number (const char *typename);
 261
 262 /**
 263  * Convert human-readable version of a 'claim' of an attribute to the binary
 264  * representation
 265  *
 266  * @param type type of the claim
 267  * @param s human-readable string
 268  * @param data set to value in binary encoding (will be allocated)
 269  * @param data_size set to number of bytes in @a data
 270  * @return #GNUNET_OK on success
 271  */
 272 int
 273 GNUNET_RECLAIM_ATTRIBUTE_string_to_value (uint32_t type,
 274                                           const char *s,
 275                                           void **data,
 276                                           size_t *data_size);
 277
 278
 279 /**
 280  * Convert the 'claim' of an attribute to a string
 281  *
 282  * @param type the type of attribute
 283  * @param data claim in binary encoding
 284  * @param data_size number of bytes in @a data
 285  * @return NULL on error, otherwise human-readable representation of the claim
 286  */
 287 char *
 288 GNUNET_RECLAIM_ATTRIBUTE_value_to_string (uint32_t type,
 289                                           const void *data,
 290                                           size_t data_size);
 291
 292
 293 /**
 294  * Convert a type number to the corresponding type string
 295  *
 296  * @param type number of a type
 297  * @return corresponding typestring, NULL on error
 298  */
 299 const char *
 300 GNUNET_RECLAIM_ATTRIBUTE_number_to_typename (uint32_t type);
 301
 302
 303 #if 0 /* keep Emacsens' auto-indent happy */
 304 {
 305 #endif
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310
 311 /* ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H */
 312 #endif
 313
 314 /** @} */ /* end of group reclaim-attribute */
 315
 316 /* end of gnunet_reclaim_attribute_lib.h */