src/fs/fs_file_information.c

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file fs/fs_file_information.c
  23  * @brief  Manage information for publishing directory hierarchies
  24  * @author Christian Grothoff
  25  *
  26  * TODO:
  27  * - serialization/deserialization (& deserialization API)
  28  * - metadata filename clean up code
  29  * - metadata/ksk generation for directories from contained files
  30  */
  31 #include "platform.h"
  32 #include <extractor.h>
  33 #include "gnunet_fs_service.h"
  34 #include "fs.h"
  35 #include "fs_tree.h"
  36
  37
  38 /**
  39  * Add meta data that libextractor finds to our meta data
  40  * container.
  41  *
  42  * @param cls closure, our meta data container
  43  * @param plugin_name name of the plugin that produced this value;
  44  *        special values can be used (i.e. '&lt;zlib&gt;' for zlib being
  45  *        used in the main libextractor library and yielding
  46  *        meta data).
  47  * @param type libextractor-type describing the meta data
  48  * @param format basic format information about data
  49  * @param data_mime_type mime-type of data (not of the original file);
  50  *        can be NULL (if mime-type is not known)
  51  * @param data actual meta-data found
  52  * @param data_len number of bytes in data
  53  * @return always 0 to continue extracting
  54  */
  55 static int
  56 add_to_md(void *cls,
  57           const char *plugin_name,
  58           enum EXTRACTOR_MetaType type,
  59           enum EXTRACTOR_MetaFormat format,
  60           const char *data_mime_type,
  61           const char *data,
  62           size_t data_len)
  63 {
  64   struct GNUNET_CONTAINER_MetaData *md = cls;
  65   (void) GNUNET_CONTAINER_meta_data_insert (md,
  66                                             plugin_name,
  67                                             type,
  68                                             format,
  69                                             data_mime_type,
  70                                             data,
  71                                             data_len);
  72   return 0;
  73 }
  74
  75
  76 /**
  77  * Extract meta-data from a file.
  78  *
  79  * @return GNUNET_SYSERR on error, otherwise the number
  80  *   of meta-data items obtained
  81  */
  82 int
  83 GNUNET_FS_meta_data_extract_from_file (struct GNUNET_CONTAINER_MetaData
  84                                        *md, const char *filename,
  85                                        struct EXTRACTOR_PluginList *
  86                                        extractors)
  87 {
  88   int old;
  89
  90   if (filename == NULL)
  91     return GNUNET_SYSERR;
  92   if (extractors == NULL)
  93     return 0;
  94   old = GNUNET_CONTAINER_meta_data_iterate (md, NULL, NULL);
  95   GNUNET_assert (old >= 0);
  96   EXTRACTOR_extract (extractors,
  97                      filename,
  98                      NULL, 0,
  99                      &add_to_md,
 100                      md);
 101   return (GNUNET_CONTAINER_meta_data_iterate (md, NULL, NULL) - old);
 102 }
 103
 104
 105
 106 /**
 107  * Obtain the name under which this file information
 108  * structure is stored on disk.  Only works for top-level
 109  * file information structures.
 110  *
 111  * @param s structure to get the filename for
 112  * @return NULL on error, otherwise filename that
 113  *         can be passed to "GNUNET_FS_file_information_recover"
 114  *         to read this fi-struct from disk.
 115  */
 116 const char *
 117 GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s)
 118 {
 119   if (NULL != s->dir)
 120     return NULL;
 121   return s->serialization;
 122 }
 123
 124
 125 /**
 126  * Create an entry for a file in a publish-structure.
 127  *
 128  * @param h handle to the file sharing subsystem
 129  * @param client_info initial value for the client-info value for this entry
 130  * @param filename name of the file or directory to publish
 131  * @param keywords under which keywords should this file be available
 132  *         directly; can be NULL
 133  * @param meta metadata for the file
 134  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
 135  *                GNUNET_SYSERR for simulation
 136  * @param anonymity what is the desired anonymity level for sharing?
 137  * @param priority what is the priority for OUR node to
 138  *   keep this file available?  Use 0 for maximum anonymity and
 139  *   minimum reliability...
 140  * @param expirationTime when should this content expire?
 141  * @return publish structure entry for the file
 142  */
 143 struct GNUNET_FS_FileInformation *
 144 GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
 145                                              void *client_info,
 146                                              const char *filename,
 147                                              const struct GNUNET_FS_Uri *keywords,
 148                                              const struct GNUNET_CONTAINER_MetaData *meta,
 149                                              int do_index,
 150                                              uint32_t anonymity,
 151                                              uint32_t priority,
 152                                              struct GNUNET_TIME_Absolute expirationTime)
 153 {
 154   struct FileInfo *fi;
 155   struct stat sbuf;
 156   struct GNUNET_FS_FileInformation *ret;
 157   const char *fn;
 158   const char *ss;
 159
 160   if (0 != STAT (filename, &sbuf))
 161     {
 162       GNUNET_log_strerror_file (GNUNET_ERROR_TYPE_WARNING,
 163                                 "stat",
 164                                 filename);
 165       return NULL;
 166     }
 167   fi = GNUNET_FS_make_file_reader_context_ (filename);
 168   if (fi == NULL)
 169     {
 170       GNUNET_break (0);
 171       return NULL;
 172     }
 173   ret = GNUNET_FS_file_information_create_from_reader (h,
 174                                                        client_info,
 175                                                        sbuf.st_size,
 176                                                        &GNUNET_FS_data_reader_file_,
 177                                                        fi,
 178                                                        keywords,
 179                                                        meta,
 180                                                        do_index,
 181                                                        anonymity,
 182                                                        priority,
 183                                                        expirationTime);
 184   if (ret == NULL)
 185     return NULL;
 186   ret->h = h;
 187   ret->filename = GNUNET_strdup (filename);
 188   fn = filename;
 189   while (NULL != (ss = strstr (fn,
 190                                DIR_SEPARATOR_STR)))
 191     fn = ss + 1;
 192   GNUNET_CONTAINER_meta_data_insert (ret->meta,
 193                                      "<gnunet>",
 194                                      EXTRACTOR_METATYPE_FILENAME,
 195                                      EXTRACTOR_METAFORMAT_C_STRING,
 196                                      "text/plain",
 197                                      fn,
 198                                      strlen (fn) + 1);
 199   return ret;
 200 }
 201
 202
 203 /**
 204  * Create an entry for a file in a publish-structure.
 205  *
 206  * @param h handle to the file sharing subsystem
 207  * @param client_info initial value for the client-info value for this entry
 208  * @param length length of the file
 209  * @param data data for the file (should not be used afterwards by
 210  *        the caller; callee will "free")
 211  * @param keywords under which keywords should this file be available
 212  *         directly; can be NULL
 213  * @param meta metadata for the file
 214  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
 215  *                GNUNET_SYSERR for simulation
 216  * @param anonymity what is the desired anonymity level for sharing?
 217  * @param priority what is the priority for OUR node to
 218  *   keep this file available?  Use 0 for maximum anonymity and
 219  *   minimum reliability...
 220  * @param expirationTime when should this content expire?
 221  * @return publish structure entry for the file
 222  */
 223 struct GNUNET_FS_FileInformation *
 224 GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
 225                                              void *client_info,
 226                                              uint64_t length,
 227                                              void *data,
 228                                              const struct GNUNET_FS_Uri *keywords,
 229                                              const struct GNUNET_CONTAINER_MetaData *meta,
 230                                              int do_index,
 231                                              uint32_t anonymity,
 232                                              uint32_t priority,
 233                                              struct GNUNET_TIME_Absolute expirationTime)
 234 {
 235   if (GNUNET_YES == do_index)
 236     {
 237       GNUNET_break (0);
 238       return NULL;
 239     }
 240   return GNUNET_FS_file_information_create_from_reader (h,
 241                                                         client_info,
 242                                                         length,
 243                                                         &GNUNET_FS_data_reader_copy_,
 244                                                         data,
 245                                                         keywords,
 246                                                         meta,
 247                                                         do_index,
 248                                                         anonymity,
 249                                                         priority,
 250                                                         expirationTime);
 251 }
 252
 253
 254 /**
 255  * Create an entry for a file in a publish-structure.
 256  *
 257  * @param h handle to the file sharing subsystem
 258  * @param client_info initial value for the client-info value for this entry
 259  * @param length length of the file
 260  * @param reader function that can be used to obtain the data for the file
 261  * @param reader_cls closure for "reader"
 262  * @param keywords under which keywords should this file be available
 263  *         directly; can be NULL
 264  * @param meta metadata for the file
 265  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
 266  *                GNUNET_SYSERR for simulation
 267  * @param anonymity what is the desired anonymity level for sharing?
 268  * @param priority what is the priority for OUR node to
 269  *   keep this file available?  Use 0 for maximum anonymity and
 270  *   minimum reliability...
 271  * @param expirationTime when should this content expire?
 272  * @return publish structure entry for the file
 273  */
 274 struct GNUNET_FS_FileInformation *
 275 GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
 276                                                void *client_info,
 277                                                uint64_t length,
 278                                                GNUNET_FS_DataReader reader,
 279                                                void *reader_cls,
 280                                                const struct GNUNET_FS_Uri *keywords,
 281                                                const struct GNUNET_CONTAINER_MetaData *meta,
 282                                                int do_index,
 283                                                uint32_t anonymity,
 284                                                uint32_t priority,
 285                                                struct GNUNET_TIME_Absolute expirationTime)
 286 {
 287   struct GNUNET_FS_FileInformation *ret;
 288
 289   if ( (GNUNET_YES == do_index) &&
 290        (reader != &GNUNET_FS_data_reader_file_) )
 291     {
 292       GNUNET_break (0);
 293       return NULL;
 294     }
 295   ret = GNUNET_malloc (sizeof (struct GNUNET_FS_FileInformation));
 296   ret->h = h;
 297   ret->client_info = client_info;
 298   ret->meta = GNUNET_CONTAINER_meta_data_duplicate (meta);
 299   if (ret->meta == NULL)
 300     ret->meta = GNUNET_CONTAINER_meta_data_create ();
 301   ret->keywords = (keywords == NULL) ? NULL : GNUNET_FS_uri_dup (keywords);
 302   ret->expirationTime = expirationTime;
 303   ret->data.file.reader = reader;
 304   ret->data.file.reader_cls = reader_cls;
 305   ret->data.file.do_index = do_index;
 306   ret->data.file.file_size = length;
 307   ret->anonymity = anonymity;
 308   ret->priority = priority;
 309   return ret;
 310 }
 311
 312
 313 /**
 314  * Closure for "dir_scan_cb".
 315  */
 316 struct DirScanCls
 317 {
 318   /**
 319    * Metadata extractors to use.
 320    */
 321   struct EXTRACTOR_PluginList *extractors;
 322
 323   /**
 324    * Master context.
 325    */
 326   struct GNUNET_FS_Handle *h;
 327
 328   /**
 329    * Function to call on each directory entry.
 330    */
 331   GNUNET_FS_FileProcessor proc;
 332
 333   /**
 334    * Closure for proc.
 335    */
 336   void *proc_cls;
 337
 338   /**
 339    * Scanner to use for subdirectories.
 340    */
 341   GNUNET_FS_DirectoryScanner scanner;
 342
 343   /**
 344    * Closure for scanner.
 345    */
 346   void *scanner_cls;
 347
 348   /**
 349    * Set to an error message (if any).
 350    */
 351   char *emsg;
 352
 353   /**
 354    * Should files be indexed?
 355    */
 356   int do_index;
 357
 358   /**
 359    * Desired anonymity level.
 360    */
 361   uint32_t anonymity;
 362
 363   /**
 364    * Desired publishing priority.
 365    */
 366   uint32_t priority;
 367
 368   /**
 369    * Expiration time for publication.
 370    */
 371   struct GNUNET_TIME_Absolute expiration;
 372 };
 373
 374
 375 /**
 376  * Function called on each entry in a file to
 377  * cause default-publishing.
 378  * @param cls closure (struct DirScanCls)
 379  * @param filename name of the file to be published
 380  * @return GNUNET_OK on success, GNUNET_SYSERR to abort
 381  */
 382 static int
 383 dir_scan_cb (void *cls,
 384              const char *filename)
 385 {
 386   struct DirScanCls *dsc = cls;
 387   struct stat sbuf;
 388   struct GNUNET_FS_FileInformation *fi;
 389   struct GNUNET_FS_Uri *ksk_uri;
 390   struct GNUNET_FS_Uri *keywords;
 391   struct GNUNET_CONTAINER_MetaData *meta;
 392
 393   if (0 != STAT (filename, &sbuf))
 394     {
 395       GNUNET_asprintf (&dsc->emsg,
 396                        _("`%s' failed on file `%s': %s"),
 397                        "stat",
 398                        filename,
 399                        STRERROR (errno));
 400       return GNUNET_SYSERR;
 401     }
 402   if (S_ISDIR (sbuf.st_mode))
 403     {
 404       fi = GNUNET_FS_file_information_create_from_directory (dsc->h,
 405                                                              NULL,
 406                                                              filename,
 407                                                              dsc->scanner,
 408                                                              dsc->scanner_cls,
 409                                                              dsc->do_index,
 410                                                              dsc->anonymity,
 411                                                              dsc->priority,
 412                                                              dsc->expiration,
 413                                                              &dsc->emsg);
 414       if (NULL == fi)
 415         {
 416           GNUNET_assert (NULL != dsc->emsg);
 417           return GNUNET_SYSERR;
 418         }
 419     }
 420   else
 421     {
 422       meta = GNUNET_CONTAINER_meta_data_create ();
 423       GNUNET_FS_meta_data_extract_from_file (meta,
 424                                              filename,
 425                                              dsc->extractors);
 426       // FIXME: remove path from filename in metadata!
 427       keywords = GNUNET_FS_uri_ksk_create_from_meta_data (meta);
 428       ksk_uri = GNUNET_FS_uri_ksk_canonicalize (keywords);
 429       fi = GNUNET_FS_file_information_create_from_file (dsc->h,
 430                                                         NULL,
 431                                                         filename,
 432                                                         ksk_uri,
 433                                                         meta,
 434                                                         dsc->do_index,
 435                                                         dsc->anonymity,
 436                                                         dsc->priority,
 437                                                         dsc->expiration);
 438       GNUNET_CONTAINER_meta_data_destroy (meta);
 439       GNUNET_FS_uri_destroy (keywords);
 440       GNUNET_FS_uri_destroy (ksk_uri);
 441     }
 442   dsc->proc (dsc->proc_cls,
 443              filename,
 444              fi);
 445   return GNUNET_OK;
 446 }
 447
 448
 449 /**
 450  * Simple, useful default implementation of a directory scanner
 451  * (GNUNET_FS_DirectoryScanner).  This implementation expects to get a
 452  * UNIX filename, will publish all files in the directory except hidden
 453  * files (those starting with a ".").  Metadata will be extracted
 454  * using GNU libextractor; the specific list of plugins should be
 455  * specified in "cls", passing NULL will disable (!)  metadata
 456  * extraction.  Keywords will be derived from the metadata and be
 457  * subject to default canonicalization.  This is strictly a
 458  * convenience function.
 459  *
 460  * @param cls must be of type "struct EXTRACTOR_Extractor*"
 461  * @param h handle to the file sharing subsystem
 462  * @param dirname name of the directory to scan
 463  * @param do_index should files be indexed or inserted
 464  * @param anonymity desired anonymity level
 465  * @param priority priority for publishing
 466  * @param expirationTime expiration for publication
 467  * @param proc function called on each entry
 468  * @param proc_cls closure for proc
 469  * @param emsg where to store an error message (on errors)
 470  * @return GNUNET_OK on success
 471  */
 472 int
 473 GNUNET_FS_directory_scanner_default (void *cls,
 474                                      struct GNUNET_FS_Handle *h,
 475                                      const char *dirname,
 476                                      int do_index,
 477                                      uint32_t anonymity,
 478                                      uint32_t priority,
 479                                      struct GNUNET_TIME_Absolute expirationTime,
 480                                      GNUNET_FS_FileProcessor proc,
 481                                      void *proc_cls,
 482                                      char **emsg)
 483 {
 484   struct EXTRACTOR_PluginList *ex = cls;
 485   struct DirScanCls dsc;
 486
 487   dsc.h = h;
 488   dsc.extractors = ex;
 489   dsc.proc = proc;
 490   dsc.proc_cls = proc_cls;
 491   dsc.scanner = &GNUNET_FS_directory_scanner_default;
 492   dsc.scanner_cls = cls;
 493   dsc.do_index = do_index;
 494   dsc.anonymity = anonymity;
 495   dsc.priority = priority;
 496   dsc.expiration = expirationTime;
 497   if (-1 == GNUNET_DISK_directory_scan (dirname,
 498                                         &dir_scan_cb,
 499                                         &dsc))
 500     {
 501       GNUNET_assert (NULL != dsc.emsg);
 502       *emsg = dsc.emsg;
 503       return GNUNET_SYSERR;
 504     }
 505   return GNUNET_OK;
 506 }
 507
 508
 509 /**
 510  * Closure for dirproc function.
 511  */
 512 struct EntryProcCls
 513 {
 514   /**
 515    * Linked list of directory entries that is being
 516    * created.
 517    */
 518   struct GNUNET_FS_FileInformation *entries;
 519
 520 };
 521
 522
 523 /**
 524  * Function that processes a directory entry that
 525  * was obtained from the scanner.
 526  * @param cls our closure
 527  * @param filename name of the file (unused, why there???)
 528  * @param fi information for publishing the file
 529  */
 530 static void
 531 dirproc (void *cls,
 532          const char *filename,
 533          struct GNUNET_FS_FileInformation *fi)
 534 {
 535   struct EntryProcCls *dc = cls;
 536
 537   GNUNET_assert (fi->next == NULL);
 538   GNUNET_assert (fi->dir == NULL);
 539   fi->next = dc->entries;
 540   dc->entries = fi;
 541 }
 542
 543
 544 /**
 545  * Create a publish-structure from an existing file hierarchy, inferring
 546  * and organizing keywords and metadata as much as possible.  This
 547  * function primarily performs the recursive build and re-organizes
 548  * keywords and metadata; for automatically getting metadata
 549  * extraction, scanning of directories and creation of the respective
 550  * GNUNET_FS_FileInformation entries the default scanner should be
 551  * passed (GNUNET_FS_directory_scanner_default).  This is strictly a
 552  * convenience function.
 553  *
 554  * @param h handle to the file sharing subsystem
 555  * @param client_info initial value for the client-info value for this entry
 556  * @param filename name of the top-level file or directory
 557  * @param scanner function used to get a list of files in a directory
 558  * @param scanner_cls closure for scanner
 559  * @param do_index should files in the hierarchy be indexed?
 560  * @param anonymity what is the desired anonymity level for sharing?
 561  * @param priority what is the priority for OUR node to
 562  *   keep this file available?  Use 0 for maximum anonymity and
 563  *   minimum reliability...
 564  * @param expirationTime when should this content expire?
 565  * @param emsg where to store an error message
 566  * @return publish structure entry for the directory, NULL on error
 567  */
 568 struct GNUNET_FS_FileInformation *
 569 GNUNET_FS_file_information_create_from_directory (struct GNUNET_FS_Handle *h,
 570                                                   void *client_info,
 571                                                   const char *filename,
 572                                                   GNUNET_FS_DirectoryScanner scanner,
 573                                                   void *scanner_cls,
 574                                                   int do_index,
 575                                                   uint32_t anonymity,
 576                                                   uint32_t priority,
 577                                                   struct GNUNET_TIME_Absolute expirationTime,
 578                                                   char **emsg)
 579 {
 580   struct GNUNET_FS_FileInformation *ret;
 581   struct EntryProcCls dc;
 582   struct GNUNET_FS_Uri *ksk;
 583   struct GNUNET_CONTAINER_MetaData *meta;
 584   const char *fn;
 585   const char *ss;
 586
 587   dc.entries = NULL;
 588   meta = GNUNET_CONTAINER_meta_data_create ();
 589   GNUNET_FS_meta_data_make_directory (meta);
 590   scanner (scanner_cls,
 591            h,
 592            filename,
 593            do_index,
 594            anonymity,
 595            priority,
 596            expirationTime,
 597            &dirproc,
 598            &dc,
 599            emsg);
 600   ksk = NULL; // FIXME...
 601   // FIXME: create meta!
 602   ret = GNUNET_FS_file_information_create_empty_directory (h,
 603                                                            client_info,
 604                                                            ksk,
 605                                                            meta,
 606                                                            anonymity,
 607                                                            priority,
 608                                                            expirationTime);
 609   GNUNET_CONTAINER_meta_data_destroy (meta);
 610   ret->data.dir.entries = dc.entries;
 611   while (dc.entries != NULL)
 612     {
 613       dc.entries->dir = ret;
 614       dc.entries = dc.entries->next;
 615     }
 616   fn = filename;
 617   while ( (NULL != (ss = strstr (fn,
 618                                  DIR_SEPARATOR_STR))) &&
 619           (strlen (ss) > 1) )
 620     fn = ss + 1;
 621   GNUNET_CONTAINER_meta_data_insert (ret->meta,
 622                                      "<gnunet>",
 623                                      EXTRACTOR_METATYPE_FILENAME,
 624                                      EXTRACTOR_METAFORMAT_C_STRING,
 625                                      "text/plain",
 626                                      fn,
 627                                      strlen (fn) + 1);
 628   ret->filename = GNUNET_strdup (filename);
 629   return ret;
 630 }
 631
 632
 633 /**
 634  * Test if a given entry represents a directory.
 635  *
 636  * @param ent check if this FI represents a directory
 637  * @return GNUNET_YES if so, GNUNET_NO if not
 638  */
 639 int
 640 GNUNET_FS_file_information_is_directory (struct GNUNET_FS_FileInformation *ent)
 641 {
 642   return ent->is_directory;
 643 }
 644
 645
 646 /**
 647  * Create an entry for an empty directory in a publish-structure.
 648  * This function should be used by applications for which the
 649  * use of "GNUNET_FS_file_information_create_from_directory"
 650  * is not appropriate.
 651  *
 652  * @param h handle to the file sharing subsystem
 653  * @param client_info initial value for the client-info value for this entry
 654  * @param meta metadata for the directory
 655  * @param keywords under which keywords should this directory be available
 656  *         directly; can be NULL
 657  * @param anonymity what is the desired anonymity level for sharing?
 658  * @param priority what is the priority for OUR node to
 659  *   keep this file available?  Use 0 for maximum anonymity and
 660  *   minimum reliability...
 661  * @param expirationTime when should this content expire?
 662  * @return publish structure entry for the directory , NULL on error
 663  */
 664 struct GNUNET_FS_FileInformation *
 665 GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
 666                                                    void *client_info,
 667                                                    const struct GNUNET_FS_Uri *keywords,
 668                                                    const struct GNUNET_CONTAINER_MetaData *meta,
 669                                                    uint32_t anonymity,
 670                                                    uint32_t priority,
 671                                                    struct GNUNET_TIME_Absolute expirationTime)
 672 {
 673   struct GNUNET_FS_FileInformation *ret;
 674
 675   ret = GNUNET_malloc (sizeof (struct GNUNET_FS_FileInformation));
 676   ret->h = h;
 677   ret->client_info = client_info;
 678   ret->meta = GNUNET_CONTAINER_meta_data_duplicate (meta);
 679   ret->keywords = GNUNET_FS_uri_dup (keywords);
 680   ret->expirationTime = expirationTime;
 681   ret->is_directory = GNUNET_YES;
 682   ret->anonymity = anonymity;
 683   ret->priority = priority;
 684   return ret;
 685 }
 686
 687
 688 /**
 689  * Add an entry to a directory in a publish-structure.  Clients
 690  * should never modify publish structures that were passed to
 691  * "GNUNET_FS_publish_start" already.
 692  *
 693  * @param dir the directory
 694  * @param ent the entry to add; the entry must not have been
 695  *            added to any other directory at this point and
 696  *            must not include "dir" in its structure
 697  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 698  */
 699 int
 700 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
 701                                 struct GNUNET_FS_FileInformation *ent)
 702 {
 703   if ( (ent->dir != NULL) ||
 704        (ent->next != NULL) ||
 705        (! dir->is_directory) )
 706     {
 707       GNUNET_break (0);
 708       return GNUNET_SYSERR;
 709     }
 710   ent->dir = dir;
 711   ent->next = dir->data.dir.entries;
 712   dir->data.dir.entries = ent;
 713   dir->data.dir.dir_size = 0;
 714   return GNUNET_OK;
 715 }
 716
 717
 718 /**
 719  * Inspect a file or directory in a publish-structure.  Clients
 720  * should never modify publish structures that were passed to
 721  * "GNUNET_FS_publish_start" already.  When called on a directory,
 722  * this function will FIRST call "proc" with information about
 723  * the directory itself and then for each of the files in the
 724  * directory (but not for files in subdirectories).  When called
 725  * on a file, "proc" will be called exactly once (with information
 726  * about the specific file).
 727  *
 728  * @param dir the directory
 729  * @param proc function to call on each entry
 730  * @param proc_cls closure for proc
 731  */
 732 void
 733 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
 734                                     GNUNET_FS_FileInformationProcessor proc,
 735                                     void *proc_cls)
 736 {
 737   struct GNUNET_FS_FileInformation *pos;
 738   int no;
 739
 740   no = GNUNET_NO;
 741   if (GNUNET_OK !=
 742       proc (proc_cls,
 743             dir,
 744             (dir->is_directory) ? dir->data.dir.dir_size : dir->data.file.file_size,
 745             dir->meta,
 746             &dir->keywords,
 747             &dir->anonymity,
 748             &dir->priority,
 749             (dir->is_directory) ? &no : &dir->data.file.do_index,
 750             &dir->expirationTime,
 751             &dir->client_info))
 752     return;
 753   if (! dir->is_directory)
 754     return;
 755   pos = dir->data.dir.entries;
 756   while (pos != NULL)
 757     {
 758       no = GNUNET_NO;
 759       if (GNUNET_OK !=
 760           proc (proc_cls,
 761                 pos,
 762                 (pos->is_directory) ? pos->data.dir.dir_size : pos->data.file.file_size,
 763                 pos->meta,
 764                 &pos->keywords,
 765                 &pos->anonymity,
 766                 &pos->priority,
 767                 (dir->is_directory) ? &no : &dir->data.file.do_index,
 768                 &pos->expirationTime,
 769                 &pos->client_info))
 770         break;
 771       pos = pos->next;
 772     }
 773 }
 774
 775
 776 /**
 777  * Destroy publish-structure.  Clients should never destroy publish
 778  * structures that were passed to "GNUNET_FS_publish_start" already.
 779  *
 780  * @param fi structure to destroy
 781  * @param cleaner function to call on each entry in the structure
 782  *        (useful to clean up client_info); can be NULL; return
 783  *        values are ignored
 784  * @param cleaner_cls closure for cleaner
 785  */
 786 void
 787 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
 788                                     GNUNET_FS_FileInformationProcessor cleaner,
 789                                     void *cleaner_cls)
 790 {
 791   struct GNUNET_FS_FileInformation *pos;
 792   int no;
 793
 794   no = GNUNET_NO;
 795   if (fi->is_directory)
 796     {
 797       /* clean up directory */
 798       while (NULL != (pos = fi->data.dir.entries))
 799         {
 800           fi->data.dir.entries = pos->next;
 801           GNUNET_FS_file_information_destroy (pos, cleaner, cleaner_cls);
 802         }
 803       /* clean up client-info */
 804       if (NULL != cleaner)
 805         cleaner (cleaner_cls,
 806                  fi,
 807                  fi->data.dir.dir_size,
 808                  fi->meta,
 809                  &fi->keywords,
 810                  &fi->anonymity,
 811                  &fi->priority,
 812                  &no,
 813                  &fi->expirationTime,
 814                  &fi->client_info);
 815       GNUNET_free_non_null (fi->data.dir.dir_data);
 816     }
 817   else
 818     {
 819       /* call clean-up function of the reader */
 820       if (fi->data.file.reader != NULL)
 821         fi->data.file.reader (fi->data.file.reader_cls, 0, 0,
 822                               NULL, NULL);
 823       /* clean up client-info */
 824       if (NULL != cleaner)
 825         cleaner (cleaner_cls,
 826                  fi,
 827                  fi->data.file.file_size,
 828                  fi->meta,
 829                  &fi->keywords,
 830                  &fi->anonymity,
 831                  &fi->priority,
 832                  &fi->data.file.do_index,
 833                  &fi->expirationTime,
 834                  &fi->client_info);
 835     }
 836   GNUNET_free_non_null (fi->filename);
 837   GNUNET_free_non_null (fi->emsg);
 838   GNUNET_free_non_null (fi->chk_uri);
 839   /* clean up serialization */
 840   if ( (NULL != fi->serialization) &&
 841        (0 != UNLINK (fi->serialization)) )
 842     GNUNET_log_strerror_file (GNUNET_ERROR_TYPE_WARNING,
 843                               "unlink",
 844                               fi->serialization);
 845   if (NULL != fi->keywords)
 846     GNUNET_FS_uri_destroy (fi->keywords);
 847   if (NULL != fi->meta)
 848     GNUNET_CONTAINER_meta_data_destroy (fi->meta);
 849   GNUNET_free_non_null (fi->serialization);
 850   if (fi->te != NULL)
 851     {
 852       GNUNET_FS_tree_encoder_finish (fi->te,
 853                                      NULL, NULL);
 854       fi->te = NULL;
 855     }
 856   GNUNET_free (fi);
 857 }
 858
 859
 860 /* end of fs_file_information.c */