/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */


module com { module sun { module star { module ucb {

/** defines a processor for synchronous commands, which are executed in a
    specific execution environment.

    @version  1.0

    @see com::sun::star::ucb::XCommandProcessor2
    for the improved version of this interface.

    @see      Command
    @see      XCommandEnvironment
    @see      XContent
*/
published interface XCommandProcessor : com::sun::star::uno::XInterface
{
    /** creates a unique identifier for a command.

        <p>This identifier can be used to abort the execution of the command
        associated with that identifier. Note that it is generally not
        necessary to obtain a new id for each command, because commands are
        executed synchronously. So the id for a command is valid again after a
        command previously associated with this id has finished. In fact you
        only should get one identifier per thread and assign it to every
        command executed by that thread.</p>

        <p>Also, after a call to XCommandProcessor::abort(), an
        identifier should not be used any longer (and instead be released by a
        call to XCommandProcessor2::releaseCommandIdentifier()),
        because it may well abort <em>all</em> further calls to
        XCommandProcessor::execute().</p>

        <p>To avoid ever-increasing resource consumption, the identifier
        should be released via
        XCommandProcessor2::releaseCommandIdentifier()
        when it is no longer used.</p>

        @returns
        a command identifier.
    */
    long createCommandIdentifier();

    /** executes a command.

        <p>Common command definitions can be found in the specification of the
        service Content.

        @param aCommand
        is the command to execute.

        @param CommandId
        is a unique id for the command. This identifier was obtained by calling
        XCommandProcessor::createCommandIdentifier(). A value of
        zero can be used, if the command never shall be aborted. Different
        threads MUST NOT share one command identifier (except <code>0</code>).
        This can easily achieved, if every thread that wants to use an
        XCommandProcessor, obtains exactly one identifier
        using XCommandProcessor::createCommandIdentifier().
        This identifier can be used for every call to
        XCommandProcessor::execute() done by that thread.

        @param Environment
        is the execution environment.

        @returns
        the result according to the specification of the command.

        @throws CommandAbortedException
        to indicate that the command was aborted.

        @throws DuplicateCommandIdentifierException
        to indicate that two threads tried to use the same command identifier

        @throws Exception
        if an error occurred during the execution of the command.
    */
    any execute( [in] Command aCommand,
                 [in] long CommandId,
                 [in] XCommandEnvironment Environment )
        raises ( com::sun::star::uno::Exception, CommandAbortedException );

    /** ends the command associated with the given id.

        <p>Not every command can be aborted. It's up to the implementation
        to decide whether this method will actually end the processing of
        the command or simply do nothing.

        @param CommandId
        is a unique id for the command to abort. This must be the identifier
        passed to XCommandProcessor::execute() for the command
        to abort.
    */
    void abort( [in] long CommandId );
};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */