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—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