2 * Copyright Andrey Semashev 2016.
3 * Distributed under the Boost Software License, Version 1.0.
4 * (See accompanying file LICENSE_1_0.txt or copy at
5 * http://www.boost.org/LICENSE_1_0.txt)
8 * \file utility/ipc/object_name.hpp
9 * \author Andrey Semashev
12 * The header contains declaration of a system object name wrapper.
15 #ifndef BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
16 #define BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
18 #include <boost/log/detail/config.hpp>
22 #include <boost/move/core.hpp>
23 #include <boost/log/detail/header.hpp>
25 #ifdef BOOST_HAS_PRAGMA_ONCE
31 BOOST_LOG_OPEN_NAMESPACE
36 * \brief A system object name class
38 * In order to identify a system-wide object such as a shared memory segment or a named synchronization primitive the object has to be given a name.
39 * The format of the name is specific to the operating system and the \c object_name class provides an abstraction for names of objects. It also
40 * provides means for scoping, which allows to avoid name clashes between different processes.
42 * The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:
45 * A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
46 * a b c d e f g h i j k l m n o p q r s t u v w x y z
47 * 0 1 2 3 4 5 6 7 8 9 . _ -
50 * \note The character set corresponds to the POSIX Portable Filename Character Set (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278).
52 * Use of other characters may result in non-portable system-specific behavior.
54 * The name can have one of the following scopes:
56 * \li \c global - objects within this scope are visible to any process on the system. In order to use this scope the process may need to have
57 * extended privileges. This scope is not available for Windows Store applications.
58 * \li \c user - objects within this scope can be opened by processes running under the same user as the current process.
59 * \li \c session - objects within this scope are visible to processes within the session of the current process. The definition of a session may vary between
60 * operating systems. On POSIX, a session is typically a group of processes attached to a single virtual terminal device. On Windows a session is
61 * started when a user logs into the system. There is also a separate session for Windows services.
62 * \li \c process_group - objects within this scope are visible to processes within the process group of the current process. Currently, on Windows all processes
63 * running in the current session are considered members of the same process group. This may change in future.
65 * The scopes are not overlapping. For instance, if an object is created in the global scope, the object cannot be opened with the same name but in user's scope.
67 * Note that name scoping is not a security feature. On some systems any process on the system has technical capability to open objects within any scope.
68 * The scope is only used to help avoid name clashes between processes using \c object_name to identify objects.
76 global, //!< The name has global scope; any process in the system has the potential to open the resource identified by the name
77 user, //!< The name is limited to processes running under the current user
78 session, //!< The name is limited to processes running in the current login session
79 process_group //!< The name is limited to processes running in the current process group
82 #if !defined(BOOST_LOG_DOXYGEN_PASS)
84 BOOST_COPYABLE_AND_MOVABLE(object_name)
89 #endif // !defined(BOOST_LOG_DOXYGEN_PASS)
93 * Default constructor. The method creates an empty object name.
95 * \post <tt>empty() == true</tt>
97 object_name() BOOST_NOEXCEPT
104 object_name(BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
106 m_name.swap(that.m_name);
112 object_name(object_name const& that) : m_name(that.m_name)
117 * Constructor from the native string.
119 * \param str The object name string, must not be \c NULL. The string format is specific to the operating system.
121 static object_name from_native(const char* str)
129 * Constructor from the native string.
131 * \param str The object name string. The string format is specific to the operating system.
133 static object_name from_native(std::string const& str)
141 * Constructor from the object name
142 * \param ns The scope of the object name
143 * \param str The object name, must not be NULL.
145 BOOST_LOG_API object_name(scope ns, const char* str);
148 * Constructor from the object name
149 * \param ns The scope of the object name
150 * \param str The object name
152 BOOST_LOG_API object_name(scope ns, std::string const& str);
157 object_name& operator= (BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
160 m_name.swap(that.m_name);
167 object_name& operator= (BOOST_COPY_ASSIGN_REF(object_name) that)
169 m_name = that.m_name;
174 * Returns \c true if the object name is empty
176 bool empty() const BOOST_NOEXCEPT { return m_name.empty(); }
179 * Returns length of the name, in bytes
181 std::size_t size() const BOOST_NOEXCEPT { return m_name.size(); }
184 * Returns the name string
186 const char* c_str() const BOOST_NOEXCEPT { return m_name.c_str(); }
189 * Swaps the object name with another object name
191 void swap(object_name& that) BOOST_NOEXCEPT { m_name.swap(that.m_name); }
194 * Swaps two object names
196 friend void swap(object_name& left, object_name& right) BOOST_NOEXCEPT
202 * Returns string representation of the object name
204 friend std::string to_string(object_name const& name)
212 friend bool operator== (object_name const& left, object_name const& right) BOOST_NOEXCEPT
214 return left.m_name == right.m_name;
217 * Inequality operator
219 friend bool operator!= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
221 return left.m_name != right.m_name;
226 friend bool operator< (object_name const& left, object_name const& right) BOOST_NOEXCEPT
228 return left.m_name < right.m_name;
233 friend bool operator> (object_name const& left, object_name const& right) BOOST_NOEXCEPT
235 return left.m_name > right.m_name;
238 * Less or equal operator
240 friend bool operator<= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
242 return left.m_name <= right.m_name;
245 * Greater or equal operator
247 friend bool operator>= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
249 return left.m_name >= right.m_name;
253 * Stream ouput operator
255 template< typename CharT, typename TraitsT >
256 friend std::basic_ostream< CharT, TraitsT >& operator<< (std::basic_ostream< CharT, TraitsT >& strm, object_name const& name)
258 strm << name.c_str();
265 BOOST_LOG_CLOSE_NAMESPACE // namespace log
269 #include <boost/log/detail/footer.hpp>
271 #endif // BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_