// vi:ft=cpp
/**
 * \file
 * \brief Meta interface for getting dynamic type information
 *        about objects behind capabilities.
 * \ingroup l4_api
 */
/*
 * (c) 2008-2009 Alexander Warg <warg@os.inf.tu-dresden.de>
 *     economic rights: Technische Universität Dresden (Germany)
 *
 * This file is part of TUD:OS and distributed under the terms of the
 * GNU General Public License 2.
 * Please see the COPYING-GPL-2 file for details.
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 */

#pragma once

#include <l4/sys/capability>

namespace L4 {
/**
 * \addtogroup l4_kernel_object_api
 */
/*@{*/

/**
 * \brief Meta interface that shall be implemented by each L4Re object
 *        and gives access to the dynamic type information for
 *        L4Re objects.
 */
class Meta : public Kobject_t<Meta, Kobject, L4_PROTO_META>
{
  L4_KOBJECT(Meta)

public:
  enum Op
  {
    O_num_ifaces = 0,
    O_iface      = 1,
    O_supports   = 2,
  };

  /**
   * \brief Get the number of interfaces implemented by this object.
   * \param utcb is the utcb to use for sending the message.
   * \return The message tag for the operation, the label (l4_msgtag_t::label())
   *         is set to the number of interfaces if successful, or to -error
   *         when an error occured.
   */
  l4_msgtag_t num_interfaces(l4_utcb_t *utcb = l4_utcb()) throw();

  /**
   * \brief Get the protocol number that must be used for the interface with
   *        the index \a idx.
   * \param idx is the index of the interface to get the protocol number for.
   *            \a idx must be \>= 0 and \< the return value of
   *            num_interfaces().
   * \param utcb is the utcb to use for sending the message.
   * \return The message tag for the operation, the label (l4_msgtag_t::label())
   *         is set to the protocol number of interface \a idx.
   */
  l4_msgtag_t interface(int idx, l4_utcb_t *u = l4_utcb()) throw();
  /**
   * \brief Figure out if the object supports the given \a protocol (number).
   * \param protocol is the protocol number to check for.
   * \param utcb is the utcb to use for sending the message.
   * \return The message tag for the operation, the label (l4_msgtag_t::label())
   *         is set to 1 if \a protocol is supported to 0 if not.
   *
   * This method is intended to be used for statically assigned protocol
   * numbers.
   */
  l4_msgtag_t supports(long protocol, l4_utcb_t *u = l4_utcb()) throw();
};

/*@}*/

inline l4_msgtag_t
Meta::num_interfaces(l4_utcb_t *u) throw()
{
  l4_msg_regs_t *mr = l4_utcb_mr_u(u);
  mr->mr[0] = O_num_ifaces;
  return l4_ipc_call(cap(), u, l4_msgtag(Protocol, 1, 0, 0),
                     L4_IPC_NEVER);
}

inline l4_msgtag_t
Meta::interface(int idx, l4_utcb_t *u) throw()
{
  l4_msg_regs_t *mr = l4_utcb_mr_u(u);
  mr->mr[0] = O_iface;
  mr->mr[1] = idx;
  return l4_ipc_call(cap(), u, l4_msgtag(Protocol, 2, 0, 0),
                     L4_IPC_NEVER);
}

inline l4_msgtag_t
Meta::supports(long protocol, l4_utcb_t *u) throw()
{
  l4_msg_regs_t *mr = l4_utcb_mr_u(u);
  mr->mr[0] = O_supports;
  mr->mr[1] = protocol;
  return l4_ipc_call(cap(), u, l4_msgtag(Protocol, 2, 0, 0),
                     L4_IPC_NEVER);
}

}