/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 Sun Microsystems, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include <Bonobo_Storage.idl>

module Accessibility {

  typedef sequence<string> StringSeq;

  /** 
   * An interface by which the requested data from a StreamableContent object
   * may be read by the client.
   * @note this interface supercedes the use of BonoboStream by previous
   * versions of StreamableContent.
   *
   * @since AT-SPI 1.7.0 
   */
  interface ContentStream : Bonobo::Unknown {

      typedef sequence<octet> iobuf;

      /** 
       * Indicates that a transmission error has occurred while 
       * reading or seeking the stream or data source. 
       */
      exception IOError {
	  string reason;
      };
      /** 
       * Indicates that the requested operation is not supported by the stream instance.
       */
      exception NotSupported {
	  string reason;
      };

      /**
       * The operation is supported, but the current requestor does not have
       * permission to t the request, for instance does not have permission to read 
       * the stream.
       */
      exception NoPermission {
	  string reason;
      };

      /** 
       * Specifies the meaning of a seek 'offset'.  Not all SeekTypes are 
       * supported by all StreamableContent data sources, for instance 
       * some streams may not support seeking from the beginning or other
       * types of 'backwards' seeks.
       */
      enum SeekType {
	  SEEK_SET, /**< Seek from the start of the stream or data source.*/
	  SEEK_CURRENT, /**< Seek relative to the current position. */
	  SEEK_END /**< Seek from the end of the file, stream, or data source. */
      };

      /** 
       * Seek to a specified position in the Stream.
       * @param offset an offset specifying the requested position in the stream,
       * relative to the SeekType specified in \c whence.
       * @param whence a SeekType specifying the reference point from which the 
       * seek offset is calculated.  Some forms of seek are not supported by certain
       * implementations of Stream, in which case a NotSupported exception will be raised.
       * @returns the actual resulting offset, if no exception was raised.
       **/
      long seek (in long offset, in SeekType whence)
	  raises (NoPermission, IOError, NotSupported);
      /** 
       * Request/read a specified amount of data from a Stream.
       * @returns the number of bytes actually read into the client buffer.
       **/
      long read (in long count, out iobuf buffer)  
	  raises (NoPermission, IOError);
      /** 
       * close the stream and release associated resources.  
       * A client should not perform further operations on a 
       * StreamableContent::Stream object after closing it.
       **/
      void close ();

      /** /cond */
      void unimplemented ();
      void unimplemented2 ();
      /** /endcond */
  };


  /** 
   * An interface whereby an object allows its backing content
   * to be streamed to clients.  Negotiation of content type
   * is allowed.  Clients may examine the backing data and
   * transform, convert, or parse the content in order to
   * present it in an alternate form to end-users.
   *
   * @note The StreamableContent interface is particularly useful for saving, 
   * printing, or post-processing entire documents, or for persisting 
   * alternate views of a document.
   * If document content itself is being serialized, stored, or converted,
   * then use of the StreamableContent interface can help address performance
   * issues.  Unlike most AT-SPI/Accessibility interfaces, this interface
   * is not strongly tied to the current user-agent view of the
   * a particular document, but may in some cases give access to the 
   * underlying model data.
   */
  interface StreamableContent : Bonobo::Unknown {

      /**
       * getContentTypes:
       * @returns the list of available mimetypes for this object's content.
       */
    StringSeq getContentTypes ();
      /**
       * \n DEPRECATED, use getStream instead.
       * getContent:
       * Retrieve this object's content, in a format appropriate to a
       * requested mimetype.
       *
       * @note the data is returned as an object of type ::Bonobo::Stream.
       * The primary methods which are supported on Bonobo::Streams for the
       * purposes of the ::StreamableContent API are \c seek and \c read.
       * \c seek may not be supported for all mimetypes or
       * all implementors.
       * 
       \verbatim
        long Bonobo::Stream:seek (in long offset, in SeekType whence)
                raises (NoPermission, IOError)
        void Bonobo::Stream:read (in long count, out iobuf buffer)
                raises (NoPermission, IOError)
       \endverbatim
       *  
       * @see ::Bonobo::Stream
       *
       * @returns a ::Bonobo::Stream whose mimetype matches \a contentType,
       *          if available, or \c NIL.
       */
    Bonobo::Stream getContent (in string contentType);

      /**
       * Retrieve this object's content, in a format appropriate to a
       * requested mimetype, as a ::ContentStream instance.
       *
       * @note This method supercedes the older getContent method, which
       * relied on the Bonobo::Stream API.
       * \c seek may not be supported for all mimetypes or
       * all implementors.
       * 
       * @param contentType a string specifying the desired mimetype for the content stream.
       * @returns a Stream whose mimetype matches \a contentType,
       *          if available, or \c NIL.
       * @since AT-SPI 1.8.0
       */
    ContentStream getStream (in string contentType);

      /**
       * Get a URI pointing to the content of the specified type, if such a URI
       * can be obtained.  Not all streamable content providers have URI representations.
       *
       * @param contentType a string specifying the desired mimetype for the content stream.
       * If NULL, then a URI for the default content type will be returned, if available.
       *
       * @returns a string which constitutes a URI for a stream of the specified
       * content type, or NULL if no such URI can be obtained.
       */
    string getURI (in string contentType);
    /**
     * \cond
     * unImplemented:
     *
     * placeholders for future expansion.
     */
    void unImplemented ();
    void unImplemented2 ();
      /** \endcond */
  };

};