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