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