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 */ object_name()97 object_name() BOOST_NOEXCEPT 98 { 99 } 100 101 /*! 102 * Move constructor. 103 */ object_name(BOOST_RV_REF (object_name)that)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 */ object_name(object_name const & that)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 */ from_native(const char * str)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 */ from_native(std::string const & str)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 */ operator =(BOOST_RV_REF (object_name)that)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 */ operator =(BOOST_COPY_ASSIGN_REF (object_name)that)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 */ empty() const176 bool empty() const BOOST_NOEXCEPT { return m_name.empty(); } 177 178 /*! 179 * Returns length of the name, in bytes 180 */ size() const181 std::size_t size() const BOOST_NOEXCEPT { return m_name.size(); } 182 183 /*! 184 * Returns the name string 185 */ c_str() const186 const char* c_str() const BOOST_NOEXCEPT { return m_name.c_str(); } 187 188 /*! 189 * Swaps the object name with another object name 190 */ swap(object_name & that)191 void swap(object_name& that) BOOST_NOEXCEPT { m_name.swap(that.m_name); } 192 193 /*! 194 * Swaps two object names 195 */ swap(object_name & left,object_name & right)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 */ to_string(object_name const & name)204 friend std::string to_string(object_name const& name) 205 { 206 return name.m_name; 207 } 208 209 /*! 210 * Equality operator 211 */ operator ==(object_name const & left,object_name const & right)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 */ operator !=(object_name const & left,object_name const & right)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 */ operator <(object_name const & left,object_name const & right)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 */ operator >(object_name const & left,object_name const & right)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 */ operator <=(object_name const & left,object_name const & right)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 */ operator >=(object_name const & left,object_name const & right)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 > operator <<(std::basic_ostream<CharT,TraitsT> & strm,object_name const & name)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_ 272