lib/silcutil/silcdir.h

   1 /*
   2
   3   silcdir.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/Directory Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The SILC Directory API provides portable way to open and read directories
  25  * and their content.
  26  *
  27  * EXAMPLE
  28  *
  29  * SilcDir dir;
  30  * SilcDirEntry entry;
  31  *
  32  * dir = silc_dir_open("foodir");
  33  *
  34  * while ((entry = silc_dir_read(dir, NULL)))
  35  *   printf("File name: %s\n", silc_dir_entry_name(entry));
  36  *
  37  * silc_dir_close(dir);
  38  *
  39  ***/
  40
  41 #ifndef SILCDIR_H
  42 #define SILCDIR_H
  43
  44 /****s* silcutil/SilcDir
  45  *
  46  * NAME
  47  *
  48  *    typedef struct SilcDirStruct *SilcDir;
  49  *
  50  * DESCRIPTION
  51  *
  52  *    The directory context.  This is allocated by silc_dir_open and
  53  *    freed by calling silc_dir_close.
  54  *
  55  ***/
  56 typedef struct SilcDirStruct *SilcDir;
  57
  58 /****s* silcutil/SilcDirEntry
  59  *
  60  * NAME
  61  *
  62  *    typedef struct SilcDirEntryStruct *SilcDirEntry;
  63  *
  64  * DESCRIPTION
  65  *
  66  *    The directory entry context.  The entry is usually a file in the
  67  *    directory.
  68  *
  69  ***/
  70 typedef struct SilcDirEntryStruct *SilcDirEntry;
  71
  72 /****f* silcutil/silc_dir_open
  73  *
  74  * SYNOPSIS
  75  *
  76  *    SilcDir silc_dir_open(const char *name);
  77  *
  78  * DESCRIPTION
  79  *
  80  *    Opens the directory named `name' and returns its context.  Returns NULL
  81  *    on error and sets the silc_errno.  This function must be called before
  82  *    being able to read the directory and its contents.
  83  *
  84  ***/
  85 SilcDir silc_dir_open(const char *name);
  86
  87 /****f* silcutil/silc_dir_close
  88  *
  89  * SYNOPSIS
  90  *
  91  *    void silc_dir_close(SilcDir dir);
  92  *
  93  * DESCRIPTION
  94  *
  95  *    Closes the directory `dir'.
  96  *
  97  ***/
  98 void silc_dir_close(SilcDir dir);
  99
 100 /****f* silcutil/silc_dir_read
 101  *
 102  * SYNOPSIS
 103  *
 104  *    SilcDirEntry silc_dir_read(SilcDir dir, SilcFileStat status);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Reads next entry (file) from the directory `dir'.  The silc_dir_open
 109  *    must be called first before reading from the directory.  Returns the
 110  *    next entry context or NULL if there are no more entries or error occurs.
 111  *    In case of error the silc_errno is also set.
 112  *
 113  *    If the `status' is non-NULL this will also call silc_file_stat and
 114  *    returns the status into the `status' pointer.
 115  *
 116  *    The returned context remains valid until the silc_dir_read is called
 117  *    again.
 118  *
 119  ***/
 120 SilcDirEntry silc_dir_read(SilcDir dir, SilcFileStat status);
 121
 122 /****f* silcutil/silc_dir_rewind
 123  *
 124  * SYNOPSIS
 125  *
 126  *    void silc_dir_rewind(SilcDir dir);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Rewinds the directory `dir' to the beginning of the directory.  Calling
 131  *    silc_dir_read after this will return the first entry in the directory.
 132  *
 133  ***/
 134 void silc_dir_rewind(SilcDir dir);
 135
 136 /****f* silcutil/silc_dir_name
 137  *
 138  * SYNOPSIS
 139  *
 140  *    const char *silc_dir_name(SilcDir dir);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Returns the name of the directory from `dir' context.
 145  *
 146  ***/
 147 const char *silc_dir_name(SilcDir dir);
 148
 149 /****f* silcutil/silc_dir_entry_name
 150  *
 151  * SYNOPSIS
 152  *
 153  *    const char *silc_dir_entry_name(SilcDirEntry entry);
 154  *
 155  * DESCRIPTION
 156  *
 157  *    Returns the name of the entry (file) `entry'.  The returned pointer
 158  *    remains valid until the silc_dir_read is called again.
 159  *
 160  ***/
 161 const char *silc_dir_entry_name(SilcDirEntry entry);
 162
 163 #endif /* SILCDIR_H */