home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_StreamableContent.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  7.1 KB  |  196 lines
  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 : Bonobo::Unknown {
  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 : Bonobo::Unknown {
  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. };
  196.