pyatspi/streamablecontent.py

   1 #Copyright (C) 2008 Codethink Ltd
   2
   3
   4 #modify it under the terms of the GNU Lesser General Public
   5 #License version 2 as published by the Free Software Foundation.
   6
   7 #This program is distributed in the hope that it will be useful,
   8 #but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 #GNU General Public License for more details.
  11 #You should have received a copy of the GNU Lesser General Public License
  12 #along with this program; if not, write to the Free Software
  13 #Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  14
  15 from interfaces import *
  16 from base import BaseProxy, Enum
  17 from accessible import Accessible
  18 from factory import accessible_factory
  19
  20 __all__ = [
  21            "ContentStream",
  22            "StreamableContent",
  23           ]
  24
  25 #------------------------------------------------------------------------------
  26
  27 class ContentStream(BaseProxy):
  28         """
  29         An interface by which the requested data from a StreamableContent
  30         object may be read by the client.
  31         """
  32
  33         def close(self, *args, **kwargs):
  34                 """
  35                 close the stream and release associated resources. A client should
  36                 not perform further operations on a StreamableContent::Stream
  37                 object after closing it.
  38                 """
  39                 func = self.get_dbus_method("close", dbus_interface=ATSPI_STREAMABLE_CONTENT)
  40                 return func(*args, **kwargs)
  41
  42         def read(self, *args, **kwargs):
  43                 """
  44                 Request/read a specified amount of data from a Stream.
  45                 @return the number of bytes actually read into the client buffer.
  46                 """
  47                 func = self.get_dbus_method("read", dbus_interface=ATSPI_STREAMABLE_CONTENT)
  48                 return func(*args, **kwargs)
  49
  50         def seek(self, *args, **kwargs):
  51                 """
  52                 Seek to a specified position in the Stream.
  53                 @param : offset
  54                 an offset specifying the requested position in the stream, relative
  55                 to the SeekType specified in whence.
  56                 @param : whence
  57                 a SeekType specifying the reference point from which the seek
  58                 offset is calculated. Some forms of seek are not supported by
  59                 certain implementations of Stream, in which case a NotSupported
  60                 exception will be raised.
  61                 @return the actual resulting offset, if no exception was raised.
  62                 """
  63                 func = self.get_dbus_method("seek", dbus_interface=ATSPI_STREAMABLE_CONTENT)
  64                 return func(*args, **kwargs)
  65
  66         class IOError(Exception):
  67                 pass
  68
  69         class NoPermission(Exception):
  70                 pass
  71
  72         class NotSupported(Exception):
  73                 pass
  74
  75         class SeekType(Enum):
  76                 """
  77                 Specifies the meaning of a seek 'offset'. Not all SeekTypes are
  78                 supported by all StreamableContent data sources, for instance
  79                 some streams may not support seeking from the beginning or other
  80                 types of 'backwards' seeks.
  81                 """
  82                 _enum_lookup = {
  83                         0:'SEEK_SET',
  84                         1:'SEEK_CURRENT',
  85                         2:'SEEK_END',
  86                 }
  87
  88         SEEK_CURRENT = SeekType(1)
  89         SEEK_END = SeekType(2)
  90         SEEK_SET = SeekType(0)
  91
  92 #------------------------------------------------------------------------------
  93
  94 class StreamableContent(Accessible):
  95         """
  96         An interface whereby an object allows its backing content to
  97         be streamed to clients. Negotiation of content type is allowed.
  98         Clients may examine the backing data and transform, convert,
  99         or parse the content in order to present it in an alternate form
 100         to end-users.
 101         """
 102
 103         def getContent(self, *args, **kwargs):
 104                 """
 105                 DEPRECATED, use getStream instead.
 106                 """
 107                 func = self.get_dbus_method("getContent", dbus_interface=ATSPI_STREAMABLE_CONTENT)
 108                 return func(*args, **kwargs)
 109
 110         def getContentTypes(self, *args, **kwargs):
 111                 """
 112                 getContentTypes:
 113                 @return the list of available mimetypes for this object's content.
 114                 """
 115                 func = self.get_dbus_method("getContentTypes", dbus_interface=ATSPI_STREAMABLE_CONTENT)
 116                 return func(*args, **kwargs)
 117
 118         def getStream(self, *args, **kwargs):
 119                 """
 120                 Retrieve this object's content, in a format appropriate to a
 121                 requested mimetype, as a ContentStream instance.
 122                 @param : contentType
 123                 a string specifying the desired mimetype for the content stream.
 124                 @return a Stream whose mimetype matches contentType, if available,
 125                 or NIL.
 126                 """
 127                 func = self.get_dbus_method("getStream", dbus_interface=ATSPI_STREAMABLE_CONTENT)
 128                 return func(*args, **kwargs)
 129
 130         def getURI(self, *args, **kwargs):
 131                 """
 132                 Get a URI pointing to the content of the specified type, if such
 133                 a URI can be obtained. Not all streamable content providers have
 134                 URI representations.
 135                 @param : contentType
 136                 a string specifying the desired mimetype for the content stream.
 137                 If NULL, then a URI for the default content type will be returned,
 138                 if available.
 139                 @return a string which constitutes a URI for a stream of the
 140                 specified content type, or NULL if no such URI can be obtained.
 141                 """
 142                 func = self.get_dbus_method("getURI", dbus_interface=ATSPI_STREAMABLE_CONTENT)
 143                 return func(*args, **kwargs)
 144
 145 # Register the accessible class with the factory.
 146 accessible_factory.register_accessible_class(ATSPI_STREAMABLE_CONTENT, StreamableContent)
 147
 148 #END----------------------------------------------------------------------------