/**
 * Fractal Runtime
 *
 * Copyright (C) 2009 STMicroelectronics
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
 *
 * Contact: mind@ow2.org
 *
 * Authors: Matthieu Leclercq
 */

#include "ErrorCode.idt"

/**
 * A component interface to introspect component interfaces.
 */
interface fractal.api.Component {

  /**
   * Returns an external interface of the component to which this interface
   * belongs.
   *
   * @param interfaceName the name of the external interface that must be
   *      returned.
   * @param interfaceReference (out parameter) the external interface of the
   *      component to which this interface belongs, whose name is equal to the
   *      given name.
   * @return <code>0</code> if the interface exist and has been returned
   *      correctly or {@link FRACTAL_API_NO_SUCH_INTERFACE} if there is no such
   *      interface.
   */
  int getFcInterface(in string interfaceName, out void* interfaceReference);

  /**
   * Returns the names of the external interfaces of the component to which this
   * interface belongs. More precisely, if the given <code>interfaceNames</code>
   * is <code>null</code>, this method returns the number of external 
   * interfaces. If it is not <code>null</code>, this method assumes that the 
   * given array is big enough to contain all the names of the external 
   * interfaces.
   *
   * @param interfaceNames an array into which names of the external
   *      interfaces are copied. Can be <code>null</code>.
   * @return the number of interface names; or
   *      {@link FRACTAL_API_OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int listFcInterfaces(in string interfaceNames[]);

  /**
   * Returns the role of an external interface of the component to which this
   * interface belongs.
   *
   * @param interfaceName the name of an external interface.
   * @return <code>0</code> if the interface exist and is a client interface;
   *      <code>1</code> if the interface exist and is a server interface;
   *      or {@link FRACTAL_API_NO_SUCH_INTERFACE} if there is no such
   *      interface.
   */
  int getFcInterfaceRole(in string interfaceName);
  
  /**
   * Returns the signature of an external interface of the component to which 
   * this interface belongs.
   *
   * @param interfaceName the name of an external interface.
   * @param signature (out parameter) the signature of the external interface of
   *      the component to which this interface belongs, whose name is equal to
   *      the given name.the signature of the external interface.
   * @return <code>0</code> if the interface exist and its signature has been
   *      returned correctly or {@link FRACTAL_API_NO_SUCH_INTERFACE} if there
   *      is no such interface.
   */
  int getFcInterfaceSignature(in string interfaceName,
      out string signature); 

  /**
   * Returns the external interfaces of the component to which this interface
   * belongs. More precisely, if the given <code>interfaceReferences</code> is
   * <code>null</code>, this method returns the number of external interfaces.
   * If it is not <code>null</code>, this method assumes that the given array is
   * big enough to contain all the external interfaces.
   *
   * @param interfaceReferences an array into which references of the external
   *      interfaces are copied. Can be <code>null</code>.
   * @return the number of interface references; or
   *      {@link FRACTAL_API_OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int getFcInterfaces(in void* interfaceReferences[]);
}