idl/Accessibility_StreamableContent.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <Bonobo_Storage.idl>
  24
  25 module Accessibility {
  26
  27   typedef sequence<string> StringSeq;
  28
  29   /**
  30    * An interface whereby an object allows its backing content
  31    * to be streamed to clients.  Negotiation of content type
  32    * is allowed.  Clients may examine the backing data and
  33    * transform, convert, or parse the content in order to
  34    * present it in an alternate form to end-users.
  35    *
  36    * @note The StreamableContent interface is particularly useful for saving,
  37    * printing, or post-processing entire documents, or for persisting
  38    * alternate views of a document.
  39    * If document content itself is being serialized, stored, or converted,
  40    * then use of the StreamableContent interface can help address performance
  41    * issues.  Unlike most AT-SPI/Accessibility interfaces, this interface
  42    * is not strongly tied to the current user-agent view of the
  43    * a particular document, but may in some cases give access to the
  44    * underlying model data.
  45    */
  46   interface StreamableContent {
  47
  48       /**
  49        * Specifies the meaning of a seek 'offset'.  Not all SeekTypes are
  50        * supported by all StreamableContent data sources, for instance
  51        * some streams may not support seeking from the beginning or other
  52        * types of 'backwards' seeks.
  53        */
  54       enum SeekType {
  55           SEEK_SET, /**< Seek from the start of the stream or data source.*/
  56           SEEK_CURRENT, /**< Seek relative to the current position. */
  57           SEEK_END /**< Seek from the end of the file, stream, or data source. */
  58       };
  59
  60       /**
  61        * Indicates that a transmission error has occurred while
  62        * reading or seeking the stream or data source.
  63        */
  64       exception IOError {
  65           string reason;
  66       };
  67       /**
  68        * Indicates that the requested operation is not supported by the stream instance.
  69        */
  70       exception NotSupported {
  71           string reason;
  72       };
  73
  74       /**
  75        * The operation is supported, but the current requestor does not have
  76        * permission to t the request, for instance does not have permission to read
  77        * the stream.
  78        */
  79       exception NoPermission {
  80           string reason;
  81       };
  82
  83       /**
  84        * getContentTypes:
  85        * @returns the list of available mimetypes for this object's content.
  86        */
  87     StringSeq getContentTypes ();
  88       /**
  89        * Retrieve this object's content, in a format appropriate to a
  90        * requested mimetype.
  91        *
  92        * @note the data is returned as an object of type ::Bonobo::Stream.
  93        * The primary methods which are supported on Bonobo::Streams for the
  94        * purposes of the ::StreamableContent API are \c seek and \c read.
  95        * \c seek may not be supported for all mimetypes or
  96        * all implementors.
  97        *
  98        \verbatim
  99         long Bonobo::Stream:seek (in long offset, in SeekType whence)
 100                 raises (NoPermission, IOError)
 101         void Bonobo::Stream:read (in long count, out iobuf buffer)
 102                 raises (NoPermission, IOError)
 103        \endverbatim
 104        *
 105        * @see ::Bonobo::Stream
 106        *
 107        * @returns a ::Bonobo::Stream whose mimetype matches \a contentType,
 108        *          if available, or \c NIL.
 109        */
 110     Bonobo::Stream getContent (in string contentType);
 111
 112     /**
 113      * \cond
 114      * unImplemented:
 115      *
 116      * placeholders for future expansion.
 117      */
 118     void unImplemented ();
 119     void unImplemented2 ();
 120     void unImplemented3 ();
 121     void unImplemented4 ();
 122       /** \endcond */
 123   };
 124 };