1*d1766043SAndrew Rist/************************************************************** 2cdf0e10cSrcweir * 3*d1766043SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4*d1766043SAndrew Rist * or more contributor license agreements. See the NOTICE file 5*d1766043SAndrew Rist * distributed with this work for additional information 6*d1766043SAndrew Rist * regarding copyright ownership. The ASF licenses this file 7*d1766043SAndrew Rist * to you under the Apache License, Version 2.0 (the 8*d1766043SAndrew Rist * "License"); you may not use this file except in compliance 9*d1766043SAndrew Rist * with the License. You may obtain a copy of the License at 10*d1766043SAndrew Rist * 11*d1766043SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12*d1766043SAndrew Rist * 13*d1766043SAndrew Rist * Unless required by applicable law or agreed to in writing, 14*d1766043SAndrew Rist * software distributed under the License is distributed on an 15*d1766043SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*d1766043SAndrew Rist * KIND, either express or implied. See the License for the 17*d1766043SAndrew Rist * specific language governing permissions and limitations 18*d1766043SAndrew Rist * under the License. 19*d1766043SAndrew Rist * 20*d1766043SAndrew Rist *************************************************************/ 21*d1766043SAndrew Rist 22*d1766043SAndrew Rist 23cdf0e10cSrcweir 24cdf0e10cSrcweir#ifndef __com_sun_star_task_InteractionHandler_idl__ 25cdf0e10cSrcweir#define __com_sun_star_task_InteractionHandler_idl__ 26cdf0e10cSrcweir 27cdf0e10cSrcweirmodule com { module sun { module star { 28cdf0e10cSrcweir module lang { published interface XInitialization; }; 29cdf0e10cSrcweir module task { published interface XInteractionHandler; }; 30cdf0e10cSrcweir}; }; }; 31cdf0e10cSrcweir 32cdf0e10cSrcweirmodule com { module sun { module star { module task { 33cdf0e10cSrcweir 34cdf0e10cSrcweir//============================================================================ 35cdf0e10cSrcweir/** An interaction request handler that lets the user handle requests via GUI dialogs. 36cdf0e10cSrcweir 37cdf0e10cSrcweir <p>The interaction handler service has a numerof of <a href="#built_in_handler">built-in handlers</a>, responsible 38cdf0e10cSrcweir for a lot of well known interactions. Additionally, there's a configuration module which allows to 39cdf0e10cSrcweir <a href="#configuring_handlers">configure additional handlers</a>, responsible for arbitrary requests.</a></p> 40cdf0e10cSrcweir 41cdf0e10cSrcweir <a name="built_in_handler"></a> 42cdf0e10cSrcweir <h3>Built-in Handlers</h3> 43cdf0e10cSrcweir The following well-known requests can be dealt with by the built-in handlers: 44cdf0e10cSrcweir <UL> 45cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">AuthenticationRequest</type></LI> 46cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">CertificateValidationRequest</type></LI> 47cdf0e10cSrcweir <LI><type scope="com::sun::star::sync2">BadPartnershipException</type>*</LI> 48cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">HandleCookiesRequest</type></LI> 49cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type>*</LI> 50cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveCHAOSException</type>*</LI> 51cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveFileIOException</type>*</LI> 52cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveIOException</type>*</LI> 53cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkConnectException</type>*</LI> 54cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkException</type>*</LI> 55cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkGeneralException</type>*</LI> 56cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkOffLineException</type>*</LI> 57cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkReadException</type>*</LI> 58cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkResolveNameException</type>*</LI> 59cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveNetworkWriteException</type>*</LI> 60cdf0e10cSrcweir <LI><type scope="com::sun::star::ucb">InteractiveWrongMediumException</type>*</LI> 61cdf0e10cSrcweir <LI><type scope="com::sun::star::task">PasswordRequest</type></LI> 62cdf0e10cSrcweir <LI><type scope="com::sun::star::java">WrongJavaVersionException</type>*</LI> 63cdf0e10cSrcweir <LI><type scope="com::sun::star::task">DocumentMacroConfirmationRequest</type></LI> 64cdf0e10cSrcweir </UL> 65cdf0e10cSrcweir The requests marked with an asterisk are only handled if (a) their 66cdf0e10cSrcweir continuations match certain restrictions (see below), and (b) the 67cdf0e10cSrcweir necessary resource strings are available (this can be exploited by 68cdf0e10cSrcweir applications that carry only a subset of all resource files with 69cdf0e10cSrcweir them).</P> 70cdf0e10cSrcweir 71cdf0e10cSrcweir <P>The continuation restrictions are as follows: Let <VAR>C</VAR> be the 72cdf0e10cSrcweir subset of the provided continuations that are of type 73cdf0e10cSrcweir <type scope="com::sun::star::task">XInteractionApprove</type>, 74cdf0e10cSrcweir <type scope="com::sun::star::task">XInteractionDisapprove</type>, 75cdf0e10cSrcweir <type scope="com::sun::star::task">XInteractionRetry</type>, or 76cdf0e10cSrcweir <type scope="com::sun::star::task">XInteractionAbort</type> (or of a 77cdf0e10cSrcweir derived type). All other continuations are ignored for these requests. 78cdf0e10cSrcweir The request is only handled if the set <VAR>C</VAR> is any of the 79cdf0e10cSrcweir following: 80cdf0e10cSrcweir <UL> 81cdf0e10cSrcweir <LI>Abort</LI> 82cdf0e10cSrcweir <LI>Retry, Abort</LI> 83cdf0e10cSrcweir <LI>Approve</LI> 84cdf0e10cSrcweir <LI>Approve, Abort</LI> 85cdf0e10cSrcweir <LI>Approve, Disapprove</LI> 86cdf0e10cSrcweir <LI>Approve, Disapprove, Abort</LI> 87cdf0e10cSrcweir </UL></P> 88cdf0e10cSrcweir 89cdf0e10cSrcweir <P>An 90cdf0e10cSrcweir <type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type> 91cdf0e10cSrcweir carries with it a sequence of arguments, which should be 92cdf0e10cSrcweir <type scope="com::sun::star::beans">PropertyValue</type>s. The following 93cdf0e10cSrcweir details which properties are interpreted by the interaction handler, 94cdf0e10cSrcweir depending on the request's 95cdf0e10cSrcweir <type scope="com::sun::star::ucb">IOErrorCode</type>: 96cdf0e10cSrcweir <DL> 97cdf0e10cSrcweir <DT><code>"Uri"</code></DT> 98cdf0e10cSrcweir <DD>All error codes except 99cdf0e10cSrcweir <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>. 100cdf0e10cSrcweir The URI of the involved resource (a <atom>string</atom>).</DD> 101cdf0e10cSrcweir 102cdf0e10cSrcweir <DT><code>"ResourceName"</code></DT> 103cdf0e10cSrcweir <DD>All error codes except 104cdf0e10cSrcweir <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>. 105cdf0e10cSrcweir A name for the involved resource (a <atom>string</atom>) that might be 106cdf0e10cSrcweir more meaningful to the user than the URI. For example, a 107cdf0e10cSrcweir (platform-dependent) path notation for file system resources.</DD> 108cdf0e10cSrcweir 109cdf0e10cSrcweir <DT><code>"ResourceType"</code></DT> 110cdf0e10cSrcweir <DD><const scope="com::sun::star::ucb">IOErrorCode::DEVICE_NOT_READY</const> 111cdf0e10cSrcweir and 112cdf0e10cSrcweir <const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const> 113cdf0e10cSrcweir only. An identifier for the type of resource involved (a 114cdf0e10cSrcweir <atom>string</atom>). Currently understood values are 115cdf0e10cSrcweir <code>"volume"</code> (e.g., a file system volume) and 116cdf0e10cSrcweir <code>"folder"</code> (i.e., a resource that contains other 117cdf0e10cSrcweir resources).</DD> 118cdf0e10cSrcweir 119cdf0e10cSrcweir <DT><code>"Removable"</code></DT> 120cdf0e10cSrcweir <DD><const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const> 121cdf0e10cSrcweir only. A flag indicating whether the resource resides on a storage 122cdf0e10cSrcweir medium that can be removed by the user (a <atom>boolean</atom>).</DD> 123cdf0e10cSrcweir 124cdf0e10cSrcweir <DT><code>"Folder"</code></DT> 125cdf0e10cSrcweir <DD><const scope="com::sun::star::ucb">IOErrorCode::CANT_CREATE</const> 126cdf0e10cSrcweir only. The name of the foler in which a resource cannot be created (a 127cdf0e10cSrcweir <atom>string</atom>).</DD> 128cdf0e10cSrcweir 129cdf0e10cSrcweir <DT><code>"Volume"</code> and <code>"OtherVolume"</code></DT> 130cdf0e10cSrcweir <DD><const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const> 131cdf0e10cSrcweir only. The names of the two volumes involved (two 132cdf0e10cSrcweir <atom>string</atom>s).</DD> 133cdf0e10cSrcweir </DL></P> 134cdf0e10cSrcweir 135cdf0e10cSrcweir <a name="configuring_handlers"></a> 136cdf0e10cSrcweir <h3>Configurating additional Handlers</h3> 137cdf0e10cSrcweir 138cdf0e10cSrcweir <p>It is possible to configure additional interaction handlers, to which certain requests can be delegated. The 139cdf0e10cSrcweir configuration node <code>/org.openoffice.Interaction/InteractionHandlers</code> is evaluated and respected 140cdf0e10cSrcweir by the <code>InteractionHandler</code> implementation.</p> 141cdf0e10cSrcweir 142cdf0e10cSrcweir <p>A custom interaction handler can declare itself responsible for an arbitrary number of UNO types, specified 143cdf0e10cSrcweir by full-qualified type name. Also, for each type, it can specify whether it is responsible for only this particular 144cdf0e10cSrcweir type, or all possibly existent derived types.</p> 145cdf0e10cSrcweir 146cdf0e10cSrcweir <p>Whenever the <code>InteractionHandler</code> encounteres a request it cannot fulfill itself, it will examine 147cdf0e10cSrcweir the configuration, to find a handler implementation for the request, and delegate it to the first matching 148cdf0e10cSrcweir handler.</p> 149cdf0e10cSrcweir 150cdf0e10cSrcweir <p>If multiple custom interaction handlers declare themself responsible for the same request type, it is not 151cdf0e10cSrcweir defined which handler will actully be invoked. Thus, when deploying a custom interaction handler, ensure 152cdf0e10cSrcweir that the types you specify are general enough to cover all requests you want to handle, but also specific 153cdf0e10cSrcweir enough to not cover requests which other handlers might be interested in.</p> 154cdf0e10cSrcweir */ 155cdf0e10cSrcweirpublished service InteractionHandler 156cdf0e10cSrcweir{ 157cdf0e10cSrcweir //------------------------------------------------------------------------ 158cdf0e10cSrcweir /** Handle an interaction request. 159cdf0e10cSrcweir */ 160cdf0e10cSrcweir interface com::sun::star::task::XInteractionHandler; 161cdf0e10cSrcweir 162cdf0e10cSrcweir //------------------------------------------------------------------------ 163cdf0e10cSrcweir /** Initialize the interaction handler. 164cdf0e10cSrcweir 165cdf0e10cSrcweir <P>The arguments must be a sequence of 166cdf0e10cSrcweir <type scope="com::sun::star::beans">PropertyValue</type>s. The 167cdf0e10cSrcweir currently supported properties are: 168cdf0e10cSrcweir <UL> 169cdf0e10cSrcweir <LI><code>"Parent"</code> of type 170cdf0e10cSrcweir <type scope="com::sun::star::awt">XWindow</type> denotes the 171cdf0e10cSrcweir parent window for any GUI dialogs the interaction handler pops up; 172cdf0e10cSrcweir it is strongly recommended that this property is supplied;</LI> 173cdf0e10cSrcweir <LI><code>"Context"</code> of type <atom>string</atom> is a 174cdf0e10cSrcweir textual description of the current context (used, e.g., as a first 175cdf0e10cSrcweir line of text in error boxes); this property is optional.</LI> 176cdf0e10cSrcweir </UL></P> 177cdf0e10cSrcweir */ 178cdf0e10cSrcweir interface com::sun::star::lang::XInitialization; 179cdf0e10cSrcweir}; 180cdf0e10cSrcweir 181cdf0e10cSrcweir}; }; }; }; 182cdf0e10cSrcweir 183cdf0e10cSrcweir#endif 184