summaryrefslogtreecommitdiffstats
path: root/udkapi/com/sun/star/io/XInputStream.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--udkapi/com/sun/star/io/XInputStream.idl145
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: */