cole Library Reference Manual
Prev |  | Next

# API

## Name

API -- Public cole API for the present release.

## Synopsis

    #include <cole/cole.h>

    #define     COLE_MAJOR_VERSION
    #define     COLE_MINOR_VERSION
    #define     COLE_MICRO_VERSION
    extern      int cole_major_version;
    extern      int cole_minor_version;
    extern      int cole_micro_version;
    extern      char *cole_version;
    extern      char *cole_host_info;
    enum        COLERRNO;
    void        cole_perror                     (const char *s,
                                                 COLERRNO colerrno);
    struct      COLEFS;
    struct      COLEDIR;
    struct      COLEDIRENT;
    struct      COLEFILE;
    COLEFS*     cole_mount                      (char *filename,
                                                 COLERRNO *colerrno);
    int         cole_umount                     (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);
    int         cole_print_tree                 (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);
    int         cole_locate_filename            (COLEFS *colefilesystem,
                                                 char *filename,
                                                 void *info,
                                                 COLE_LOCATE_ACTION_FUNC *action,
                                                 COLERRNO *colerrno);
    int         cole_recurse_tree               (COLEFS *colefilesystem,
                                                 void *info,
                                                 COLE_RECURSE_DIR_FUNC *inroot,
                                                 COLE_RECURSE_DIRENT_FUNC *indirentry,
                                                 COLE_RECURSE_DIR_FUNC *indir,
                                                 COLE_RECURSE_DIR_FUNC *outdir,
                                                 COLE_RECURSE_VISIT_DIR_FUNC *visitdir,
                                                 COLERRNO *colerrno);
    COLEFILE*   cole_fopen                      (COLEFS *colefilesystem,
                                                 char *filename,
                                                 COLERRNO *colerrno);
    COLEFILE*   cole_fopen_direntry             (COLEDIRENT *coledirentry,
                                                 COLERRNO *colerrno);
    int         cole_fclose                     (COLEFILE *colefile,
                                                 COLERRNO *colerrno);
    size_t      cole_fread                      (COLEFILE *colefile,
                                                 void *ptr,
                                                 size_t size,
                                                 COLERRNO *colerrno);
    int         cole_feof                       (COLEFILE *colefile);
    size_t      cole_fsize                      (COLEFILE *colefile);
    size_t      cole_ftell                      (COLEFILE *colefile);
    int         cole_fseek                      (COLEFILE *colefile,
                                                 size_t delta,
                                                 COLE_SEEK_FLAG direction,
                                                 COLERRNO *colerrno);
    int         cole_frewind                    (COLEFILE *colefile,
                                                 COLERRNO *colerrno);
    COLEDIR*    cole_opendir_rootdir            (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);
    COLEDIR*    cole_opendir_direntry           (COLEDIRENT *coledirentry,
                                                 COLERRNO *colerrno);
    int         cole_closedir                   (COLEDIR *coledir,
                                                 COLERRNO *colerrno);
    COLEDIRENT* cole_visiteddirentry            (COLEDIR *coledir);
    COLEDIRENT* cole_nextdirentry               (COLEDIR *coledir);
    int         cole_direntry_isdir             (COLEDIRENT *coledirentry);
    int         cole_direntry_isfile            (COLEDIRENT *coledirentry);
    char*       cole_dir_getname                (COLEDIR *coledir);
    size_t      cole_dir_getsize                (COLEDIR *coledir);
    long        cole_dir_getsec1                (COLEDIR *coledir);
    long        cole_dir_getsec2                (COLEDIR *coledir);
    long        cole_dir_getdays1               (COLEDIR *coledir);
    long        cole_dir_getdays2               (COLEDIR *coledir);
    char*       cole_direntry_getname           (COLEDIRENT *coledirentry);
    size_t      cole_direntry_getsize           (COLEDIRENT *coledirentry);
    long        cole_direntry_getdays1          (COLEDIRENT *coledirentry);
    long        cole_direntry_getsec1           (COLEDIRENT *coledirentry);
    long        cole_direntry_getdays2          (COLEDIRENT *coledirentry);
    long        cole_direntry_getsec2           (COLEDIRENT *coledirentry);

## Description

Note: The separator character for filename components is '/'. So, a filename argument can be something like "/Macros/VB/Project1".

## Details

### COLE_MAJOR_VERSION

    #define COLE_MAJOR_VERSION 2

### COLE_MINOR_VERSION

    #define COLE_MINOR_VERSION 0

### COLE_MICRO_VERSION

    #define COLE_MICRO_VERSION 1

### cole_major_version

    extern int cole_major_version;

### cole_minor_version

    extern int cole_minor_version;

### cole_micro_version

    extern int cole_micro_version;

### cole_version

    extern char *cole_version;

### cole_host_info

    extern char *cole_host_info;

