offapi/com/sun/star/ucb/XCommandProcessor.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_ucb_XCommandProcessor_idl__
  21 #define __com_sun_star_ucb_XCommandProcessor_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  25 #include <com/sun/star/ucb/Command.idl>
  26 #include <com/sun/star/ucb/CommandAbortedException.idl>
  27
  28
  29 module com { module sun { module star { module ucb {
  30
  31 /** defines a processor for synchronous commands, which are executed in a
  32     specific execution environment.
  33
  34     @version  1.0
  35     @author   Kai Sommerfeld
  36
  37     @see com::sun::star::ucb::XCommandProcessor2
  38     for the improved version of this interface.
  39
  40     @see      Command
  41     @see      XCommandEnvironment
  42     @see      XContent
  43 */
  44 published interface XCommandProcessor : com::sun::star::uno::XInterface
  45 {
  46     /** creates a unique identifier for a command.
  47
  48         <p>This identifier can be used to abort the execution of the command
  49         associated with that identifier. Note that it is generally not
  50         necessary to obtain a new id for each command, because commands are
  51         executed synchronously. So the id for a command is valid again after a
  52         command previously associated with this id has finished. In fact you
  53         only should get one identifier per thread and assign it to every
  54         command executed by that thread.</p>
  55
  56         <p>Also, after a call to XCommandProcessor::abort(), an
  57         identifier should not be used any longer (and instead be released by a
  58         call to XCommandProcessor2::releaseCommandIdentifier()),
  59         because it may well abort <em>all</em> further calls to
  60         XCommandProcessor::execute().</p>
  61
  62         <p>To avoid ever-increasing resource consumption, the identifier
  63         should be released via
  64         XCommandProcessor2::releaseCommandIdentifier()
  65         when it is no longer used.</p>
  66
  67         @returns
  68         a command identifier.
  69     */
  70     long createCommandIdentifier();
  71
  72     /** executes a command.
  73
  74         <p>Common command definitions can be found in the specification of the
  75         service Content.
  76
  77         @param aCommand
  78         is the command to execute.
  79
  80         @param CommandId
  81         is a unique id for the command. This identifier was obtained by calling
  82         XCommandProcessor::createCommandIdentifier(). A value of
  83         zero can be used, if the command never shall be aborted. Different
  84         threads MUST NOT share one command identifier (except <code>0</code>).
  85         This can easily achieved, if every thread that wants to use an
  86         XCommandProcessor, obtains exactly one identifier
  87         using XCommandProcessor::createCommandIdentifier().
  88         This identifier can be used for every call to
  89         XCommandProcessor::execute() done by that thread.
  90
  91         @param Environment
  92         is the execution environment.
  93
  94         @returns
  95         the result according to the specification of the command.
  96
  97         @throws CommandAbortedException
  98         to indicate that the command was aborted.
  99
 100         @throws DuplicateCommandIdentifierException
 101         to indicate that two threads tried to use the same command identifier
 102
 103         @throws Exception
 104         if an error occurred during the execution of the command.
 105     */
 106     any execute( [in] Command aCommand,
 107                  [in] long CommandId,
 108                  [in] XCommandEnvironment Environment )
 109         raises ( com::sun::star::uno::Exception, CommandAbortedException );
 110
 111     /** ends the command associated with the given id.
 112
 113         <p>Not every command can be aborted. It's up to the implementation
 114         to decide whether this method will actually end the processing of
 115         the command or simply do nothing.
 116
 117         @param CommandId
 118         is a unique id for the command to abort. This must be the identifier
 119         passed to XCommandProcessor::execute() for the command
 120         to abort.
 121     */
 122     void abort( [in] long CommandId );
 123 };
 124
 125
 126 }; }; }; };
 127
 128 #endif
 129
 130 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */