summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/task/InteractionHandler.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--offapi/com/sun/star/task/InteractionHandler.idl171
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: */