/**	@file	dk3dir.h	Directory processing.

The functions in this module can be used to traverse a directory.

The example below shows how to open the current directory
and read information about the contents.

After opening a directory you can use
dk3dir_get_next_directory() or dk3dir_get_next_file() to load
information about the next item. On success you can use
dk3dir_get_shortname(), dk3dir_get_fullname() and dk3dir_get_stat()
to obtain information about the item.

If you want to traverse the directory multiple times you can
use dk3dir_reset() to reset traversal to the beginning.

@section	dirextraverse	Example for traversing a directory

@code
#include <stdio.h>
#include <dk3all.h>

static dkChar const gn[] = { "tests" };

static dkChar const * const mytexts[] = {
dkT("Directories:"),
dkT("Files:"),
NULL
};

DK3_MAIN
{
  dk3_app_t		*app = NULL;
  dkChar const * const	*msg = NULL;
  dkChar const		*en  = NULL;
  dk3_dir_t		*dir = NULL;
  dk3_stat_t		*stb = NULL;
  app = dk3app_open_command(argc, (dkChar const * const *)argv, gn);
  if(app) {
    msg = dk3app_messages(app, dkT("myprog.str"), (dkChar const **)mytexts);
    dk3sf_initialize_stdout();
    dir = dk3dir_open_app(dkT("."), app);
    if(dir) {
      if(dk3dir_get_number_of_directories(dir)) {
        dk3sf_fputs(msg[0], stdout);
	dk3sf_fputc(dkT('\n'), stdout);
        while(dk3dir_get_next_directory(dir)) {
	  en = dk3dir_get_shortname(dir);
	  if(en) {
	    dk3sf_fputs(en, stdout);
	    dk3sf_fputc(dkT('\n'), stdout);
	  }
	}
      }
      if(dk3dir_get_number_of_files(dir)) {
        while(dk3dir_get_next_file(dir)) {
	  en = dk3dir_get_shortname(dir);
	  if(en) {
	    dk3sf_fputs(en, stdout);
	    dk3sf_fputc(dkT('\n'), stdout);
	  }
	}
      }
      dk3dir_close(dir);
    }
    dk3app_close(app);
  }
}
@endcode

@section	direxexpand	Example, find all *.h files (Windows only)
@code
#include <stdio.h>
#include <dk3all.h>

static dkChar const gn[] = { "tests" };

static dkChar const * const mytexts[] = {
dkT("Directories:"),
dkT("Files:"),
NULL
};

DK3_MAIN
{
  dk3_app_t		*app = NULL;
  dkChar const * const	*msg = NULL;
  dkChar const		*en  = NULL;
  dk3_dir_t		*dir = NULL;
  dk3_stat_t		*stb = NULL;
  app = dk3app_open_command(argc, (dkChar const * const *)argv, gn);
  if(app) {
    msg = dk3app_messages(app, dkT("myprog.str"), (dkChar const **)mytexts);
    dk3sf_initialize_stdout();
    dir = dk3dir_fne_open_app(dkT("*.h"), app);
    if(dir) {
      if(dk3dir_get_number_of_files(dir)) {
        while(dk3dir_get_next_file(dir)) {
	  en = dk3dir_get_shortname(dir);
	  if(en) {
	    dk3sf_fputs(en, stdout);
	    dk3sf_fputc(dkT('\n'), stdout);
	  }
	}
      }
      dk3dir_close(dir);
    }
    dk3app_close(app);
  }
}
@endcode

*/