xml/org.freedesktop.atspi.StreamableContent.xml

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