### enum COLERRNO

    enum COLERRNO {
    /* & = means that you can use perror(3) call to print an error message */
    /* you can always use cole_perror to print an error message */
    	COLE_EFIRST,		/* Leave this at first place */
    /*&*/	COLE_EMEMORY,		/* Failed malloc(3) or realloc(3) */
    /*&*/	COLE_EOPENFILE,		/* Failed fopen(3) */
    /*&*/	COLE_ECLOSEFILE,	/* Failed fclose(3) */
    /*&*/	COLE_EREAD,		/* Failed fread(3) */
    /*&*/	COLE_EWRITE,		/* Failed fwrite(3) */
    /*&*/	COLE_EREMOVE,		/* Failed remove(3) */
    /*&*/	COLE_ETMPNAM,		/* Failed tmpnam(3) */
    /*&*/	COLE_ESEEK,		/* Failed fseek(3) */
    /*&*/	COLE_EERRNO,		/* Some system call failed */
    	COLE_ENOFILESYSTEM,	/* File is not a filesystem */
    	COLE_EINVALIDFILESYSTEM,/* Filesystem is broken, it's invalid */
    	COLE_EISNOTDIR,		/* Directory entry is not a directory */
    	COLE_EISNOTFILE,	/* Directory entry is not a file */
    	COLE_EFILENOTFOUND,	/* Doesn't exist a file with the given name */
    	COLE_EOF,		/* End of file has been reached */
    	COLE_EMEMBERISNOTDIR,	/* A member of the filename is not
    				   a directory */
    	COLE_EBROKENFILENAME,	/* The filename is not right written */
    	COLE_EFILENAMEISNOTFILE,/* Filename is not a file */
    	COLE_EFSEEKDELTA,	/* Delta argument is not valid */
    	COLE_EFSEEKFLAG,	/* Flag argument is not valid */
    	COLE_EUNKNOWN,		/* An unknown error ocurred, can be a bug */
    	COLE_ELAST		/* Leave this at last place */
    };

### cole_perror ()

    void        cole_perror                     (const char *s,
                                                 COLERRNO colerrno);

Prints a message on the standard error output, describing the error `colerrno`, preceding it with the string `s`, a semicolon and a space. It handles COLE_EERRNO value too, calling perror(3).

`s` : | string to print before the error message. It can be NULL.
`colerrno` : | error value of which a message will be printed.

### struct COLEFS

    struct COLEFS {
    	/* This structure is for internal use only, not for the public API */
    	pps_entry *tree;
    	U32 root;			/* entry root, root pps_entry */
    	U8 *BDepot;
    	U8 *SDepot;
    	FILE *sbfile;
    	char *sbfilename;
    	FILE *file;			/* actual file (the filesystem) */
    };

### struct COLEDIR

    struct COLEDIR {
    	/* This structure is for internal use only, not for the public API */
    	U32 entry;
    	struct _COLEDIRENT visited_entry;
    	struct _COLEFS *fs;		/* father */
    };

### struct COLEDIRENT

    struct COLEDIRENT {
    	/* This structure is for internal use only, not for the public API */
    	U32 entry;
    	struct _COLEDIR *dir;		/* father */
    };

### struct COLEFILE

    struct COLEFILE {
    	/* This structure is for internal use only, not for the public API */
    	U32 entry;
    	FILE *file;			/* actual extracted file */
    	char *filename;			/* actual extracted file's name */
    	U32 filesize;			/* actual extracted file size */
    	struct _COLEFS *fs;		/* father */
    	U32 pos;			/* file pointer position */
    };

### cole_mount ()

    COLEFS*     cole_mount                      (char *filename,
                                                 COLERRNO *colerrno);

Mounts the filesystem which is in `filename`.

`filename` : | name of the file with the filesystem.
`colerrno` : | error value (COLE_EMEMORY, COLE_EOPENFILE, COLE_ENOFILESYSTEM, COLE_EINVALIDFILESYSTEM, COLE_EUNKNOWN).
Returns : | a filesystem in success, or NULL in other case.

### cole_umount ()

    int         cole_umount                     (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);

Umounts the filesystem `colefilesystem`.

`colefilesystem` : | filesystem to umount.
`colerrno` : | error value (COLE_ECLOSEFILE, COLE_EREMOVE).
Returns : | zero in success, no zero in other case.

### cole_print_tree ()

    int         cole_print_tree                 (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);

Prints on the standard output the tree of files and directories contained in `colefilesystem`. Currently this call always success.

`colefilesystem` : | filesystem of which the tree will be printed.
`colerrno` : | error value (errors from call cole_recurse_tree()).
Returns : | zero in success, no zero in other case.

### cole_locate_filename ()

    int         cole_locate_filename            (COLEFS *colefilesystem,
                                                 char *filename,
                                                 void *info,
                                                 COLE_LOCATE_ACTION_FUNC *action,
                                                 COLERRNO *colerrno);

