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 by which the requested data from a StreamableContent object
  31    * may be read by the client.
  32    * @note this interface supercedes the use of BonoboStream by previous
  33    * versions of StreamableContent.
  34    *
  35    * @since AT-SPI 1.7.0
  36    */
  37   interface ContentStream {
  38
  39       typedef sequence<octet> iobuf;
  40
  41       /**
  42        * Indicates that a transmission error has occurred while
  43        * reading or seeking the stream or data source.
  44        */
  45       exception IOError {
  46           string reason;
  47       };
  48       /**
  49        * Indicates that the requested operation is not supported by the stream instance.
  50        */
  51       exception NotSupported {
  52           string reason;
  53       };
  54
  55       /**
  56        * The operation is supported, but the current requestor does not have
  57        * permission to t the request, for instance does not have permission to read
  58        * the stream.
  59        */
  60       exception NoPermission {
  61           string reason;
  62       };
  63
  64       /**
  65        * Specifies the meaning of a seek 'offset'.  Not all SeekTypes are
  66        * supported by all StreamableContent data sources, for instance
  67        * some streams may not support seeking from the beginning or other
  68        * types of 'backwards' seeks.
  69        */
  70       enum SeekType {
  71           SEEK_SET, /**< Seek from the start of the stream or data source.*/
  72           SEEK_CURRENT, /**< Seek relative to the current position. */
  73           SEEK_END /**< Seek from the end of the file, stream, or data source. */
  74       };
  75
  76       /**
  77        * Seek to a specified position in the Stream.
  78        * @param offset an offset specifying the requested position in the stream,
  79        * relative to the SeekType specified in \c whence.
  80        * @param whence a SeekType specifying the reference point from which the
  81        * seek offset is calculated.  Some forms of seek are not supported by certain
  82        * implementations of Stream, in which case a NotSupported exception will be raised.
  83        * @returns the actual resulting offset, if no exception was raised.
  84        **/
  85       long seek (in long offset, in SeekType whence)
  86           raises (NoPermission, IOError, NotSupported);
  87       /**
  88        * Request/read a specified amount of data from a Stream.
  89        * @returns the number of bytes actually read into the client buffer.
  90        **/
  91       long read (in long count, out iobuf buffer)
  92           raises (NoPermission, IOError);
  93       /**
  94        * close the stream and release associated resources.
  95        * A client should not perform further operations on a
  96        * StreamableContent::Stream object after closing it.
  97        **/
  98       void close ();
  99
 100       /** /cond */
 101       void unimplemented ();
 102       void unimplemented2 ();
 103       /** /endcond */
 104   };
 105
 106
 107   /**
 108    * An interface whereby an object allows its backing content
 109    * to be streamed to clients.  Negotiation of content type
 110    * is allowed.  Clients may examine the backing data and
 111    * transform, convert, or parse the content in order to
 112    * present it in an alternate form to end-users.
 113    *
 114    * @note The StreamableContent interface is particularly useful for saving,
 115    * printing, or post-processing entire documents, or for persisting
 116    * alternate views of a document.
 117    * If document content itself is being serialized, stored, or converted,
 118    * then use of the StreamableContent interface can help address performance
 119    * issues.  Unlike most AT-SPI/Accessibility interfaces, this interface
 120    * is not strongly tied to the current user-agent view of the
 121    * a particular document, but may in some cases give access to the
 122    * underlying model data.
 123    */
 124   interface StreamableContent {
 125
 126       /**
 127        * getContentTypes:
 128        * @returns the list of available mimetypes for this object's content.
 129        */
 130     StringSeq getContentTypes ();
 131       /**
 132        * \n DEPRECATED, use getStream instead.
 133        * getContent:
 134        * Retrieve this object's content, in a format appropriate to a
 135        * requested mimetype.
 136        *
 137        * @note the data is returned as an object of type ::Bonobo::Stream.
 138        * The primary methods which are supported on Bonobo::Streams for the
 139        * purposes of the ::StreamableContent API are \c seek and \c read.
 140        * \c seek may not be supported for all mimetypes or
 141        * all implementors.
 142        *
 143        \verbatim
 144         long Bonobo::Stream:seek (in long offset, in SeekType whence)
 145                 raises (NoPermission, IOError)
 146         void Bonobo::Stream:read (in long count, out iobuf buffer)
 147                 raises (NoPermission, IOError)
 148        \endverbatim
 149        *
 150        * @see ::Bonobo::Stream
 151        *
 152        * @returns a ::Bonobo::Stream whose mimetype matches \a contentType,
 153        *          if available, or \c NIL.
 154        */
 155     Bonobo::Stream getContent (in string contentType);
 156
 157       /**
 158        * Retrieve this object's content, in a format appropriate to a
 159        * requested mimetype, as a ::ContentStream instance.
 160        *
 161        * @note This method supercedes the older getContent method, which
 162        * relied on the Bonobo::Stream API.
 163        * \c seek may not be supported for all mimetypes or
 164        * all implementors.
 165        *
 166        * @param contentType a string specifying the desired mimetype for the content stream.
 167        * @returns a Stream whose mimetype matches \a contentType,
 168        *          if available, or \c NIL.
 169        * @since AT-SPI 1.8.0
 170        */
 171     ContentStream getStream (in string contentType);
 172
 173       /**
 174        * Get a URI pointing to the content of the specified type, if such a URI
 175        * can be obtained.  Not all streamable content providers have URI representations.
 176        *
 177        * @param contentType a string specifying the desired mimetype for the content stream.
 178        * If NULL, then a URI for the default content type will be returned, if available.
 179        *
 180        * @returns a string which constitutes a URI for a stream of the specified
 181        * content type, or NULL if no such URI can be obtained.
 182        */
 183     string getURI (in string contentType);
 184     /**
 185      * \cond
 186      * unImplemented:
 187      *
 188      * placeholders for future expansion.
 189      */
 190     void unImplemented ();
 191     void unImplemented2 ();
 192       /** \endcond */
 193   };
 194
 195 };