package fractal.api;

/**
 * A component interface to control the bindings of the component to which it
 * belongs.
 */
public interface BindingController extends ErrorConst {

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

  /**
   * Returns the interface to which the given client interface is bound. More
   * precisely, returns the server interface to which the client interface whose
   * name is given is bound. This server interface is necessarily in the same
   * address space as the client interface (see {@link #bindFc}).
   *
   * @param clientItfName the name of a client interface of the component to
   *      which this interface belongs.
   * @param interfaceReference (out parameter) the server interface to which the
   *      given interface is bound.
   * @return <code>0</code> if the operation succeed. 
   *      {@link ErrorConst#NO_SUCH_INTERFACE} if there is no such client
   *      interface.
   *      {@link ErrorConst#OPERATION_NOT_SUPPORTED} if this operation is not
   *      supported.
   */
  int lookupFc(const in string clientItfName, out any interfaceReference);

  /**
   * Binds the client interface whose name is given to a server interface. More
   * precisely, binds the client interface of the component to which this
   * interface belongs, and whose name is equal to the given name, to the given
   * server interface. The given server interface must be in the same address
   * space as the client interface.
   *
   * @param clientItfName the name of a client interface of the component to
   *      which this interface belongs.
   * @param serverItf a server interface.
   * @return <code>0</code> if the operation succeed.
   *      {@link ErrorConst#NO_SUCH_INTERFACE} if there is no such client
   *      interface. {@link ErrorConst#ILLEGAL_BINDING} if the binding cannot be
   *      created. {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a
   *      {@link LifeCycleController} interface, but it is not in an appropriate
   *      state to perform this operation.
   */
  int bindFc(const in string clientItfName, in any serverItf);

  /**
   * Unbinds the given client interface. More precisely, unbinds the client
   * interface of the component to which this interface belongs, and whose name
   * is equal to the given name.
   *
   * @param clientItfName the name of a client interface of the component to
   *      which this interface belongs.
   * @return <code>0</code> if the operation succeed. 
   *      {@link ErrorConst#NO_SUCH_INTERFACE} if there is no such client 
   *      interface. {@link ErrorConst#ILLEGAL_BINDING} if the binding cannot be 
   *      removed. {@link ErrorConst#ILLEGAL_LIFE_CYCLE} if this component has a 
   *      {@link LifeCycleController} interface, but it is not in an appropriate 
   *      state to perform this operation.
   */
  int unbindFc(const in string clientItfName);
}