diff options
Diffstat (limited to 'udkapi/com/sun/star/io/XInputStream.idl')
| -rw-r--r-- | udkapi/com/sun/star/io/XInputStream.idl | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/udkapi/com/sun/star/io/XInputStream.idl b/udkapi/com/sun/star/io/XInputStream.idl new file mode 100644 index 000000000..c4fa25eb8 --- /dev/null +++ b/udkapi/com/sun/star/io/XInputStream.idl @@ -0,0 +1,145 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_io_XInputStream_idl__ +#define __com_sun_star_io_XInputStream_idl__ + +#include <com/sun/star/uno/XInterface.idl> + +#include <com/sun/star/io/NotConnectedException.idl> + +#include <com/sun/star/io/BufferSizeExceededException.idl> + + + +module com { module sun { module star { module io { + +/** This is the basic interface to read data from a stream. + <p> + See the <a href="http://udk.openoffice.org/common/man/concept/streams.html"> + streaming document</a> for further information on chaining and piping streams. + */ +published interface XInputStream: com::sun::star::uno::XInterface +{ + /** reads the specified number of bytes in the given sequence. + + <p>The return value specifies the number of bytes which have been + put into the sequence. A difference between <var>nBytesToRead</var> + and the return value indicates that EOF has been reached. This means + that the method blocks until the specified number of bytes are + available or the EOF is reached. </p> + + @param aData + after the call, the byte sequence contains the requested number + of bytes (or less as a sign of EOF). + <br> + C++ only : Note that for unbridged (e.g., in-process) + calls, using the same sequence for repetitive readBytes()-calls + can bear a performance advantage. The callee can put the data + directly into the sequence so that no buffer reallocation is + necessary. + But this holds only when + <ol> + <li> neither caller nor callee keep a second reference to the same + sequence. + <li> the sequence is pre-allocated with the requested number of bytes. + <li> the same sequence is reused (simply preallocating a new + sequence for every call bears no advantage). + <li> the call is not bridged (e.g., between different compilers + or different processes). + </ol> + <br> + If the same 'optimized' code runs against an interface in a different process, + there is an unnecessary memory allocation/deallocation (the out parameter + is of course NOT transported over the connection), but this should + be negligible compared to a synchron call. + + @param nBytesToRead + the total number of bytes to read + */ + long readBytes( [out] sequence<byte> aData, + [in] long nBytesToRead ) + raises( com::sun::star::io::NotConnectedException, + com::sun::star::io::BufferSizeExceededException, + com::sun::star::io::IOException); + + /** reads the available number of bytes, at maximum + <var>nMaxBytesToRead</var>. + + <p>This method is very similar to the readBytes method, except that + it has different blocking behaviour. + The method blocks as long as at least 1 byte is available or + EOF has been reached. EOF has only been reached, when the method + returns 0 and the corresponding byte sequence is empty. + Otherwise, after the call, aData contains the available, + but no more than nMaxBytesToRead, bytes. + + @param aData contains the data read from the stream. + @param nMaxBytesToRead The maximum number of bytes to be read from this + stream during the call. + @see com::sun::star::io::XInputStream::readBytes + */ + long readSomeBytes( [out] sequence<byte> aData, + [in] long nMaxBytesToRead ) + raises( com::sun::star::io::NotConnectedException, + com::sun::star::io::BufferSizeExceededException, + com::sun::star::io::IOException ); + + /** skips the next <var>nBytesToSkip</var> bytes (must be positive). + + <p>It is up to the implementation whether this method is + blocking the thread or not. </p> + + @param nBytesToSkip + number of bytes to skip + */ + void skipBytes( [in] long nBytesToSkip ) + raises( com::sun::star::io::NotConnectedException, + com::sun::star::io::BufferSizeExceededException, + com::sun::star::io::IOException ); + + /** states how many bytes can be read or skipped without blocking. + + <p>Note: This method offers no information on whether the EOF + has been reached. </p> + */ + long available() + raises( com::sun::star::io::NotConnectedException, + com::sun::star::io::IOException + ); + + /** closes the stream. + + <p>Users must close the stream explicitly when no further + reading should be done. (There may exist ring references to + chained objects that can only be released during this call. + Thus not calling this method would result in a leak of memory or + external resources.) </p> + */ + void closeInput() + raises( com::sun::star::io::NotConnectedException, + com::sun::star::io::IOException); + +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |