From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- offapi/com/sun/star/util/XCloseable.idl | 120 ++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 offapi/com/sun/star/util/XCloseable.idl (limited to 'offapi/com/sun/star/util/XCloseable.idl') diff --git a/offapi/com/sun/star/util/XCloseable.idl b/offapi/com/sun/star/util/XCloseable.idl new file mode 100644 index 000000000..ad39183c8 --- /dev/null +++ b/offapi/com/sun/star/util/XCloseable.idl @@ -0,0 +1,120 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_util_XCloseable_idl__ +#define __com_sun_star_util_XCloseable_idl__ + +#include +#include + + +module com { module sun { module star { module util { + +/** makes it possible to release any objects in an ordered manner by using + a two-step mechanism + +

+ If an object should be terminated, it can be:
+

    +
  • disposed (if it supports com::sun::star::lang::XComponent::dispose())
    • +
  • closed (if it supports XCloseable::close())
    • +
+ First version gives the object no chance to disagree with that (e.g. if a + process is still running and can't be canceled really). Last version + provides this possibility, but can't guarantee real termination of called object. + It depends from the environment of an object, if one or both mechanism are necessary. +

+ +

+ Base interface XCloseBroadcaster makes it possible that any listener + which is interested on life time of listened object ... +

    +
  • can get a notification about closing of it
    • +
  • or can have a veto to break that.
    • +
+

+ + @see com::sun::star::lang::XComponent::dispose() + @see XCloseBroadcaster + @see XCloseListener + */ +published interface XCloseable: XCloseBroadcaster +{ + /** try to close the object + +

+ Must definitely be called before com::sun::star::lang::XComponent::dispose(). + But nobody can guarantee real closing of called object - because it can disagree with that if any + still running processes can't be canceled yet. It's not allowed to block this call till internal + operations will be finished here. They must be canceled or call must return immediately by throwing + the CloseVetoException. Otherwise (if nothing exist to disagree) it must return normally. +

+ +

+ Before any internal processes will be canceled, all registered XCloseListener + must be notified. Any of them can disagree with a CloseVetoException too. + It's forbidden to catch this exception inside the called close() method because the caller must + get this information! +

+ +

+ If somewhere disagree with a CloseVetoException it will not clear who has to close the object again + after still running processes was finished. The parameter DeliverOwnership regulate that. + If it is set to `FALSE` the caller of the method close() will be the owner of this object in every case. + Then it's not allowed to call close() from any other place (may a registered XCloseListener). + If it is set to `TRUE` the caller gives up his ownership. If a XCloseListener throw the veto exception + he will be the new owner of the closing object. This information is passed to the listener by a parameter of + his notification method XCloseListener::queryClosing(). After his operations was finished + he MUST try to close it again. If the closing object itself disagree by an exception and the parameter + DeliverOwnership was set to `TRUE` the object will be his own owner with all consequences of that. +
Note:
+ There is no way to get the ownership back if it was delivered! +

+ +

+ If this method was already called on an object it should return without any reaction. Normally it's possible to throw + a com::sun::star::lang::DisposedException for already disposed or closed objects + (which represent a com::sun::star::uno::RuntimeException and can be thrown by every interface call), + but it shouldn't be used here. The veto exception should be the only way to indicates the result. +

+ + @param DeliverOwnership + `TRUE` delegates the ownership of this closing object to anyone which throw the CloseVetoException. + This new owner has to close the closing object again if his still running processes will be finished. +
+ `FALSE` let the ownership at the original one which called the close() method. He must react for possible + CloseVetoExceptions and try it again at a later time. This can be useful for a generic UI handling. + + @throws CloseVetoException + indicates that the closing object himself or any of his currently registered listener disagree with this close() request. + + @see XCloseListener + @see CloseVetoException + @see com::sun::star::lang::XComponent::dispose() + @see com::sun::star::lang::DisposedException + */ + void close( [in] boolean DeliverOwnership ) + raises( CloseVetoException ); +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ -- cgit v1.2.3