]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
29 | namespace boost { | |
30 | ||
31 | BOOST_LOG_OPEN_NAMESPACE | |
32 | ||
33 | namespace 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 | */ | |
70 | class object_name | |
71 | { | |
72 | public: | |
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 | ||
86 | private: | |
87 | std::string m_name; | |
88 | ||
89 | #endif // !defined(BOOST_LOG_DOXYGEN_PASS) | |
90 | ||
91 | public: | |
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(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(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(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(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 | ||
265 | BOOST_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_ |