l4/pkg/l4re/include/namespace

   1 // -*- Mode: C++ -*-
   2 // vim:ft=cpp
   3 /**
   4  * \file
   5  * \brief   Namespace interface
   6  */
   7 /*
   8  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   9  *               Alexander Warg <warg@os.inf.tu-dresden.de>,
  10  *               Björn Döbel <doebel@os.inf.tu-dresden.de>
  11  *     economic rights: Technische Universität Dresden (Germany)
  12  *
  13  * This file is part of TUD:OS and distributed under the terms of the
  14  * GNU General Public License 2.
  15  * Please see the COPYING-GPL-2 file for details.
  16  *
  17  * As a special exception, you may use this file as part of a free software
  18  * library without restriction.  Specifically, if other files instantiate
  19  * templates or use macros or inline functions from this file, or you compile
  20  * this file and link it with other files to produce an executable, this
  21  * file does not by itself cause the resulting executable to be covered by
  22  * the GNU General Public License.  This exception does not however
  23  * invalidate any other reasons why the executable file might be covered by
  24  * the GNU General Public License.
  25  */
  26 #pragma once
  27
  28 #include <l4/sys/capability>
  29 #include <l4/re/protocols>
  30
  31 namespace L4Re {
  32
  33 /**
  34  * \defgroup api_l4re_namespace Name-space API
  35  * \ingroup api_l4re
  36  * \brief API for name spaces that store capabilities.
  37  *
  38  * This is a basic abstraction for managing a mapping from
  39  * human-readable names to capabilities. In particular, a name
  40  * can also be mapped to a capability that refers to another name space
  41  * object. By this means name spaces can be constructed hierarchically.
  42  *
  43  * Name spaces play a central role in L4Re, because the implementation of the
  44  * name space objects determine the policy which capabilities (which objects)
  45  * are accessible to a client of a name space.
  46  */
  47 /**
  48  * \brief Name-space interface.
  49  * \ingroup api_l4re_namespace
  50  *
  51  * All name space objects must provide this interface. However, it is not
  52  * mandatory that a name space object allows to register new capabilities.
  53  *
  54  * The name lookup is done iteratively, this means the hierarchical names
  55  * are resolved component wise by the client itself.
  56  */
  57 class L4_EXPORT Namespace :
  58   public L4::Kobject_t<Namespace, L4::Kobject, L4Re::Protocol::Namespace>
  59 {
  60   L4_KOBJECT(Namespace)
  61
  62 public:
  63   /**
  64    * \brief Flags for registering name spaces.
  65    */
  66   enum Register_flags
  67   {
  68     Ro        = L4_CAP_FPAGE_RO,   /**< Read-only */
  69     Rw        = L4_CAP_FPAGE_RW,   /**< Read-write */
  70     Rs        = L4_CAP_FPAGE_RS,
  71     Rws       = L4_CAP_FPAGE_RWS,
  72     Strong    = L4_CAP_FPAGE_S,    /**< Strong */
  73     Trusted   = 0x008,
  74
  75     Cap_flags = Ro | Rw | Strong | Trusted,
  76
  77     Partly_resolved = 0x020,
  78     Link      = 0x100,
  79     Overwrite = 0x200,
  80   };
  81
  82   enum Query_timeout
  83   {
  84     To_default      = 3600000,
  85     To_non_blocking = 0,
  86     To_forever      = ~0,
  87   };
  88
  89   /**
  90    * \brief Query a name.
  91    *
  92    * \param name      String to query
  93    * \param cap       Capability slot to put object into.
  94    * \param timeout   Timeout of query in milliseconds.
  95    * \retval local_id Local id.
  96    *
  97    * \return <0 on failure,
  98    *         see \ref l4_error_code_t.
  99    *         - -#L4_ENOENT
 100    *         - IPC errors
 101    *         == 0 if name could be fully resolved
 102    *          > 0 if name could not be fully resolved
 103    */
 104   long query(char const *name, L4::Cap<void> const &cap,
 105              int timeout = To_default,
 106              l4_umword_t *local_id = 0, bool iterate = true) const throw();
 107
 108   /**
 109    * \brief Query a name.
 110    *
 111    * \param name      String to query
 112    * \param len       Length of the string to query.
 113    * \param cap       Capability slot to put object into.
 114    * \param timeout   Timeout of query in milliseconds.
 115    * \retval local_id Local id.
 116    *
 117    * \return <0 on failure,
 118    *         see \ref l4_error_code_t.
 119    *         - -#L4_ENOENT
 120    *         - IPC errors
 121    *         == 0 if name could be fully resolved
 122    *          > 0 if name could not be fully resolved
 123    */
 124   long query(char const *name, unsigned len, L4::Cap<void> const &cap,
 125              int timeout = To_default,
 126              l4_umword_t *local_id = 0, bool iterate = true) const throw();
 127
 128   /**
 129    * \brief Register an object with a name.
 130    *
 131    * \param name    String to register.
 132    * \param obj     Object to register.
 133    * \param flags   Flags to use, see #Register_flags, default is rw.
 134    *
 135    * \return 0 on success, <0 on failure, see \ref l4_error_code_t.
 136    *         - -#L4_EEXIST
 137    *         - -#L4_EPERM
 138    *         - -#L4_ENOMEM
 139    *         - -#L4_EINVAL
 140    *         - IPC errors
 141    */
 142   long register_obj(char const *name, L4::Cap<void> const &obj,
 143                     unsigned flags = Rw) const throw();
 144
 145   long unlink(char const *name) throw();
 146   long link(char const *name, unsigned len,
 147             L4::Cap<L4Re::Namespace> src_dir,
 148             char const *src_name, unsigned src_len,
 149             unsigned flags = Rw) throw();
 150
 151 private:
 152   long _query(char const *name, unsigned len,
 153               L4::Cap<void> const &target, l4_umword_t *local_id,
 154               bool iterate) const throw();
 155
 156 };
 157
 158 };
 159