utility/ipc/object_name.hpp

0001 /*
0002  *             Copyright Andrey Semashev 2016.
0003  * Distributed under the Boost Software License, Version 1.0.
0004  *    (See accompanying file LICENSE_1_0.txt or copy at
0005  *          http://www.boost.org/LICENSE_1_0.txt)
0006  */
0007 /*!
0008  * \file   utility/ipc/object_name.hpp
0009  * \author Andrey Semashev
0010  * \date   05.03.2016
0011  *
0012  * The header contains declaration of a system object name wrapper.
0013  */
0014
0015 #ifndef BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
0016 #define BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_
0017
0018 #include <boost/log/detail/config.hpp>
0019 #include <cstddef>
0020 #include <iosfwd>
0021 #include <string>
0022 #include <boost/move/core.hpp>
0023 #include <boost/log/detail/header.hpp>
0024
0025 #ifdef BOOST_HAS_PRAGMA_ONCE
0026 #pragma once
0027 #endif
0028
0029 namespace boost {
0030
0031 BOOST_LOG_OPEN_NAMESPACE
0032
0033 namespace ipc {
0034
0035 /*!
0036  * \brief A system object name class
0037  *
0038  * 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.
0039  * 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
0040  * provides means for scoping, which allows to avoid name clashes between different processes.
0041  *
0042  * The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:
0043  *
0044  * <pre>
0045  * 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
0046  * 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
0047  * 0 1 2 3 4 5 6 7 8 9 . _ -
0048  * </pre>
0049  *
0050  * \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).
0051  *
0052  * Use of other characters may result in non-portable system-specific behavior.
0053  *
0054  * The name can have one of the following scopes:
0055  *
0056  * \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
0057  *                 extended privileges. This scope is not available for Windows Store applications.
0058  * \li \c user - objects within this scope can be opened by processes running under the same user as the current process.
0059  * \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
0060  *                  operating systems. On POSIX, a session is typically a group of processes attached to a single virtual terminal device. On Windows a session is
0061  *                  started when a user logs into the system. There is also a separate session for Windows services.
0062  * \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
0063  *                        running in the current session are considered members of the same process group. This may change in future.
0064  *
0065  * 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.
0066  *
0067  * 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.
0068  * The scope is only used to help avoid name clashes between processes using \c object_name to identify objects.
0069  */
0070 class object_name
0071 {
0072 public:
0073     //! Name scopes
0074     enum scope
0075     {
0076         global,        //!< The name has global scope; any process in the system has the potential to open the resource identified by the name
0077         user,          //!< The name is limited to processes running under the current user
0078         session,       //!< The name is limited to processes running in the current login session
0079         process_group  //!< The name is limited to processes running in the current process group
0080     };
0081
0082 #if !defined(BOOST_LOG_DOXYGEN_PASS)
0083
0084     BOOST_COPYABLE_AND_MOVABLE(object_name)
0085
0086 private:
0087     std::string m_name;
0088
0089 #endif // !defined(BOOST_LOG_DOXYGEN_PASS)
0090
0091 public:
0092     /*!
0093      * Default constructor. The method creates an empty object name.
0094      *
0095      * \post <tt>empty() == true</tt>
0096      */
0097     object_name() BOOST_NOEXCEPT
0098     {
0099     }
0100
0101     /*!
0102      * Move constructor.
0103      */
0104     object_name(BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
0105     {
0106         m_name.swap(that.m_name);
0107     }
0108
0109     /*!
0110      * Copy constructor.
0111      */
0112     object_name(object_name const& that) : m_name(that.m_name)
0113     {
0114     }
0115
0116     /*!
0117      * Constructor from the native string.
0118      *
0119      * \param str The object name string, must not be \c NULL. The string format is specific to the operating system.
0120      */
0121     static object_name from_native(const char* str)
0122     {
0123         object_name name;
0124         name.m_name = str;
0125         return name;
0126     }
0127
0128     /*!
0129      * Constructor from the native string.
0130      *
0131      * \param str The object name string. The string format is specific to the operating system.
0132      */
0133     static object_name from_native(std::string const& str)
0134     {
0135         object_name name;
0136         name.m_name = str;
0137         return name;
0138     }
0139
0140     /*!
0141      * Constructor from the object name
0142      * \param ns The scope of the object name
0143      * \param str The object name, must not be NULL.
0144      */
0145     BOOST_LOG_API object_name(scope ns, const char* str);
0146
0147     /*!
0148      * Constructor from the object name
0149      * \param ns The scope of the object name
0150      * \param str The object name
0151      */
0152     BOOST_LOG_API object_name(scope ns, std::string const& str);
0153
0154     /*!
0155      * Move assignment
0156      */
0157     object_name& operator= (BOOST_RV_REF(object_name) that) BOOST_NOEXCEPT
0158     {
0159         m_name.clear();
0160         m_name.swap(that.m_name);
0161         return *this;
0162     }
0163
0164     /*!
0165      * Copy assignment
0166      */
0167     object_name& operator= (BOOST_COPY_ASSIGN_REF(object_name) that)
0168     {
0169         m_name = that.m_name;
0170         return *this;
0171     }
0172
0173     /*!
0174      * Returns \c true if the object name is empty
0175      */
0176     bool empty() const BOOST_NOEXCEPT { return m_name.empty(); }
0177
0178     /*!
0179      * Returns length of the name, in bytes
0180      */
0181     std::size_t size() const BOOST_NOEXCEPT { return m_name.size(); }
0182
0183     /*!
0184      * Returns the name string
0185      */
0186     const char* c_str() const BOOST_NOEXCEPT { return m_name.c_str(); }
0187
0188     /*!
0189      * Swaps the object name with another object name
0190      */
0191     void swap(object_name& that) BOOST_NOEXCEPT { m_name.swap(that.m_name); }
0192
0193     /*!
0194      * Swaps two object names
0195      */
0196     friend void swap(object_name& left, object_name& right) BOOST_NOEXCEPT
0197     {
0198         left.swap(right);
0199     }
0200
0201     /*!
0202      * Returns string representation of the object name
0203      */
0204     friend std::string to_string(object_name const& name)
0205     {
0206         return name.m_name;
0207     }
0208
0209     /*!
0210      * Equality operator
0211      */
0212     friend bool operator== (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0213     {
0214         return left.m_name == right.m_name;
0215     }
0216     /*!
0217      * Inequality operator
0218      */
0219     friend bool operator!= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0220     {
0221         return left.m_name != right.m_name;
0222     }
0223     /*!
0224      * Less operator
0225      */
0226     friend bool operator< (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0227     {
0228         return left.m_name < right.m_name;
0229     }
0230     /*!
0231      * Greater operator
0232      */
0233     friend bool operator> (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0234     {
0235         return left.m_name > right.m_name;
0236     }
0237     /*!
0238      * Less or equal operator
0239      */
0240     friend bool operator<= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0241     {
0242         return left.m_name <= right.m_name;
0243     }
0244     /*!
0245      * Greater or equal operator
0246      */
0247     friend bool operator>= (object_name const& left, object_name const& right) BOOST_NOEXCEPT
0248     {
0249         return left.m_name >= right.m_name;
0250     }
0251
0252     /*!
0253      * Stream ouput operator
0254      */
0255     template< typename CharT, typename TraitsT >
0256     friend std::basic_ostream< CharT, TraitsT >& operator<< (std::basic_ostream< CharT, TraitsT >& strm, object_name const& name)
0257     {
0258         strm << name.c_str();
0259         return strm;
0260     }
0261 };
0262
0263 } // namespace ipc
0264
0265 BOOST_LOG_CLOSE_NAMESPACE // namespace log
0266
0267 } // namespace boost
0268
0269 #include <boost/log/detail/footer.hpp>
0270
0271 #endif // BOOST_LOG_UTILITY_IPC_OBJECT_NAME_HPP_INCLUDED_