offapi/com/sun/star/task/InteractionHandler.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: InteractionHandler.idl,v $
  10  * $Revision: 1.11 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_task_InteractionHandler_idl__
  32 #define __com_sun_star_task_InteractionHandler_idl__
  33
  34 module com { module sun { module star {
  35     module lang { published interface XInitialization; };
  36     module task { published interface XInteractionHandler; };
  37 }; }; };
  38
  39 module com { module sun { module star { module task {
  40
  41 //============================================================================
  42 /** An interaction request handler that lets the user handle a number of well
  43     known requests via GUI dialogs (and the
  44     <type scope="com::sun::star::task">PasswordContainer</type> service).
  45
  46     <P>The well known requests handled by this service include
  47     <UL>
  48         <LI><type scope="com::sun::star::ucb">AuthenticationRequest</type></LI>
  49         <LI><type scope="com::sun::star::ucb">CertificateValidationRequest</type></LI>
  50         <LI><type scope="com::sun::star::sync2">BadPartnershipException</type>*</LI>
  51         <LI><type scope="com::sun::star::ucb">HandleCookiesRequest</type></LI>
  52         <LI><type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type>*</LI>
  53         <LI><type scope="com::sun::star::ucb">InteractiveCHAOSException</type>*</LI>
  54         <LI><type scope="com::sun::star::ucb">InteractiveFileIOException</type>*</LI>
  55         <LI><type scope="com::sun::star::ucb">InteractiveIOException</type>*</LI>
  56         <LI><type scope="com::sun::star::ucb">InteractiveNetworkConnectException</type>*</LI>
  57         <LI><type scope="com::sun::star::ucb">InteractiveNetworkException</type>*</LI>
  58         <LI><type scope="com::sun::star::ucb">InteractiveNetworkGeneralException</type>*</LI>
  59         <LI><type scope="com::sun::star::ucb">InteractiveNetworkOffLineException</type>*</LI>
  60         <LI><type scope="com::sun::star::ucb">InteractiveNetworkReadException</type>*</LI>
  61         <LI><type scope="com::sun::star::ucb">InteractiveNetworkResolveNameException</type>*</LI>
  62         <LI><type scope="com::sun::star::ucb">InteractiveNetworkWriteException</type>*</LI>
  63         <LI><type scope="com::sun::star::ucb">InteractiveWrongMediumException</type>*</LI>
  64         <LI><type scope="com::sun::star::task">PasswordRequest</type></LI>
  65         <LI><type scope="com::sun::star::java">WrongJavaVersionException</type>*</LI>
  66         <LI><type scope="com::sun::star::task">DocumentMacroConfirmationRequest</type></LI>
  67     </UL>
  68     The requests marked with an asterisk are only handled if (a) their
  69     continuations match certain restrictions (see below), and (b) the
  70     necessary resource strings are available (this can be exploited by
  71     applications that carry only a subset of all resource files with
  72     them).</P>
  73
  74     <P>The continuation restrictions are as follows:  Let <VAR>C</VAR> be the
  75     subset of the provided continuations that are of type
  76     <type scope="com::sun::star::task">XInteractionApprove</type>,
  77     <type scope="com::sun::star::task">XInteractionDisapprove</type>,
  78     <type scope="com::sun::star::task">XInteractionRetry</type>, or
  79     <type scope="com::sun::star::task">XInteractionAbort</type> (or of a
  80     derived type).  All other continuations are ignored for these requests.
  81     The request is only handled if the set <VAR>C</VAR> is any of the
  82     following:
  83     <UL>
  84         <LI>Abort</LI>
  85         <LI>Retry, Abort</LI>
  86         <LI>Approve</LI>
  87         <LI>Approve, Abort</LI>
  88         <LI>Approve, Disapprove</LI>
  89         <LI>Approve, Disapprove, Abort</LI>
  90     </UL></P>
  91
  92     <P>An
  93     <type scope="com::sun::star::ucb">InteractiveAugmentedIOException</type>
  94     carries with it a sequence of arguments, which should be
  95     <type scope="com::sun::star::beans">PropertyValue</type>s.  The following
  96     details which properties are interpreted by the interaction handler,
  97     depending on the request's
  98     <type scope="com::sun::star::ucb">IOErrorCode</type>:
  99     <DL>
 100         <DT><code>"Uri"</code></DT>
 101         <DD>All error codes except
 102         <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>.
 103         The URI of the involved resource (a <atom>string</atom>).</DD>
 104
 105         <DT><code>"ResourceName"</code></DT>
 106         <DD>All error codes except
 107         <const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>.
 108         A name for the involved resource (a <atom>string</atom>) that might be
 109         more meaningful to the user than the URI.  For example, a
 110         (platform-dependent) path notation for file system resources.</DD>
 111
 112         <DT><code>"ResourceType"</code></DT>
 113         <DD><const scope="com::sun::star::ucb">IOErrorCode::DEVICE_NOT_READY</const>
 114         and
 115         <const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const>
 116         only.  An identifier for the type of resource involved (a
 117         <atom>string</atom>).  Currently understood values are
 118         <code>"volume"</code> (e.g., a file system volume) and
 119         <code>"folder"</code> (i.e., a resource that contains other
 120         resources).</DD>
 121
 122         <DT><code>"Removable"</code></DT>
 123         <DD><const scope="com::sun::star::ucb">IOErrorCode::NOT_EXISTING</const>
 124         only.  A flag indicating whether the resource resides on a storage
 125         medium that can be removed by the user (a <atom>boolean</atom>).</DD>
 126
 127         <DT><code>"Folder"</code></DT>
 128         <DD><const scope="com::sun::star::ucb">IOErrorCode::CANT_CREATE</const>
 129         only.  The name of the foler in which a resource cannot be created (a
 130         <atom>string</atom>).</DD>
 131
 132         <DT><code>"Volume"</code> and <code>"OtherVolume"</code></DT>
 133         <DD><const scope="com::sun::star::ucb">IOErrorCode::DIFFERENT_DEVICES</const>
 134         only.  The names of the two volumes involved (two
 135         <atom>string</atom>s).</DD>
 136     </DL></P>
 137  */
 138 published service InteractionHandler
 139 {
 140     //------------------------------------------------------------------------
 141     /** Handle an interaction request.
 142      */
 143     interface com::sun::star::task::XInteractionHandler;
 144
 145     //------------------------------------------------------------------------
 146     /** Initialize the interaction handler.
 147
 148         <P>The arguments must be a sequence of
 149         <type scope="com::sun::star::beans">PropertyValue</type>s.  The
 150         currently supported properties are:
 151         <UL>
 152             <LI><code>"Parent"</code> of type
 153             <type scope="com::sun::star::awt">XWindow</type> denotes the
 154             parent window for any GUI dialogs the interaction handler pops up;
 155             it is strongly recommended that this property is supplied;</LI>
 156             <LI><code>"Context"</code> of type <atom>string</atom> is a
 157             textual description of the current context (used, e.g., as a first
 158             line of text in error boxes); this property is optional.</LI>
 159         </UL></P>
 160      */
 161     interface com::sun::star::lang::XInitialization;
 162 };
 163
 164 }; }; }; };
 165
 166 #endif