please read: storage interface

[Dietmar Maurer <dietmar maurer-it com>]

Hi everybody,

maybe some of you already noticed that I have sent many mails
in the last month concerning the storage interface. The storage
interface is simply not ready and I already pointed out its weakness.

Although I sent many mails to the list I have received very few
constructive answers. My point of view is:

- There are many things we should correct (see the attached idl file,
     and tell me your opinion)
- We are behind the code freeze
- I have really tried to fix it since one month or so, but never got
    some feedback - it seems that all developers are very busy.

All I can do is to offer you to implement the changes
in the bonobo module. I will need only a few days to do that.

So please can you give me that extra time? I know we are
behind the freeze but I think it is absolutely necessary.

Regards,

    Dietmar

/*
 *
 * Author:
 *    Miguel de Icaza (miguel gnu org)
 *
 * Terms:
 *
 *    Storage:   This interface provides access to a directory
 *               like storage facility. 
 *
 *    Stream:    Used to read and write bytes to a storage.  The
 *               Streams are equivalent to files.
 *
 */

/*

  Changes:

  no return value for writes 

  changed directory_list to DirectoryList

  remove the close method from the Stream interface

  added more exceptions

  New get_info method (something like unix stat). 

  New set_info method

  add more info to directory_list

  more open modes

  removed eos, length method

  removed create methods

  changed the stream copy_to method to use out instead of inout.

 */

module Bonobo {

        const long MASK_CONTENT_TYPE = 1;
        const long MASK_SIZE         = 2;
        const long MASK_TYPE         = 4;

	typedef string ContentType;

	struct StorageInfo {
		string		name;
		unsigne long    type;
		ContentType	content_type;
		long		size;
	};

	interface Stream : Unknown {
		typedef sequence<octet> iobuf;

		exception IOError {}; /* driver internal error */
		exception NoPermission {};
		exception NotSupported {};

		enum SeekType {
                        SEEK_SET,
                        SEEK_CUR,
                        SEEK_END
                };

		/**
		 * get_info:
		 *
		 * Returns a StorageInfo structure which contains
		 * the name, content_type and size info.
		 */
		StorageInfo get_info (in long mask)
			raises (IOError);
		
		/**	
		 * set_info:
		 *
		 */
		void set_info (in StorageInfo info, in long mask)
			raises (IOError);
		
		/**
		 * read:
		 * @count:  number of bytes to read.
		 * @buffer: the buffer where the data is returned.
		 */
		void read (in long count, out iobuf buffer)
			raises (NoPermission, IOError);
		
		/**
		 * write:
		 * @buffer: a buffer to write.
		 *
		 * writes the buffer to this stream.
		 */
		void write (in iobuf buffer)
			raises (NoPermission, IOError);

		/**
		 * seek:
		 * @offset: offset
		 * @whence: 
		 *
		 * Sets the read/write pointer to @offset (relative to @whence)
		 */
		long seek (in long offset, in SeekType whence)
			raises (IOError, NotSupported);

		/**
		 * truncate:
		 * @length: new size of the stream
		 *
		 */
		void truncate (in long length)
			raises (IOError, NoPermission, NotSupported);
		
		/**
		 * copy_to:
		 * @path: destination file.
		 * @bytes: number of bytes to copy, or -1 to copy until eof
		 * @read: output, how many bytes were read.
		 * @write: output, how many bytes were written.
		 *
		 * Copies @bytes bytes (or until EOF if @bytes is -1) starting
		 * at the current read/write pointer to the component in @dest
		 * inside the Storage.
		 */
		void copy_to (in string dest, in long bytes, 
			      out long read, out long written)
			raises (IOError, NoPermission);

	};

	interface Storage : Unknown {
		
		typedef sequence<StorageInfo> DirectoryList;

		typedef long OpenMode;
		const OpenMode READ	   = 1;
		const OpenMode WRITE       = 2;
		const OpenMode CREATE      = 4;
		const OpenMode FAILIFEXIST = 8;
		const OpenMode COMPRESSED  = 16; /* try to compress */

		exception IOError {}; /* driver internal error */
		exception NameExists {};
		exception NotStream {};
		exception NotStorage {};
		exception NotFound {};
		exception NoPermission {};

		/**
		 * get_info:
		 *
		 * Returns a StorageInfo structure which contains
		 * the name, content_type and size info.
		 */
		StorageInfo get_info (in string path, in long mask)
			raises (IOError);
		
		/**	
		 * set_info:
		 *
		 */
		void set_info (in string path, in StorageInfo info, 
			       in long mask)
			raises (IOError);

		/**
		 * open_stream:
		 * @path: path of the stream to open
		 * @mode: open flags
		 *
		 * Opens a Stream whose name is @path.
		 */
		Stream open_stream (in string path, in OpenMode mode)
			raises (IOError, NotFound, NoPermission, NotStream);

		/**
		 * open_storage:
		 * @path: path of the storage to open.
		 * @mode: open mode.
		 * 
		 * Returns a storage object for @path.
		 */
		Storage open_storage (in string path, in OpenMode mode)
			raises (IOError, NotFound, NoPermission, NotStorage);

		/**
		 * list_contents:
		 * @path: path that we want to examine.
		 *
		 * Returns a list of all the Storage and Streams available
		 * at @path.
		 */
		DirectoryList list_contents (in string path, in long mask)
			raises (IOError, NotStorage, NotFound);

		/** 
		 * copy_to:
		 * @target: where to copy this storage to.
		 *
		 * Copies this storages contents to the @target storage
		 */
		void copy_to (in Storage target)
			raises (IOError, NoPermission);

		/** 
		 * rename:
		 * @path_name: element name to rename
		 * @new_path_name: new name we want to use
		 *
		 * Renames a Stream or Storage component inside a Storage.
		 */
		void rename (in string path_name, in string new_path_name)
			raises (IOError, NameExists, NotFound, NoPermission);

		/**
		 * erase:
		 * @path: path to the element to erase.
		 * 
		 * Destroys the element pointed to by @path.  The element
		 * can be a Storage or a Stream.
		 */
		void erase (in string path)
                       raises (IOError, NoPermission, NotFound);

	};
};