1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_io_XAsyncOutputMonitor_idl__
29#define __com_sun_star_io_XAsyncOutputMonitor_idl__
30
31#ifndef __com_sun_star_io_IOException_idl__
32#include "com/sun/star/io/IOException.idl"
33#endif
34#ifndef __com_sun_star_uno_XInterface_idl__
35#include "com/sun/star/uno/XInterface.idl"
36#endif
37
38module com { module sun { module star { module io {
39
40/**
41   An optional companion interface to
42   <type scope="com::sun::star::io">XOutputStream</type> that supports scenarios
43   where <member scope="com::sun::star::io">XOutputStream::writeBytes</member>
44   operates asynchronously and does not necessarily report any errors.
45
46   <p>A typical scenario where this interface is useful is when an
47   <type scope="com::sun::star::io">XOutputStream</type> is used to write to a
48   file via NFS.  Normally, any calls to
49   <member scope="com::sun::star::io">XOutputStream::writeBytes</member> will
50   execute asynchronously then, in that any potential errors might only be
51   reported by later calls to
52   <member scope="com::sun::star::io">XOutputStream::writeBytes</member> or
53   <member scope="com::sun::star::io">XOutputStream::closeOutput</member>.  If
54   such an output stream shall not be closed immediately after one or more calls
55   to <member scope="com::sun::star::io">XOutputStream::writeBytes</member>, but
56   the client wants to know as soon as possible whether writing was successful,
57   then <member
58   scope="com::sun::star::io">XAsyncOutputMonitor::waitForCompletion</member>
59   should be called after the series of calls to
60   <member scope="com::sun::star::io">XOutputStream::writeBytes</member>.</p>
61
62   @since OOo 2.0
63*/
64interface XAsyncOutputMonitor {
65    /**
66       waits for the completion of any previous calls to
67       <member scope="com::sun::star::io">XOutputStream::writeBytes</member>,
68       and reports potentially pending errors.
69
70       <p>Calling this method is potentially expensive (even if the associated
71       <type scope="com::sun::star::io">XOutputStream</type> represents a local
72       file not accessed via NFS, for example).  This method has a similar
73       description to
74       <member scope="com::sun::star::io">XOutputStream::flush</member>.
75       However, where the semantics of <code>flush</code> are rather vague,
76       <code>waitForCompletion</code> has very specific semantics&mdash;it just
77       blocks long enough so that any errors encountered during previous calls
78       to <member scope="com::sun::star::io">XOutputStream::writeBytes</member>
79       can reliably be reported.  It specificially does not guarantee that any
80       data have savely been stored on a stable physical medium, like a hard
81       disk (and it is completely unspecified whether <code>flush</code> should
82       give this guarantee).</p>
83
84       @throws com::sun::star::io::IOException
85       if any previous call to <member
86       scope="com::sun::star::io">XOutputStream::writeBytes</member> encountered
87       such an error, but has not yet reported it (in cases where
88       <code>writeBytes</code> operates asynchronously).
89    */
90    void waitForCompletion() raises (IOException);
91};
92
93}; }; }; };
94
95#endif
96