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_ucb_XCommandProcessor_idl__
25cdf0e10cSrcweir#define __com_sun_star_ucb_XCommandProcessor_idl__
26cdf0e10cSrcweir
27cdf0e10cSrcweir#ifndef __com_sun_star_uno_XInterface_idl__
28cdf0e10cSrcweir#include <com/sun/star/uno/XInterface.idl>
29cdf0e10cSrcweir#endif
30cdf0e10cSrcweir
31cdf0e10cSrcweir#ifndef __com_sun_star_ucb_XCommandEnvironment_idl__
32cdf0e10cSrcweir#include <com/sun/star/ucb/XCommandEnvironment.idl>
33cdf0e10cSrcweir#endif
34cdf0e10cSrcweir
35cdf0e10cSrcweir#ifndef __com_sun_star_ucb_Command_idl__
36cdf0e10cSrcweir#include <com/sun/star/ucb/Command.idl>
37cdf0e10cSrcweir#endif
38cdf0e10cSrcweir
39cdf0e10cSrcweir#ifndef __com_sun_star_ucb_CommandAbortedException_idl__
40cdf0e10cSrcweir#include <com/sun/star/ucb/CommandAbortedException.idl>
41cdf0e10cSrcweir#endif
42cdf0e10cSrcweir
43cdf0e10cSrcweir//=============================================================================
44cdf0e10cSrcweir
45cdf0e10cSrcweirmodule com { module sun { module star { module ucb {
46cdf0e10cSrcweir
47cdf0e10cSrcweir//=============================================================================
48cdf0e10cSrcweir/** defines a processor for synchronous commands, which are executed in a
49cdf0e10cSrcweir    specific execution environment.
50cdf0e10cSrcweir
51cdf0e10cSrcweir	@version  1.0
52cdf0e10cSrcweir	@author   Kai Sommerfeld
53cdf0e10cSrcweir
54cdf0e10cSrcweir    @see com::sun::star::ucb::XCommandProcessor2
55cdf0e10cSrcweir    for the improved version of this interface.
56cdf0e10cSrcweir
57cdf0e10cSrcweir	@see	  Command
58cdf0e10cSrcweir	@see      XCommandEnvironment
59cdf0e10cSrcweir	@see      XContent
60cdf0e10cSrcweir*/
61cdf0e10cSrcweirpublished interface XCommandProcessor : com::sun::star::uno::XInterface
62cdf0e10cSrcweir{
63cdf0e10cSrcweir	//-------------------------------------------------------------------------
64cdf0e10cSrcweir	/** creates a unique identifier for a command.
65cdf0e10cSrcweir
66cdf0e10cSrcweir	    <p>This identifier can be used to abort the execution of the command
67cdf0e10cSrcweir		accociated with that identifier. Note that it is generally not
68cdf0e10cSrcweir		necessary to obtain a new id for each command, because commands are
69cdf0e10cSrcweir		executed synchronously. So the id for a command is valid again after a
70cdf0e10cSrcweir		command previously associated with this id has finished. In fact you
71cdf0e10cSrcweir		only should get one identifier per thread and assign it to every
72cdf0e10cSrcweir		command executed by that thread.</p>
73cdf0e10cSrcweir
74cdf0e10cSrcweir        <p>Also, after a call to <member>XCommandProcessor::abort</member>, an
75cdf0e10cSrcweir        identifier should not be used any longer (and instead be released by a
76cdf0e10cSrcweir        call to <member>XCommandProcessor2::releaseCommandIdentifier</member>),
77cdf0e10cSrcweir		because it may well abort <em>all</em> further calls to
78cdf0e10cSrcweir        <member>XCommandProcessor::execute</member>.</p>
79cdf0e10cSrcweir
80cdf0e10cSrcweir        <p>To avoid ever-increasing resource consumption, the identifier
81cdf0e10cSrcweir        should be released via
82cdf0e10cSrcweir        <member>XCommandProcessor2::releaseCommandIdentifier</member>
83cdf0e10cSrcweir        when it is no longer used.</p>
84cdf0e10cSrcweir
85cdf0e10cSrcweir		@returns
86cdf0e10cSrcweir		a command identifier.
87cdf0e10cSrcweir	*/
88cdf0e10cSrcweir	long createCommandIdentifier();
89cdf0e10cSrcweir
90cdf0e10cSrcweir	//-------------------------------------------------------------------------
91cdf0e10cSrcweir	/** executes a command.
92cdf0e10cSrcweir
93cdf0e10cSrcweir		<p>Common command definitions can be found in the soecification of the
94cdf0e10cSrcweir		service	<type>Content</type>.
95cdf0e10cSrcweir
96cdf0e10cSrcweir		@param aCommand
97cdf0e10cSrcweir		is the command to execute.
98cdf0e10cSrcweir
99cdf0e10cSrcweir		@param CommandId
100cdf0e10cSrcweir		is a unique id for the command. This identifier was obtained by calling
101cdf0e10cSrcweir		<member>XCommandProcessor::createCommandIdentifier</member>. A value of
102cdf0e10cSrcweir        zero can be used, if the command never shall be aborted. Different
103cdf0e10cSrcweir        threads MUST NOT share one command identifier (except <code>0</code>).
104cdf0e10cSrcweir        This can easily achieved, if every thread that wants to use an
105cdf0e10cSrcweir        <type>XCommandProcessor</type>, obtains exactly one identifier
106cdf0e10cSrcweir        using <member>XCommandProcessor::createCommandIdentifier</member>.
107cdf0e10cSrcweir        This identifier can be used for every call to
108cdf0e10cSrcweir        <member>XCommandProcessor::execute</member> done by that thread.
109cdf0e10cSrcweir
110cdf0e10cSrcweir		@param Environment
111cdf0e10cSrcweir		is the execution environment.
112cdf0e10cSrcweir
113cdf0e10cSrcweir		@returns
114cdf0e10cSrcweir		the result according to the specification of the command.
115cdf0e10cSrcweir
116cdf0e10cSrcweir		@throws CommandAbortedException
117cdf0e10cSrcweir		to indicate that the command was aborted.
118cdf0e10cSrcweir
119cdf0e10cSrcweir        @throws DuplicateCommandIdentifierException
120cdf0e10cSrcweir        to indicate that two threads tried to use the same command identifier
121cdf0e10cSrcweir
122cdf0e10cSrcweir		@throws Exception
123cdf0e10cSrcweir		if an error occured during the execution of the command.
124cdf0e10cSrcweir	*/
125cdf0e10cSrcweir	any execute( [in] Command aCommand,
126cdf0e10cSrcweir				 [in] long CommandId,
127cdf0e10cSrcweir				 [in] XCommandEnvironment Environment )
128cdf0e10cSrcweir		raises ( com::sun::star::uno::Exception, CommandAbortedException );
129cdf0e10cSrcweir
130cdf0e10cSrcweir	//-------------------------------------------------------------------------
131cdf0e10cSrcweir	/** ends the command associated with the given id.
132cdf0e10cSrcweir
133cdf0e10cSrcweir        <p>Not every command can be aborted. It's up to the implementation
134cdf0e10cSrcweir        to decide whether this method will actually end the processing of
135cdf0e10cSrcweir        the command or simply do nothing.
136cdf0e10cSrcweir
137cdf0e10cSrcweir		@param CommandId
138cdf0e10cSrcweir		is a unique id for the command to abort. This must be the identifier
139cdf0e10cSrcweir		passed to <member>XCommandProcessor::execute</member> for the command
140cdf0e10cSrcweir		to abort.
141cdf0e10cSrcweir	*/
142cdf0e10cSrcweir	[oneway] void abort( [in] long CommandId );
143cdf0e10cSrcweir};
144cdf0e10cSrcweir
145cdf0e10cSrcweir//=============================================================================
146cdf0e10cSrcweir
147cdf0e10cSrcweir}; }; }; };
148cdf0e10cSrcweir
149cdf0e10cSrcweir#endif
150