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, 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
  89     SEEK_END = SeekType(2)
  90
  91     SEEK_SET = SeekType(0)
  92
  93 #------------------------------------------------------------------------------
  94
  95 class StreamableContent(BaseProxy):
  96     """
  97     An interface whereby an object allows its backing content to
  98     be streamed to clients. Negotiation of content type is allowed.
  99     Clients may examine the backing data and transform, convert,
 100     or parse the content in order to present it in an alternate form
 101     to end-users.
 102     """
 103
 104     def getContent(self, *args, **kwargs):
 105         """
 106         DEPRECATED, use getStream instead. getContent: Retrieve this
 107         object's content, in a format appropriate to a requested mimetype.
 108                 long Bonobo::Stream:seek (in long offset, in SeekType
 109         whence)
 110                         raises (NoPermission, IOError)
 111                 void Bonobo::Stream:read (in long count, out iobuf buffer)
 112                         raises (NoPermission, IOError)
 113
 114         @return a Bonobo::Stream whose mimetype matches contentType,
 115         if available, or NIL.
 116         """
 117         func = self.get_dbus_method("getContent")
 118         return func(*args, **kwargs)
 119
 120     def getContentTypes(self, *args, **kwargs):
 121         """
 122         getContentTypes:
 123         @return the list of available mimetypes for this object's content.
 124         """
 125         func = self.get_dbus_method("getContentTypes")
 126         return func(*args, **kwargs)
 127
 128     def getStream(self, *args, **kwargs):
 129         """
 130         Retrieve this object's content, in a format appropriate to a
 131         requested mimetype, as a ContentStream instance.
 132         @param : contentType
 133         a string specifying the desired mimetype for the content stream.
 134         @return a Stream whose mimetype matches contentType, if available,
 135         or NIL.
 136         """
 137         func = self.get_dbus_method("getStream")
 138         return func(*args, **kwargs)
 139
 140     def getURI(self, *args, **kwargs):
 141         """
 142         Get a URI pointing to the content of the specified type, if such
 143         a URI can be obtained. Not all streamable content providers have
 144         URI representations.
 145         @param : contentType
 146         a string specifying the desired mimetype for the content stream.
 147         If NULL, then a URI for the default content type will be returned,
 148         if available.
 149         @return a string which constitutes a URI for a stream of the
 150         specified content type, or NULL if no such URI can be obtained.
 151         """
 152         func = self.get_dbus_method("getURI")
 153         return func(*args, **kwargs)
 154
 155 # ATTENTION - Register the Application class with the accessible factory.
 156 add_accessible_class(interfaces.ATSPI_STREAMABLE_CONTENT, StreamableContent)
 157
 158 #END----------------------------------------------------------------------------