X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=idl%2FAccessibility_StreamableContent.idl;h=c38c6470a47c69128f0ad89d4239e08ba9e4dcd6;hb=591c44d8894cdb56f31226422b6f611564e52fb2;hp=13f38056afbe3a71342e42c412f4caf7fd2c48c5;hpb=f762b0286cab88a3895df9c84a6e6990ffdbcbd0;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/idl/Accessibility_StreamableContent.idl b/idl/Accessibility_StreamableContent.idl index 13f3805..c38c647 100644 --- a/idl/Accessibility_StreamableContent.idl +++ b/idl/Accessibility_StreamableContent.idl @@ -26,17 +26,170 @@ module Accessibility { typedef sequence StringSeq; - typedef sequence OctetSeq; + /** + * An interface by which the requested data from a StreamableContent object + * may be read by the client. + * @note this interface supercedes the use of BonoboStream by previous + * versions of StreamableContent. + * + * @since AT-SPI 1.7.0 + */ + interface ContentStream : Bonobo::Unknown { - enum SeekType { - SEEK_START, - SEEK_END, - SEEK_CURRENT + typedef sequence iobuf; + + /** + * Indicates that a transmission error has occurred while + * reading or seeking the stream or data source. + */ + exception IOError { + string reason; + }; + /** + * Indicates that the requested operation is not supported by the stream instance. + */ + exception NotSupported { + string reason; + }; + + /** + * The operation is supported, but the current requestor does not have + * permission to t the request, for instance does not have permission to read + * the stream. + */ + exception NoPermission { + string reason; + }; + + /** + * Specifies the meaning of a seek 'offset'. Not all SeekTypes are + * supported by all StreamableContent data sources, for instance + * some streams may not support seeking from the beginning or other + * types of 'backwards' seeks. + */ + enum SeekType { + SEEK_SET, /**< Seek from the start of the stream or data source.*/ + SEEK_CURRENT, /**< Seek relative to the current position. */ + SEEK_END /**< Seek from the end of the file, stream, or data source. */ + }; + + /** + * Seek to a specified position in the Stream. + * @param offset an offset specifying the requested position in the stream, + * relative to the SeekType specified in \c whence. + * @param whence a SeekType specifying the reference point from which the + * seek offset is calculated. Some forms of seek are not supported by certain + * implementations of Stream, in which case a NotSupported exception will be raised. + * @returns the actual resulting offset, if no exception was raised. + **/ + long seek (in long offset, in SeekType whence) + raises (NoPermission, IOError, NotSupported); + /** + * Request/read a specified amount of data from a Stream. + * @returns the number of bytes actually read into the client buffer. + **/ + long read (in long count, out iobuf buffer) + raises (NoPermission, IOError); + /** + * close the stream and release associated resources. + * A client should not perform further operations on a + * StreamableContent::Stream object after closing it. + **/ + void close (); + + /** /cond */ + void unimplemented (); + void unimplemented2 (); + /** /endcond */ }; - interface StreamableContent { + + /** + * An interface whereby an object allows its backing content + * to be streamed to clients. Negotiation of content type + * is allowed. Clients may examine the backing data and + * transform, convert, or parse the content in order to + * present it in an alternate form to end-users. + * + * @note The StreamableContent interface is particularly useful for saving, + * printing, or post-processing entire documents, or for persisting + * alternate views of a document. + * If document content itself is being serialized, stored, or converted, + * then use of the StreamableContent interface can help address performance + * issues. Unlike most AT-SPI/Accessibility interfaces, this interface + * is not strongly tied to the current user-agent view of the + * a particular document, but may in some cases give access to the + * underlying model data. + */ + interface StreamableContent : Bonobo::Unknown { + + /** + * getContentTypes: + * @returns the list of available mimetypes for this object's content. + */ StringSeq getContentTypes (); + /** + * \n DEPRECATED, use getStream instead. + * getContent: + * Retrieve this object's content, in a format appropriate to a + * requested mimetype. + * + * @note the data is returned as an object of type ::Bonobo::Stream. + * The primary methods which are supported on Bonobo::Streams for the + * purposes of the ::StreamableContent API are \c seek and \c read. + * \c seek may not be supported for all mimetypes or + * all implementors. + * + \verbatim + long Bonobo::Stream:seek (in long offset, in SeekType whence) + raises (NoPermission, IOError) + void Bonobo::Stream:read (in long count, out iobuf buffer) + raises (NoPermission, IOError) + \endverbatim + * + * @see ::Bonobo::Stream + * + * @returns a ::Bonobo::Stream whose mimetype matches \a contentType, + * if available, or \c NIL. + */ Bonobo::Stream getContent (in string contentType); - /* methods used from Bonobo::Stream : seek, read. Others unsupported. */ + + /** + * Retrieve this object's content, in a format appropriate to a + * requested mimetype, as a ::ContentStream instance. + * + * @note This method supercedes the older getContent method, which + * relied on the Bonobo::Stream API. + * \c seek may not be supported for all mimetypes or + * all implementors. + * + * @param contentType a string specifying the desired mimetype for the content stream. + * @returns a Stream whose mimetype matches \a contentType, + * if available, or \c NIL. + * @since AT-SPI 1.8.0 + */ + ContentStream getStream (in string contentType); + + /** + * Get a URI pointing to the content of the specified type, if such a URI + * can be obtained. Not all streamable content providers have URI representations. + * + * @param contentType a string specifying the desired mimetype for the content stream. + * If NULL, then a URI for the default content type will be returned, if available. + * + * @returns a string which constitutes a URI for a stream of the specified + * content type, or NULL if no such URI can be obtained. + */ + string getURI (in string contentType); + /** + * \cond + * unImplemented: + * + * placeholders for future expansion. + */ + void unImplemented (); + void unImplemented2 (); + /** \endcond */ }; + };