info/SRC680 CWS kso13 : New UNO interface com.sun.star.io.AsyncOutputMonitor

Type
info

Title
New UNO interface com.sun.star.io.AsyncOutputMonitor

Posted by
[email protected]

Affected
,.

Effective from
SRC680 CWS kso13

Summary

+ com.sun.star.io.AsyncOutputMonitor

Description

module com { module sun { module star { module io {

/**
An optional companion interface to
<type scope="com::sun::star::io">XOutputStream</type> that supports
scenarios
where <member
scope="com::sun::star::io">XOutputStream::writeBytes</member>
operates asynchronously and does not necessarily report any errors.

<p>A typical scenario where this interface is useful is when an
<type scope="com::sun::star::io">XOutputStream</type> is used to
write to a
file via NFS. Normally, any calls to
<member
scope="com::sun::star::io">XOutputStream::writeBytes</member> will
execute asynchronously then, in that any potential errors might only be
reported by later calls to
<member
scope="com::sun::star::io">XOutputStream::writeBytes</member> or
<member
scope="com::sun::star::io">XOutputStream::closeOutput</member>. If
such an output stream shall not be closed immediately after one or
more calls
to <member
scope="com::sun::star::io">XOutputStream::writeBytes</member>, but
the client wants to know as soon as possible whether writing was
successful,
then <member

scope="com::sun::star::io">XAsyncOutputMonitor::waitForCompletion</member>
should be called after the series of calls to
<member
scope="com::sun::star::io">XOutputStream::writeBytes</member>.</p>

@since OOo2.0.0
*/
interface XAsyncOutputMonitor {
/**
waits for the completion of any previous calls to
<member
scope="com::sun::star::io">XOutputStream::writeBytes</member>,
and reports potentially pending errors.

<p>Calling this method is potentially expensive (even if the
associated
<type scope="com::sun::star::io">XOutputStream</type>
represents a local
file not accessed via NFS, for example). This method has a similar
description to
<member scope="com::sun::star::io">XOutputStream::flush</member>.
However, where the semantics of <code>flush</code> are rather
vague,
<code>waitForCompletion</code> has very specific
semantics&mdash;it just
blocks long enough so that any errors encountered during
previous calls
to <member
scope="com::sun::star::io">XOutputStream::writeBytes</member>
can reliably be reported. It specificially does not guarantee
that any
data have savely been stored on a stable physical medium, like
a hard
disk (and it is completely unspecified whether
<code>flush</code> should
give this guarantee).</p>

@throws com::sun::star::io::IOException
if any previous call to <member
scope="com::sun::star::io">XOutputStream::writeBytes</member>
encountered
such an error, but has not yet reported it (in cases where
<code>writeBytes</code> operates asynchronously).
*/
void waitForCompletion() raises (IOException);
};

}; }; }; };

---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]