/*  Tux Commander VFS: Filelist tree storage
 *  Copyright (C) 2007-2009 Tomas Bzatek <tbzatek@users.sourceforge.net>
 *   Check for updates on tuxcmd.sourceforge.net
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef __TREEPATHUTILS_H__
#define __TREEPATHUTILS_H__

#ifdef __cplusplus
  extern "C" {
#endif


#include <glib.h>
#include "tuxcmd-vfs.h"


/****
 *  USAGE / RULES:
 *
 *   1. create new tree, add items one by one with filelist_tree_add_item(), found during first archive listing
 *   2. optionally call filelist_tree_resolve_symlinks()
 *   3. when mapping a file back, use filelist_find_original_index_by_path() or filelist_tree_find_node_by_path()
 *      and take the particular attribute (original_XXX) as a reference to match the archive records against.
 *
 *
 *   - don't set the FName and FDisplayName values, filelist functions set these dynamically
 *     when traversing tree during adding.
 *
 *   - due to the previous fact, the FDisplayName string is taken from original path, making
 *     sure it's valid UTF-8. No way to have different display name than the file name.
 *
 *   - it's important to set either 'original_index' or 'original_pathstr' value, to match
 *     exact file back in the archive during VFSCopyToLocal operation. These attributes are
 *     left untouched by filelist functions.
 *
 *   - all returned values are constants, do not modify anything (except of the item data itself).
 *
 *   - the 'symlink_target_data' member is just a pointer to an existing data, don't free it.
 *
 *   - the single 'node' and 'tree' objects are virtually equal, linked together. It may lead
 *     to a slight confusion.
 *
 */


#define FILELIST_MAX_SYMLINK_DEPTH  20   /*  do not go deeper than 20 levels  */


struct PathTree {
  GPtrArray *        items;
  struct TVFSItem *  data;
  struct TVFSItem *  symlink_target_data;
  unsigned long int  original_index;     /*  original index as stored in the archive, for matching back  */
  char *             node;
  char *             original_pathstr;   /*  original path as stored in the archive, for matching back  */
};


struct PathTree *   filelist_tree_new ();
void                filelist_tree_free (struct PathTree *tree);

/*  Convenient function to print whole tree, for debugging purposes.  */
void                filelist_tree_print (struct PathTree *tree);

/*  Add item into the particular structure under the 'path' node. This function tries to find the right node
 *  and creates placeholder nodes in between, when a part of the directory structure is missing.
 */
gboolean            filelist_tree_add_item (struct PathTree *tree, const char *path, struct TVFSItem *item, const char *original_pathstr, unsigned long int original_index);

struct PathTree *   filelist_tree_find_node_by_path (struct PathTree *tree, const char *path);
unsigned long int   filelist_find_original_index_by_path (struct PathTree *tree, const char *path);

void                filelist_tree_resolve_symlinks (struct PathTree *tree);

/*  Find the n-th item inside one node, the 'index' argument is absolute position in the list.
 *  Don't confuse with 'original_index' member. Used in vfs_filelist_list_next().
 */
struct PathTree *   filelist_tree_get_item_by_index (struct PathTree *tree, unsigned long int index);


#ifdef __cplusplus
  }
#endif
#endif /* __TREEPATHUTILS_H__ */