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