libisofs/src/libisofs.h

202 lines
5.9 KiB
C

/*
* Copyright (c) 2007 Vreixo Formoso
*
* This file is part of the libisofs project; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation. See COPYING file for details.
*/
#ifndef LIBISO_LIBISOFS_H_
#define LIBISO_LIBISOFS_H_
#include <sys/stat.h>
typedef struct Iso_Node IsoNode;
typedef struct Iso_Dir IsoDir;
typedef struct Iso_Symlink IsoSymlink;
typedef struct Iso_Dir_Iter IsoDirIter;
/**
* Increments the reference counting of the given node.
*/
void iso_node_ref(IsoNode *node);
/**
* Decrements the reference couting of the given node.
* If it reach 0, the node is free, and, if the node is a directory,
* its children will be unref() too.
*/
void iso_node_unref(IsoNode *node);
/**
* Set the name of a node.
*
* @param name The name in UTF-8 encoding
*/
void iso_node_set_name(IsoNode *node, const char *name);
/**
* Get the name of a node (in UTF-8).
* The returned string belongs to the node and should not be modified nor
* freed. Use strdup if you really need your own copy.
*/
const char *iso_node_get_name(const IsoNode *node);
/**
* Set the permissions for the node. This attribute is only useful when
* Rock Ridge extensions are enabled.
*
* @param mode
* bitmask with the permissions of the node, as specified in 'man 2 stat'.
* The file type bitfields will be ignored, only file permissions will be
* modified.
*/
void iso_node_set_permissions(IsoNode *node, mode_t mode);
/**
* Get the permissions for the node
*/
mode_t iso_node_get_permissions(const IsoNode *node);
/**
* Get the mode of the node, both permissions and file type, as specified in
* 'man 2 stat'.
*/
mode_t iso_node_get_mode(const IsoNode *node);
/**
* Set the user id for the node. This attribute is only useful when
* Rock Ridge extensions are enabled.
*/
void iso_node_set_uid(IsoNode *node, uid_t uid);
/**
* Get the user id of the node.
*/
uid_t iso_node_get_uid(const IsoNode *node);
/**
* Set the group id for the node. This attribute is only useful when
* Rock Ridge extensions are enabled.
*/
void iso_node_set_gid(IsoNode *node, gid_t gid);
/**
* Get the group id of the node.
*/
gid_t iso_node_get_gid(const IsoNode *node);
/**
* Add a new node to a dir. Note that this function don't add a new ref to
* the node, so you don't need to free it, it will be automatically freed
* when the dir is deleted. Of course, if you want to keep using the node
* after the dir life, you need to iso_node_ref() it.
*
* @param dir
* the dir where to add the node
* @param child
* the node to add. You must ensure that the node hasn't previously added
* to other dir, and that the node name is unique inside the child.
* Otherwise this function will return a failure, and the child won't be
* inserted.
* @return
* number of nodes in dir if succes, < 0 otherwise
* Possible errors:
* ISO_NULL_POINTER, if dir or child are NULL
* ISO_NODE_ALREADY_ADDED, if child is already added to other dir
* ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
* ISO_WRONG_ARG_VALUE, if child == dir
*/
int iso_dir_add_node(IsoDir *dir, IsoNode *child);
/**
* Locate a node inside a given dir.
*
* @param name
* The name of the node
* @param node
* Location for a pointer to the node, it will filled with NULL if the dir
* doesn't have a child with the given name.
* The node will be owned by the dir and shouldn't be unref(). Just call
* iso_node_ref() to get your own reference to the node.
* @return
* 1 node found, 0 child has no such node, < 0 error
* Possible errors:
* ISO_NULL_POINTER, if dir, node or name are NULL
*/
int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node);
/**
* Get the number of children of a directory.
*
* @return
* >= 0 number of items, < 0 error
* Possible errors:
* ISO_NULL_POINTER, if dir is NULL
*/
int iso_dir_get_nchildren(IsoDir *dir);
/**
* Get an iterator for the children of the given dir.
*
* You can iterate over the children with iso_dir_iter_next. When finished,
* you should free the iterator with iso_dir_iter_free.
* You musn't delete a child of the same dir, using iso_node_take() or
* iso_node_remove(), while you're using the iterator. You can use
* iso_node_take_iter() or iso_node_remove_iter() instead.
*
* You can use the iterator in the way like this
*
* IsoDirIter *iter;
* IsoNode *node;
* if ( iso_dir_get_children(dir, &iter) != 1 ) {
* // handle error
* }
* while ( iso_dir_iter_next(iter, &node) == 1 ) {
* // do something with the child
* }
* iso_dir_iter_free(iter);
*
* An iterator is intended to be used in a single iteration over the
* children of a dir. Thus, it should be treated as a temporary object,
* and free as soon as possible.
*
* @return
* 1 success, < 0 error
* Possible errors:
* ISO_NULL_POINTER, if dir or iter are NULL
* ISO_OUT_OF_MEM
*/
int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter);
/**
* Get the next child.
* Take care that the node is owned by its parent, and will be unref() when
* the parent is freed. If you want your own ref to it, call iso_node_ref()
* on it.
*
* @return
* 1 success, 0 if dir has no more elements, < 0 error
* Possible errors:
* ISO_NULL_POINTER, if node or iter are NULL
* ISO_ERROR, on wrong iter usage, usual caused by modiying the
* dir during iteration
*/
int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node);
/**
* Check if there're more children.
*
* @return
* 1 dir has more elements, 0 no, < 0 error
* Possible errors:
* ISO_NULL_POINTER, if iter is NULL
*/
int iso_dir_iter_has_next(IsoDirIter *iter);
/**
* Free a dir iterator.
*/
void iso_dir_iter_free(IsoDirIter *iter);
#endif /*LIBISO_LIBISOFS_H_*/