-----------------------------------------------------------------------------
--
--                     Onions Network Streams Library
--
--                 O N I O N S . I N S T R E A M S . D I R
--
--                                 S p e c
--
--     Copyright (C) 1997-1998  Regents of the University of California
--
--  Onions 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, with or without the single exception listed below;
--  either version 2, or (at your option) any later version.  Onions 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
--  distributed with Onions; see the file COPYING.  If not, write to the
--  Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
--  02111-1307, USA.
--
--  As a special exception, if other files instantiate generics from this
--  library, or you link this library with other files to produce an
--  executable, this library does not by itself cause the resulting
--  executable to be covered by the GNU General Public License.  This
--  exception does not however invalidate any other reasons why the
--  executable file might be covered by the GNU General Public License.
--
--  Created in 1997 by Roy T. Fielding and Yuzo Kanomata
-----------------------------------------------------------------------------
--
--  The Dir Input Stream is a stream end that reads a filesystem directory
--  and generates a stream of filename buckets.  Open must be called
--  before reading.  A filter can be used on top of this stream to
--  create a formatted directory listing.
--

with Ada.Streams;
with Interfaces.C.Strings;
with Onions.Thin;

package Onions.Instreams.Dir is

   type Dir_Input_Stream is new Input_Stream with private;

   type Dir_Input_Stream_Ptr is access all Dir_Input_Stream;

   ---------------------------------------------
   --  Dispatching Stream Control Operations  --
   ---------------------------------------------

   --  Free the storage associated with a stream object.
   --
   procedure Free (SP : in out Dir_Input_Stream_Ptr);

   --  Open the named directory and associate it with an input stream.
   --  Raises Device_Error if it is unable to open the directory.
   --
   function Open
      (Stream : in Dir_Input_Stream_Ptr;
       Name   : in String) return Input_Pipe;

   --  Close the directory associated with the stream.  Note that this
   --  is different from a Close of an Input_Pipe in that it does not
   --  free the stream.  I.e., the stream can be Open'd again.
   --
   procedure Close (Stream : in out Dir_Input_Stream);

   --  Abort_Stream should only be used if a stream is interrupted
   --  by the user, or an error occurs that makes the whole stream bad.
   --  It forces the stream closed without a flush.
   --
   procedure Abort_Stream (Stream : in out Dir_Input_Stream);

   --  Reset is like Close, but only resets to the directory beginning
   --  instead of closing the directory.
   --
   procedure Reset (Stream : in out Dir_Input_Stream);

   --  Drain the stream by returning any processed data
   --  as if it were the end-of-stream.
   --
   procedure Drain
      (Stream   : in out Dir_Input_Stream;
       ItemList : out Bucket_List);

   --  Name returns a string containing the currently open directory name.
   --
   function Name (Stream : in Dir_Input_Stream) return String;

   ------------------------------------
   --  Ada.Streams Dispatching Read  --
   ------------------------------------

   --  Read obtains stream a filename from Stream and places it into
   --  the components of Item.  Last is set to the index of
   --  the last component of Item that was filled.  This interface is
   --  defined by Ada.Streams for abstract stream operations.  We won't
   --  use it much because it forces a full data copy when filtering.
   --
   procedure Read
      (Stream : in out Dir_Input_Stream;
       Item   : out Ada.Streams.Stream_Element_Array;
       Last   : out Ada.Streams.Stream_Element_Offset);

   ----------------------------------
   --  Data Processing Operations  --
   ----------------------------------

   --  Process does the real work of reading from the directory and moving
   --  each filename bucket to the Processed read queue.
   --  The Everything (end-of-stream indicator) boolean is ignored.
   --  Raises End_Error        when end-of-directory is encountered;
   --         Status_Error     if the directory hasn't been Open'd yet;
   --         Storage_Error    if there is no memory available for the buffer;
   --         Device_Error     if anything else goes fatally wrong.
   --
   procedure Process
      (Stream     : in out Dir_Input_Stream;
       Everything : Boolean);

   --  Unprocess would be called by Pop if someone foolishly tried
   --  to pop off the Dir_Input_Stream.  We just raise Use_Error.
   --
   procedure Unprocess (Stream : in out Dir_Input_Stream);

private

   type Dir_Input_Stream is new Input_Stream with record

      --  Name of the open directory
      --
      Dirname : C.Strings.chars_ptr := C.Strings.Null_Ptr;

      --  DIR_Ptr is the OS directory handle once it is opened
      --
      DIR_Ptr : Onions.Thin.DIR_Address := System.Null_Address;

   end record;

end Onions.Instreams.Dir;