xml/org.freedesktop.atspi.StreamableContent.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>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.</p>
  11
  12   <p>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.</p>
  16
  17   <p>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.</p>
  21 </tp:license>
  22 <interface name="org.freedesktop.atspi.ContentStream">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>An interface by which the requested data from a StreamableContent object
  25       may be read by the client.
  26       @note this interface supercedes the use of BonoboStream by previous
  27       versions of StreamableContent.  </p>
  28
  29     <p>@since AT-SPI 1.7.0 </p>
  30   </tp:docstring>
  31 </interface>
  32 <tp:enum name="SeekType" type="u">
  33   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  34     <p>Specifies the meaning of a seek 'offset'.  Not all SeekTypes are
  35       supported by all StreamableContent data sources, for instance
  36       some streams may not support seeking from the beginning or other
  37       types of 'backwards' seeks.</p>
  38   </tp:docstring>
  39   <tp:enumvalue suffix="SEEK_SET">
  40   <tp:docstring>
  41     &lt; Seek from the start of the stream or data source.
  42   </tp:docstring>
  43   </tp:enumvalue>
  44   <tp:enumvalue suffix="SEEK_CURRENT" value="1">
  45   <tp:docstring>
  46     &lt; Seek relative to the current position.
  47   </tp:docstring>
  48   </tp:enumvalue>
  49   <tp:enumvalue suffix="SEEK_END" value="2">
  50   <tp:docstring>
  51     &lt; Seek from the end of the file, stream, or data source.
  52   </tp:docstring>
  53   </tp:enumvalue>
  54 </tp:enum>
  55 <tp:errors xmlns="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.atspi.error">
  56   <tp:error name="IOError">
  57   <tp:docstring>
  58     Indicates that a transmission error has occurred while reading or seeking the stream or data source.
  59   </tp:docstring>
  60   </tp:error>
  61   <tp:error name="NotSupported">
  62   <tp:docstring>
  63     Indicates that the requested operation is not supported by the stream instance.
  64   </tp:docstring>
  65   </tp:error>
  66   <tp:error name="NoPermission">
  67   <tp:docstring>
  68     The operation is supported, but the current requestor does not havepermission to t the request, for instance does not have permission to read the stream.
  69   </tp:docstring>
  70   </tp:error>
  71 </tp:errors>
  72 <method name="seek">
  73   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  74     <p>Seek to a specified position in the Stream.
  75       @param offset an offset specifying the requested position in the stream,
  76       relative to the SeekType specified in \c whence.
  77       @param whence a SeekType specifying the reference point from which the
  78       seek offset is calculated.  Some forms of seek are not supported by certain
  79       implementations of Stream, in which case a NotSupported exception will be raised.</p>
  80   </tp:docstring>
  81   <arg direction="in" name="offset" type="i"/>
  82   <arg direction="in" name="whence" type="u" tp:type="SeekType"/>
  83   <arg direction="out" type="i">
  84   <tp:docstring>
  85     the actual resulting offset, if no exception was raised.
  86   </tp:docstring>
  87   </arg>
  88   <tp:possible-errors>
  89     <tp:error name="org.freedesktop.atspi.error.(NoPermission"/>
  90     <tp:error name="org.freedesktop.atspi.error.IOError"/>
  91     <tp:error name="org.freedesktop.atspi.error.NotSupported"/>
  92   </tp:possible-errors>
  93 </method>
  94 <method name="read">
  95   <tp:docstring>
  96     Request/read a specified amount of data from a Stream.
  97   </tp:docstring>
  98   <arg direction="in" name="count" type="i"/>
  99   <arg direction="out" name="buffer" type="ay" tp:type="iobuf"/>
 100   <arg direction="out" type="i">
 101   <tp:docstring>
 102     the number of bytes actually read into the client buffer.
 103   </tp:docstring>
 104   </arg>
 105   <tp:possible-errors>
 106     <tp:error name="org.freedesktop.atspi.error.(NoPermission"/>
 107     <tp:error name="org.freedesktop.atspi.error.IOError"/>
 108   </tp:possible-errors>
 109 </method>
 110 <method name="close">
 111   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 112     <p>close the stream and release associated resources.
 113       A client should not perform further operations on a
 114       StreamableContent::Stream object after closing it.</p>
 115   </tp:docstring>
 116 </method>
 117 <method name="unimplemented">
 118   <tp:docstring>
 119     /cond
 120   </tp:docstring>
 121 </method>
 122 <method name="unimplemented2">
 123 </method>
 124 <interface name="org.freedesktop.atspi.StreamableContent">
 125   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 126     <p>An interface whereby an object allows its backing content
 127       to be streamed to clients.  Negotiation of content type
 128       is allowed.  Clients may examine the backing data and
 129       transform, convert, or parse the content in order to
 130       present it in an alternate form to end-users.  </p>
 131
 132     <p>@note The StreamableContent interface is particularly useful for saving,
 133       printing, or post-processing entire documents, or for persisting
 134       alternate views of a document.
 135       If document content itself is being serialized, stored, or converted,
 136       then use of the StreamableContent interface can help address performance
 137       issues.  Unlike most AT-SPI/Accessibility interfaces, this interface
 138       is not strongly tied to the current user-agent view of the
 139       a particular document, but may in some cases give access to the
 140       underlying model data.</p>
 141   </tp:docstring>
 142   <method name="getContentTypes">
 143     <tp:docstring>
 144       getContentTypes:
 145     </tp:docstring>
 146     <arg direction="out" type="as" tp:type="StringSeq">
 147     <tp:docstring>
 148       the list of available mimetypes for this object's content.
 149     </tp:docstring>
 150     </arg>
 151   </method>
 152   <method name="getContent">
 153     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 154       <p>\n DEPRECATED, use getStream instead.
 155         getContent:
 156         Retrieve this object's content, in a format appropriate to a
 157         requested mimetype.    </p>
 158
 159       <p>@note the data is returned as an object of type ::Bonobo::Stream.
 160         The primary methods which are supported on Bonobo::Streams for the
 161         purposes of the ::StreamableContent API are \c seek and \c read.
 162         \c seek may not be supported for all mimetypes or
 163         all implementors.    </p>
 164
 165       <p>\verbatim
 166         long Bonobo::Stream:seek (in long offset, in SeekType whence)
 167         raises (NoPermission, IOError)
 168         void Bonobo::Stream:read (in long count, out iobuf buffer)
 169         raises (NoPermission, IOError)
 170         \endverbatim    </p>
 171
 172       <p>@see ::Bonobo::Stream    </p>
 173     </tp:docstring>
 174     <arg direction="in" name="contentType" type="s"/>
 175     <arg direction="out" type="FIXME" tp:type="Bonobo::Stream">
 176     <tp:docstring>
 177       a ::Bonobo::Stream whose mimetype matches \a contentType,if available, or \c NIL.
 178     </tp:docstring>
 179     </arg>
 180   </method>
 181   <method name="getStream">
 182     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 183       <p>Retrieve this object's content, in a format appropriate to a
 184         requested mimetype, as a ::ContentStream instance.    </p>
 185
 186       <p>@note This method supercedes the older getContent method, which
 187         relied on the Bonobo::Stream API.
 188         \c seek may not be supported for all mimetypes or
 189         all implementors.    </p>
 190
 191       <p>@param contentType a string specifying the desired mimetype for the content stream.</p>
 192     </tp:docstring>
 193     <arg direction="in" name="contentType" type="s"/>
 194     <arg direction="out" type="FIXME" tp:type="ContentStream">
 195     <tp:docstring>
 196       a Stream whose mimetype matches \a contentType,if available, or \c NIL.@since AT-SPI 1.8.0
 197     </tp:docstring>
 198     </arg>
 199   </method>
 200   <method name="getURI">
 201     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 202       <p>Get a URI pointing to the content of the specified type, if such a URI
 203         can be obtained.  Not all streamable content providers have URI representations.    </p>
 204
 205       <p>@param contentType a string specifying the desired mimetype for the content stream.
 206         If NULL, then a URI for the default content type will be returned, if available.    </p>
 207     </tp:docstring>
 208     <arg direction="in" name="contentType" type="s"/>
 209     <arg direction="out" type="s">
 210     <tp:docstring>
 211       a string which constitutes a URI for a stream of the specifiedcontent type, or NULL if no such URI can be obtained.
 212     </tp:docstring>
 213     </arg>
 214   </method>
 215   <method name="unImplemented">
 216     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 217       <p>\cond
 218         unImplemented:    </p>
 219
 220       <p>placeholders for future expansion.</p>
 221     </tp:docstring>
 222   </method>
 223   <method name="unImplemented2">
 224   </method>
 225 </interface>
 226 </node>