| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| |
| #ifndef __com_sun_star_task_InteractionHandler_idl__ |
| #define __com_sun_star_task_InteractionHandler_idl__ |
| |
| module com { module sun { module star { |
| module lang { published interface XInitialization; }; |
| module task { published interface XInteractionHandler; }; |
| }; }; }; |
| |
| 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 numerof 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><type scope="com::sun::star::ucb">AuthenticationRequest</type></LI> |
| <LI><type scope="com::sun::star::ucb">CertificateValidationRequest</type></LI> |
| <LI><type scope="com::sun::star::sync2">BadPartnershipException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">HandleCookiesRequest</type></LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveCHAOSException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveFileIOException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveIOException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkConnectException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkGeneralException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkOffLineException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkReadException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkResolveNameException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveNetworkWriteException</type>*</LI> |
| <LI><type scope="com::sun::star::ucb">InteractiveWrongMediumException</type>*</LI> |
| <LI><type scope="com::sun::star::task">PasswordRequest</type></LI> |
| <LI><type scope="com::sun::star::java">WrongJavaVersionException</type>*</LI> |
| <LI><type scope="com::sun::star::task">DocumentMacroConfirmationRequest</type></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 |
| <type scope="com::sun::star::task">XInteractionApprove</type>, |
| <type scope="com::sun::star::task">XInteractionDisapprove</type>, |
| <type scope="com::sun::star::task">XInteractionRetry</type>, or |
| <type scope="com::sun::star::task">XInteractionAbort</type> (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 |
| <type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type> |
| carries with it a sequence of arguments, which should be |
| <type scope="com::sun::star::beans">PropertyValue</type>s. The following |
| details which properties are interpreted by the interaction handler, |
| depending on the request's |
| <type scope="com::sun::star::ucb">IOErrorCode</type>: |
| <DL> |
| <DT><code>"Uri"</code></DT> |
| <DD>All error codes except |
| <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>. |
| The URI of the involved resource (a <atom>string</atom>).</DD> |
| |
| <DT><code>"ResourceName"</code></DT> |
| <DD>All error codes except |
| <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>. |
| A name for the involved resource (a <atom>string</atom>) 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><const scope="com::sun::star::ucb">IOErrorCode::DEVICE_NOT_READY</const> |
| and |
| <const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const> |
| only. An identifier for the type of resource involved (a |
| <atom>string</atom>). 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><const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const> |
| only. A flag indicating whether the resource resides on a storage |
| medium that can be removed by the user (a <atom>boolean</atom>).</DD> |
| |
| <DT><code>"Folder"</code></DT> |
| <DD><const scope="com::sun::star::ucb">IOErrorCode::CANT_CREATE</const> |
| only. The name of the foler in which a resource cannot be created (a |
| <atom>string</atom>).</DD> |
| |
| <DT><code>"Volume"</code> and <code>"OtherVolume"</code></DT> |
| <DD><const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const> |
| only. The names of the two volumes involved (two |
| <atom>string</atom>s).</DD> |
| </DL></P> |
| |
| <a name="configuring_handlers"></a> |
| <h3>Configurating 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> encounteres 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 themself responsible for the same request type, it is not |
| defined which handler will actully 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 |
| { |
| //------------------------------------------------------------------------ |
| /** Handle an interaction request. |
| */ |
| interface com::sun::star::task::XInteractionHandler; |
| |
| //------------------------------------------------------------------------ |
| /** Initialize the interaction handler. |
| |
| <P>The arguments must be a sequence of |
| <type scope="com::sun::star::beans">PropertyValue</type>s. The |
| currently supported properties are: |
| <UL> |
| <LI><code>"Parent"</code> of type |
| <type scope="com::sun::star::awt">XWindow</type> denotes the |
| parent window for any GUI dialogs the interaction handler pops up; |
| it is strongly recommended that this property is supplied;</LI> |
| <LI><code>"Context"</code> of type <atom>string</atom> is a |
| textual description of the current context (used, e.g., as a first |
| line of text in error boxes); this property is optional.</LI> |
| </UL></P> |
| */ |
| interface com::sun::star::lang::XInitialization; |
| }; |
| |
| }; }; }; }; |
| |
| #endif |