142 lines
5.9 KiB
Text
142 lines
5.9 KiB
Text
/* -*- 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).
|
|
|
|
<p>
|
|
C++ only : Note that for unbridged (e.g., in-process)
|
|
calls, using the same sequence for repetive 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 preallocationg a new
|
|
sequence for every call bears no advantage ).
|
|
<li> the call is not bridged (e.g., betweeen different compilers
|
|
or different processes ).
|
|
</ol>
|
|
|
|
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: */
|