Locate the `filename` in the filesystem `colefilesystem`, calling `action` when it's found. `info` is arbitrary pointer passed to `action`. Currently, `filename` must begin with a '/' character, it means `filename` is the absolute filename.

`colefilesystem` : | filesystem where to locate `filename`.
`filename` : | name of the file or directory to be located.
`info` : | arbitrary pointer passed to `action`.
`action` : | pointer to the function that is called when founding `filename`.
`colerrno` : | error value (COLE_EUNKNOWN, COLE_EMEMBERISNOTDIR, COLE_EFILENOTFOUND, COLE_EBROKENFILENAME, errors from call cole_recurse_tree()).
Returns : | zero in success, 1 in other case.

### cole_recurse_tree ()

    int         cole_recurse_tree               (COLEFS *colefilesystem,
                                                 void *info,
                                                 COLE_RECURSE_DIR_FUNC *inroot,
                                                 COLE_RECURSE_DIRENT_FUNC *indirentry,
                                                 COLE_RECURSE_DIR_FUNC *indir,
                                                 COLE_RECURSE_DIR_FUNC *outdir,
                                                 COLE_RECURSE_VISIT_DIR_FUNC *visitdir,
                                                 COLERRNO *colerrno);

Recurse the filesystem `colefilesystem`, calling the functions pointed by `inroot`, `indirentry`, `indir` and `outdirectory` when start visiting root directory, start visiting any directory entry (file or directory), start visiting a directory or end visiting a directory, respectively. If `visitdir` returns no zero or it's NULL, the directory is visited, otherwise is not visited. `info` is a arbitrary pointer which is passed to the functions pointed by `inroot`, `indirentry`, `indir` and `outdirectory`: it may be used to share arbitrary information between them.

`colefilesystem` : | filesystem to recurse.
`info` : | arbitrary pointer passed to the functions.
`inroot` : | pointer to the function that is called when start visiting root directory. It can be NULL.
`indirentry` : | pointer to the function that is called when start visiting any directory entry (file or directory). It can be NULL.
`indir` : | pointer to the function that is called when start visiting a directory. It can be NULL.
`outdir` : | pointer to the function that is called when end visiting a directory. It can be NULL.
`visitdir` : | pointer to the function that is called to know if visit a directory. It can be NULL.
`colerrno` : | error value (errors from calls cole_opendir_rootdir(), cole_opendir_direntry(), cole_closedir() and inroot, indirentry, indir, and outdir functions).
Returns : | zero if recursed all the tree, no zero in other case.

### cole_fopen ()

    COLEFILE*   cole_fopen                      (COLEFS *colefilesystem,
                                                 char *filename,
                                                 COLERRNO *colerrno);

Opens the file with the name `filename` in the filesystem `colefilesystem`. Currently, `filename` must begin with a '/' character, it means `filename` is the absolute filename.

`colefilesystem` : | filesystem in which `filename` is in.
`filename` : | name of the file to open.
`colerrno` : | error value (COLE_EFILENOTFOUND, errors from calls cole_opendir_rootdir(), cole_fopen_direntry() and cole_locate_filename()).
Returns : | a file in success, or NULL in other case.

### cole_fopen_direntry ()

    COLEFILE*   cole_fopen_direntry             (COLEDIRENT *coledirentry,
                                                 COLERRNO *colerrno);

Opens a directory entry as file.

`coledirentry` : | directory entry to be opened as file.
`colerrno` : | error value (COLE_EISNOTFILE, COLE_EMEMORY, COLE_ETMPNAM, COLE_EOPENFILE, COLE_EINVALIDFILESYSTEM, COLE_EREAD, COLE_EWRITE, COLE_EUNKNOWN).
Returns : | a file in success, or NULL in other case.

### cole_fclose ()

    int         cole_fclose                     (COLEFILE *colefile,
                                                 COLERRNO *colerrno);

Closes the file `colefile`.

`colefile` : | file to be closed.
`colerrno` : | error value (COLE_ECLOSEFILE, CLOSE_EREMOVE).
Returns : | zero in sucess, no zero in other case.

### cole_fread ()

    size_t      cole_fread                      (COLEFILE *colefile,
                                                 void *ptr,
                                                 size_t size,
                                                 COLERRNO *colerrno);

Reads `size` bytes from `colefile` and store them in the location given by `ptr`. If not success, the file position indicator is not changed.

`colefile` : | file to be read.
`ptr` : | memory location where the bytes will be stored.
`size` : | how many bytes will be read.
`colerrno` : | error value (COLE_EOF, COLE_EREAD, COLE_ESEEK).
Returns : | in sucess the number of bytes actually readed (maximum `size`) or zero in other case.

### cole_feof ()

    int         cole_feof                       (COLEFILE *colefile);

