/**
 * 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"

/**
 * Enumeration of the available attribute types.
 */
enum AttributeType {
  INT_ATTR_TYPE,
  STRING_ATTR_TYPE,
  INT8_T_ATTR_TYPE,
  UINT8_T_ATTR_TYPE,
  INT16_T_ATTR_TYPE,
  UINT16_T_ATTR_TYPE,
  INT32_T_ATTR_TYPE,
  UINT32_T_ATTR_TYPE,
  INT64_T_ATTR_TYPE,
  UINT64_T_ATTR_TYPE,
  INTPTR_T_ATTR_TYPE,
  UINTPTR_T_ATTR_TYPE,
  UNKNOWN_ATTR_TYPE
};

/**
 * A component interface to control the attributes of the component to which it
 * belongs.
 */
interface fractal.api.AttributeController {

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

  /**
   * Returns the value of an attribute.
   *
   * @param attributeName the name of the attribute to return.
   * @param value (out parameter) the value of the attribute.
   * @return <code>0</code> if the operation succeed.
   *      {@link FRACTAL_API_NO_SUCH_ATTRIBUTE} if there is no such attribute.
   */
  int getFcAttribute(in string attributeName, out void *value);

  /**
   * Returns the size of an attribute (in byte).
   *
   * @param attributeName the name of the attribute to return.
   * @return the size if the attribute or {@link FRACTAL_API_NO_SUCH_ATTRIBUTE}
   *       if there is no such attribute.
   */
  int getFcAttributeSize(in string attributeName);

  /**
   * Returns the type of an attribute.
   *
   * @param attributeName the name of the attribute to return.
   * @param type (out parameter) the type of the attribute.
   * @return <code>0</code> if the operation succeed.
   *      {@link FRACTAL_API_NO_SUCH_ATTRIBUTE} if there is no such attribute.
   */
  int getFcAttributeType(in string attributeName,
      out enum AttributeType type);

  /**
   * Sets the value of an attribute.
   *
   * @param attributeName the name of the attribute to set.
   * @param value the value of the attribute to set.
   * @return <code>0</code> if the operation succeed.
   *      {@link FRACTAL_API_NO_SUCH_ATTRIBUTE} if there is no such attribute.
   *      {@link FRACTAL_API_ILLEGAL_ATTRIBUTE} if the attribute is not settable.
   *      {@link FRACTAL_API_OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int setFcAttribute(in string attributeName, in void *value);
}
