1/*
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)
6 */
7/*!
8 * \file utility/ipc/object_name.hpp
9 * \author Andrey Semashev
10 * \date 05.03.2016
11 *
12 * The header contains declaration of a system object name wrapper.
13 */
14
15#ifndef BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
16#define BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
17
18#include <boost/log/detail/config.hpp>
19#include <cstddef>
20#include <iosfwd>
21#include <string>
22#include <boost/move/core.hpp>
23#include <boost/log/detail/header.hpp>
24
25#ifdef BOOST_HAS_PRAGMA_ONCE
26#pragma once
27#endif
28
29namespace boost {
30
31BOOST_LOG_OPEN_NAMESPACE
32
33namespace ipc {
34
35/*!
36 * \brief A system object name class
37 *
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.
41 *
42 * The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:
43 *
44 * <pre>
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 . _ -
48 * </pre>
49 *
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).
51 *
52 * Use of other characters may result in non-portable system-specific behavior.
53 *
54 * The name can have one of the following scopes:
55 *
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.
64 *
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.
66 *
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.
69 */
70class object_name
71{
72public:
73 //! Name scopes
74 enum scope
75 {
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
80 };
81
82#if !defined(BOOST_LOG_DOXYGEN_PASS)
83
84 BOOST_COPYABLE_AND_MOVABLE(object_name)
85
86private:
87 std::string m_name;
88
89#endif // !defined(BOOST_LOG_DOXYGEN_PASS)
90
91public:
92 /*!
93 * Default constructor. The method creates an empty object name.
94 *
95 * \post <tt>empty() == true</tt>
96 */
97 object_name() BOOST_NOEXCEPT
98 {
99 }
100
101 /*!
102 * Move constructor.
103 */
104 object_name(BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
105 {
106 m_name.swap(s&: that.m_name);
107 }
108
109 /*!
110 * Copy constructor.
111 */
112 object_name(object_name const& that) : m_name(that.m_name)
113 {
114 }
115
116 /*!
117 * Constructor from the native string.
118 *
119 * \param str The object name string, must not be \c NULL. The string format is specific to the operating system.
120 */
121 static object_name from_native(const char* str)
122 {
123 object_name name;
124 name.m_name = str;
125 return name;
126 }
127
128 /*!
129 * Constructor from the native string.
130 *
131 * \param str The object name string. The string format is specific to the operating system.
132 */
133 static object_name from_native(std::string const& str)
134 {
135 object_name name;
136 name.m_name = str;
137 return name;
138 }
139
140 /*!
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.
144 */
145 BOOST_LOG_API object_name(scope ns, const char* str);
146
147 /*!
148 * Constructor from the object name
149 * \param ns The scope of the object name
150 * \param str The object name
151 */
152 BOOST_LOG_API object_name(scope ns, std::string const& str);
153
154 /*!
155 * Move assignment
156 */
157 object_name& operator= (BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
158 {
159 m_name.clear();
160 m_name.swap(s&: that.m_name);
161 return *this;
162 }
163
164 /*!
165 * Copy assignment
166 */
167 object_name& operator= (BOOST_COPY_ASSIGN_REF(object_name) that)
168 {
169 m_name = that.m_name;
170 return *this;
171 }
172
173 /*!
174 * Returns \c true if the object name is empty
175 */
176 bool empty() const BOOST_NOEXCEPT { return m_name.empty(); }
177
178 /*!
179 * Returns length of the name, in bytes
180 */
181 std::size_t size() const BOOST_NOEXCEPT { return m_name.size(); }
182
183 /*!
184 * Returns the name string
185 */
186 const char* c_str() const BOOST_NOEXCEPT { return m_name.c_str(); }
187
188 /*!
189 * Swaps the object name with another object name
190 */
191 void swap(object_name& that) BOOST_NOEXCEPT { m_name.swap(s&: that.m_name); }
192
193 /*!
194 * Swaps two object names
195 */
196 friend void swap(object_name& left, object_name& right) BOOST_NOEXCEPT
197 {
198 left.swap(that&: right);
199 }
200
201 /*!
202 * Returns string representation of the object name
203 */
204 friend std::string to_string(object_name const& name)
205 {
206 return name.m_name;
207 }
208
209 /*!
210 * Equality operator
211 */
212 friend bool operator== (object_name const& left, object_name const& right) BOOST_NOEXCEPT
213 {
214 return left.m_name == right.m_name;
215 }
216 /*!
217 * Inequality operator
218 */
219 friend bool operator!= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
220 {
221 return left.m_name != right.m_name;
222 }
223 /*!
224 * Less operator
225 */
226 friend bool operator< (object_name const& left, object_name const& right) BOOST_NOEXCEPT
227 {
228 return left.m_name < right.m_name;
229 }
230 /*!
231 * Greater operator
232 */
233 friend bool operator> (object_name const& left, object_name const& right) BOOST_NOEXCEPT
234 {
235 return left.m_name > right.m_name;
236 }
237 /*!
238 * Less or equal operator
239 */
240 friend bool operator<= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
241 {
242 return left.m_name <= right.m_name;
243 }
244 /*!
245 * Greater or equal operator
246 */
247 friend bool operator>= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
248 {
249 return left.m_name >= right.m_name;
250 }
251
252 /*!
253 * Stream ouput operator
254 */
255 template< typename CharT, typename TraitsT >
256 friend std::basic_ostream< CharT, TraitsT >& operator<< (std::basic_ostream< CharT, TraitsT >& strm, object_name const& name)
257 {
258 strm << name.c_str();
259 return strm;
260 }
261};
262
263} // namespace ipc
264
265BOOST_LOG_CLOSE_NAMESPACE // namespace log
266
267} // namespace boost
268
269#include <boost/log/detail/footer.hpp>
270
271#endif // BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
272

source code of boost/libs/log/include/boost/log/utility/ipc/object_name.hpp