pyatspi/streamablecontent.py

   1 #Copyright (C) 2008 Codethink Ltd
   2
   3 #This library is free software; you can redistribute it and/or
   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
  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     def unimplemented(self, *args, **kwargs):
  66         """
  67         /cond
  68         """
  69         func = self.get_dbus_method("unimplemented")
  70         return func(*args, **kwargs)
  71
  72     def unimplemented2(self, *args, **kwargs):
  73         func = self.get_dbus_method("unimplemented2")
  74         return func(*args, **kwargs)
  75
  76     class IOError(Exception):
  77         pass
  78
  79     class NoPermission(Exception):
  80         pass
  81
  82     class NotSupported(Exception):
  83         pass
  84
  85     class SeekType(_Enum):
  86         """
  87         Specifies the meaning of a seek 'offset'. Not all SeekTypes are
  88         supported by all StreamableContent data sources, for instance
  89         some streams may not support seeking from the beginning or other
  90         types of 'backwards' seeks.
  91         """
  92         _enum_lookup = {
  93             0:'SEEK_SET',
  94             1:'SEEK_CURRENT',
  95             2:'SEEK_END',
  96         }
  97
  98     SEEK_CURRENT = SeekType(1)
  99
 100     SEEK_END = SeekType(2)
 101
 102     SEEK_SET = SeekType(0)
 103
 104 #------------------------------------------------------------------------------
 105
 106 class StreamableContent(BaseProxy):
 107     """
 108     An interface whereby an object allows its backing content to
 109     be streamed to clients. Negotiation of content type is allowed.
 110     Clients may examine the backing data and transform, convert,
 111     or parse the content in order to present it in an alternate form
 112     to end-users.
 113     """
 114
 115     def getContent(self, *args, **kwargs):
 116         """
 117         DEPRECATED, use getStream instead. getContent: Retrieve this
 118         object's content, in a format appropriate to a requested mimetype.
 119                 long Bonobo::Stream:seek (in long offset, in SeekType
 120         whence)
 121                         raises (NoPermission, IOError)
 122                 void Bonobo::Stream:read (in long count, out iobuf buffer)
 123                         raises (NoPermission, IOError)
 124
 125         @return a Bonobo::Stream whose mimetype matches contentType,
 126         if available, or NIL.
 127         """
 128         func = self.get_dbus_method("getContent")
 129         return func(*args, **kwargs)
 130
 131     def getContentTypes(self, *args, **kwargs):
 132         """
 133         getContentTypes:
 134         @return the list of available mimetypes for this object's content.
 135         """
 136         func = self.get_dbus_method("getContentTypes")
 137         return func(*args, **kwargs)
 138
 139     def getStream(self, *args, **kwargs):
 140         """
 141         Retrieve this object's content, in a format appropriate to a
 142         requested mimetype, as a ContentStream instance.
 143         @param : contentType
 144         a string specifying the desired mimetype for the content stream.
 145         @return a Stream whose mimetype matches contentType, if available,
 146         or NIL.
 147         """
 148         func = self.get_dbus_method("getStream")
 149         return func(*args, **kwargs)
 150
 151     def getURI(self, *args, **kwargs):
 152         """
 153         Get a URI pointing to the content of the specified type, if such
 154         a URI can be obtained. Not all streamable content providers have
 155         URI representations.
 156         @param : contentType
 157         a string specifying the desired mimetype for the content stream.
 158         If NULL, then a URI for the default content type will be returned,
 159         if available.
 160         @return a string which constitutes a URI for a stream of the
 161         specified content type, or NULL if no such URI can be obtained.
 162         """
 163         func = self.get_dbus_method("getURI")
 164         return func(*args, **kwargs)
 165
 166 # ATTENTION - Register the Application class with the accessible factory.
 167 add_accessible_class(interfaces.ATSPI_STREAMABLE_CONTENT, StreamableContent)
 168
 169 #END----------------------------------------------------------------------------