/* -*- 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 frame {

/** can be used to identify office modules.

    @since OOo 2.0
 */
interface XModuleManager : com::sun::star::uno::XInterface
{
    /**
       @short  identifies the given module.

       @details This identifier can then be used at the service ModuleManager
               to get more information about this module.

               For identification the interface com::sun::star::lang::XServiceInfo
               is requested on the given module. Because all module service registrations must be unique
               this value can be queried and checked against the configuration.

               Since OOo 2.3.0 also the optional interface XModule will be used.
               If it exists it will be preferred.

       @param  Module
               Possible objects for this parameter can be the following one:
               <ul>
                   <li>
                       <b>com::sun::star::frame::XFrame</b><br>
                       A frame contains (against a component window) a controller.
                       Such controller represent the module (in case no model exists).
                   </li>
                   <li>
                       <b>com::sun::star::frame::XController</b><br>
                       A controller can be bound to a model. Then the model represent the module.
                       If no model exists - the controller is used for identification.
                   </li>
                   <li>
                       <b>com::sun::star::frame::XModel</b><br>
                       A model represent a module every time and can be used for
                       identification directly.
                   </li>
               </ul>

       @throws com::sun::star::lang::IllegalArgumentException
               if the parameter Module is:
               <ul>
                   <li>an empty one</li>
                   <li>or does not provide one of the needed interface
                       XFrame, XController, XModel</li>
                   <li>or does not provide the needed interface XServiceInfo.</li>
               </ul>

       @throws UnknownModuleException
               if the given module could not be identified.
               Note: If the module represent a XFrame instance with does not contain
               a document, this exception is thrown too!

       @return An identifier for the given module.
               Note: This value varies every time. Error will be transported
               by thrown exceptions!
     */
    string identify( [in] ::com::sun::star::uno::XInterface Module )
        raises(::com::sun::star::lang::IllegalArgumentException,
                                       UnknownModuleException  );


};

}; }; }; };

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