1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_io_XAsyncOutputMonitor_idl__
25#define __com_sun_star_io_XAsyncOutputMonitor_idl__
26
27#ifndef __com_sun_star_io_IOException_idl__
28#include "com/sun/star/io/IOException.idl"
29#endif
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include "com/sun/star/uno/XInterface.idl"
32#endif
33
34module com { module sun { module star { module io {
35
36/**
37   An optional companion interface to
38   <type scope="com::sun::star::io">XOutputStream</type> that supports scenarios
39   where <member scope="com::sun::star::io">XOutputStream::writeBytes</member>
40   operates asynchronously and does not necessarily report any errors.
41
42   <p>A typical scenario where this interface is useful is when an
43   <type scope="com::sun::star::io">XOutputStream</type> is used to write to a
44   file via NFS.  Normally, any calls to
45   <member scope="com::sun::star::io">XOutputStream::writeBytes</member> will
46   execute asynchronously then, in that any potential errors might only be
47   reported by later calls to
48   <member scope="com::sun::star::io">XOutputStream::writeBytes</member> or
49   <member scope="com::sun::star::io">XOutputStream::closeOutput</member>.  If
50   such an output stream shall not be closed immediately after one or more calls
51   to <member scope="com::sun::star::io">XOutputStream::writeBytes</member>, but
52   the client wants to know as soon as possible whether writing was successful,
53   then <member
54   scope="com::sun::star::io">XAsyncOutputMonitor::waitForCompletion</member>
55   should be called after the series of calls to
56   <member scope="com::sun::star::io">XOutputStream::writeBytes</member>.</p>
57
58   @since OpenOffice 2.0
59*/
60interface XAsyncOutputMonitor {
61    /**
62       waits for the completion of any previous calls to
63       <member scope="com::sun::star::io">XOutputStream::writeBytes</member>,
64       and reports potentially pending errors.
65
66       <p>Calling this method is potentially expensive (even if the associated
67       <type scope="com::sun::star::io">XOutputStream</type> represents a local
68       file not accessed via NFS, for example).  This method has a similar
69       description to
70       <member scope="com::sun::star::io">XOutputStream::flush</member>.
71       However, where the semantics of <code>flush</code> are rather vague,
72       <code>waitForCompletion</code> has very specific semantics&mdash;it just
73       blocks long enough so that any errors encountered during previous calls
74       to <member scope="com::sun::star::io">XOutputStream::writeBytes</member>
75       can reliably be reported.  It specificially does not guarantee that any
76       data have savely been stored on a stable physical medium, like a hard
77       disk (and it is completely unspecified whether <code>flush</code> should
78       give this guarantee).</p>
79
80       @throws com::sun::star::io::IOException
81       if any previous call to <member
82       scope="com::sun::star::io">XOutputStream::writeBytes</member> encountered
83       such an error, but has not yet reported it (in cases where
84       <code>writeBytes</code> operates asynchronously).
85    */
86    void waitForCompletion() raises (IOException);
87};
88
89}; }; }; };
90
91#endif
92