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