Tests if the end of file has been reached in `colefile`.

`colefile` : | file to be tested.
Returns : | no zero if the end of file has been reached, zero in other case.

### cole_fsize ()

    size_t      cole_fsize                      (COLEFILE *colefile);

`colefile` : | file of which its size will be returned.
Returns : | the size in bytes of the file `colefile`.

### cole_ftell ()

    size_t      cole_ftell                      (COLEFILE *colefile);

Get the current value of the file position indicator for the file `colefile`.

`colefile` : | file of which the file position indicator will be get.
Returns : | The file position.

### cole_fseek ()

    int         cole_fseek                      (COLEFILE *colefile,
                                                 size_t delta,
                                                 COLE_SEEK_FLAG direction,
                                                 COLERRNO *colerrno);

Sets the value of the file position indicator for the file `colefile` `delta` bytes from the beginning of the file, forward from the current position, backward from the current position, or from the end of the file, if `direction` is COLE_SEEK_SET, COLE_SEEK_BACKWARD, COLE_SEEK_FORWARD or COLE_SEEK_END, respectively. The file position indicator will always be <= `colefile`->filesize. If you `delta` is such that the previous line would not true, cole_fseek fails.

`colefile` : | file of which its file position indicator will be set.
`delta` : | number of bytes that the file position indicator will be moved.
`direction` : | from where start to count the `delta` bytes.
`colerrno` : | error value (COLE_EFSEEKDELTA).
Returns : | zero in success, no zero in other case.

### cole_frewind ()

    int         cole_frewind                    (COLEFILE *colefile,
                                                 COLERRNO *colerrno);

Sets the value of the file position indicator for the file `colefile` in the beginning of the file.

`colefile` : | file of which its file position indicator will be rewind.
`colerrno` : | error value (error from call cole_fseek()).
Returns : | zero in success, no zero in other case.

### cole_opendir_rootdir ()

    COLEDIR*    cole_opendir_rootdir            (COLEFS *colefilesystem,
                                                 COLERRNO *colerrno);

Opens the root directory of the filesystem `colefilesystem` as directory.

`colefilesystem` : | filesystem of which the root directory will be opened.
`colerrno` : | error value (COLE_EMEMORY).
Returns : | a directory in success, or NULL in other case.

### cole_opendir_direntry ()

    COLEDIR*    cole_opendir_direntry           (COLEDIRENT *coledirentry,
                                                 COLERRNO *colerrno);

Opens a directory entry as directory.

`coledirentry` : | directory entry to be opened as directory.
`colerrno` : | error value (COLE_EISNOTDIR, COLE_EMEMORY).
Returns : | a directory in success, or NULL in other case.

### cole_closedir ()

    int         cole_closedir                   (COLEDIR *coledir,
                                                 COLERRNO *colerrno);

Closes the directory `coledir`. Currently this call always success.

`coledir` : | directory to be closed.
`colerrno` : | error value().
Returns : | zero in success, no zero in other case.

### cole_visiteddirentry ()

    COLEDIRENT* cole_visiteddirentry            (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_nextdirentry ()

    COLEDIRENT* cole_nextdirentry               (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_direntry_isdir ()

    int         cole_direntry_isdir             (COLEDIRENT *coledirentry);

Tests if the directory entry `coledirentry` is a directory.

`coledirentry` : | directory entry to be tested.
Returns : | no zero if it is a directory, zero in other case.

### cole_direntry_isfile ()

    int         cole_direntry_isfile            (COLEDIRENT *coledirentry);

Tests if the directory entry `coledirentry` is a file.

`coledirentry` : | directory entry to be tested.
Returns : | no zero if it is a directory, zero in other case.

### cole_dir_getname ()

    char*       cole_dir_getname                (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_dir_getsize ()

    size_t      cole_dir_getsize                (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_dir_getsec1 ()

    long        cole_dir_getsec1                (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_dir_getsec2 ()

    long        cole_dir_getsec2                (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_dir_getdays1 ()

    long        cole_dir_getdays1               (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_dir_getdays2 ()

    long        cole_dir_getdays2               (COLEDIR *coledir);

`coledir` : |
Returns : |

### cole_direntry_getname ()

    char*       cole_direntry_getname           (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

### cole_direntry_getsize ()

    size_t      cole_direntry_getsize           (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

### cole_direntry_getdays1 ()

    long        cole_direntry_getdays1          (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

### cole_direntry_getsec1 ()

    long        cole_direntry_getsec1           (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

### cole_direntry_getdays2 ()

    long        cole_direntry_getdays2          (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

### cole_direntry_getsec2 ()

    long        cole_direntry_getsec2           (COLEDIRENT *coledirentry);

`coledirentry` : |
Returns : |

Prev | Home | Next
cole Library | Up | Internals