diff options
Diffstat (limited to 'offapi/com/sun/star/task/InteractionHandler.idl')
| -rw-r--r-- | offapi/com/sun/star/task/InteractionHandler.idl | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/offapi/com/sun/star/task/InteractionHandler.idl b/offapi/com/sun/star/task/InteractionHandler.idl new file mode 100644 index 000000000..48f8dd736 --- /dev/null +++ b/offapi/com/sun/star/task/InteractionHandler.idl @@ -0,0 +1,171 @@ +/* -*- 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_task_InteractionHandler_idl__ +#define __com_sun_star_task_InteractionHandler_idl__ + +module com { module sun { module star { + module task { published interface XInteractionHandler2; }; + module awt { published interface XWindow; }; +}; }; }; + +module com { module sun { module star { module task { + +/** An interaction request handler that lets the user handle requests via GUI dialogs. + + <p>The interaction handler service has a number of <a href="#built_in_handler">built-in handlers</a>, responsible + for a lot of well known interactions. Additionally, there's a configuration module which allows to + <a href="#configuring_handlers">configure additional handlers</a>, responsible for arbitrary requests.</a></p> + + <a name="built_in_handler"></a> + <h3>Built-in Handlers</h3> + The following well-known requests can be dealt with by the built-in handlers: + <UL> + <LI>com::sun::star::ucb::AuthenticationRequest</LI> + <LI>com::sun::star::ucb::CertificateValidationRequest</LI> + <LI>com::sun::star::ucb::InteractiveAugmentedIOException*</LI> + <LI>com::sun::star::ucb::InteractiveFileIOException*</LI> + <LI>com::sun::star::ucb::InteractiveIOException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkConnectException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkGeneralException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkOffLineException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkReadException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkResolveNameException*</LI> + <LI>com::sun::star::ucb::InteractiveNetworkWriteException*</LI> + <LI>com::sun::star::ucb::InteractiveWrongMediumException*</LI> + <LI>com::sun::star::task::PasswordRequest</LI> + <LI>com::sun::star::java::WrongJavaVersionException*</LI> + <LI>com::sun::star::task::DocumentMacroConfirmationRequest</LI> + </UL> + The requests marked with an asterisk are only handled if (a) their + continuations match certain restrictions (see below), and (b) the + necessary resource strings are available (this can be exploited by + applications that carry only a subset of all resource files with + them).</P> + + <P>The continuation restrictions are as follows: Let <VAR>C</VAR> be the + subset of the provided continuations that are of type + com::sun::star::task::XInteractionApprove, + com::sun::star::task::XInteractionDisapprove, + com::sun::star::task::XInteractionRetry, or + com::sun::star::task::XInteractionAbort (or of a + derived type). All other continuations are ignored for these requests. + The request is only handled if the set <VAR>C</VAR> is any of the + following: + <UL> + <LI>Abort</LI> + <LI>Retry, Abort</LI> + <LI>Approve</LI> + <LI>Approve, Abort</LI> + <LI>Approve, Disapprove</LI> + <LI>Approve, Disapprove, Abort</LI> + </UL></P> + + <P>An + com::sun::star::ucb::InteractiveAugmentedIOException + carries with it a sequence of arguments, which should be + com::sun::star::beans::PropertyValues. The following + details which properties are interpreted by the interaction handler, + depending on the request's + com::sun::star::ucb::IOErrorCode: + <DL> + <DT><code>"Uri"</code></DT> + <DD>All error codes except + com::sun::star::ucb::IOErrorCode::DIFFERENT_DEVICES. + The URI of the involved resource (a `string`).</DD> + + <DT><code>"ResourceName"</code></DT> + <DD>All error codes except + com::sun::star::ucb::IOErrorCode::DIFFERENT_DEVICES. + A name for the involved resource (a `string`) that might be + more meaningful to the user than the URI. For example, a + (platform-dependent) path notation for file system resources.</DD> + + <DT><code>"ResourceType"</code></DT> + <DD>com::sun::star::ucb::IOErrorCode::DEVICE_NOT_READY + and + com::sun::star::ucb::IOErrorCode::NOT_EXISTING + only. An identifier for the type of resource involved (a + `string`). Currently understood values are + <code>"volume"</code> (e.g., a file system volume) and + <code>"folder"</code> (i.e., a resource that contains other + resources).</DD> + + <DT><code>"Removable"</code></DT> + <DD>com::sun::star::ucb::IOErrorCode::NOT_EXISTING + only. A flag indicating whether the resource resides on a storage + medium that can be removed by the user (a `boolean`).</DD> + + <DT><code>"Folder"</code></DT> + <DD>com::sun::star::ucb::IOErrorCode::CANT_CREATE + only. The name of the folder in which a resource cannot be created (a + `string`).</DD> + + <DT><code>"Volume"</code> and <code>"OtherVolume"</code></DT> + <DD>com::sun::star::ucb::IOErrorCode::DIFFERENT_DEVICES + only. The names of the two volumes involved (two + `string`s).</DD> + </DL></P> + + <a name="configuring_handlers"></a> + <h3>Configuring additional Handlers</h3> + + <p>It is possible to configure additional interaction handlers, to which certain requests can be delegated. The + configuration node <code>/org.openoffice.Interaction/InteractionHandlers</code> is evaluated and respected + by the <code>InteractionHandler</code> implementation.</p> + + <p>A custom interaction handler can declare itself responsible for an arbitrary number of UNO types, specified + by full-qualified type name. Also, for each type, it can specify whether it is responsible for only this particular + type, or all possibly existent derived types.</p> + + <p>Whenever the <code>InteractionHandler</code> encounters a request it cannot fulfill itself, it will examine + the configuration, to find a handler implementation for the request, and delegate it to the first matching + handler.</p> + + <p>If multiple custom interaction handlers declare themselves responsible for the same request type, it is not + defined which handler will actually be invoked. Thus, when deploying a custom interaction handler, ensure + that the types you specify are general enough to cover all requests you want to handle, but also specific + enough to not cover requests which other handlers might be interested in.</p> + */ +published service InteractionHandler : XInteractionHandler2 +{ + /** Creates an instance. + + @param parent denotes the parent window for any GUI dialogs the + interaction handler pops up; may be null. + */ + createWithParent([in] com::sun::star::awt::XWindow parent); + + /** Creates an instance with an additional context. + + @param parent denotes the parent window for any GUI dialogs the + interaction handler pops up; may be null. + + @param context is a textual description of the current context (used, + e.g., as a first line of text in error boxes). + */ + createWithParentAndContext([in] com::sun::star::awt::XWindow parent, [in] string context); +}; + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |