Class object_name

boost::log::ipc::object_name — A system object name class.

Synopsis

// In header: <boost/log/utility/ipc/object_name.hpp>


class object_name {
public:

  // Name scopes. 
  enum scope { global, user, session, process_group };
  // construct/copy/destruct
  object_name() noexcept;
  object_name(object_name &&) noexcept;
  object_name(object_name const &);
  object_name(scope, const char *);
  object_name(scope, std::string const &);
  object_name & operator=(object_name &&) noexcept;
  object_name & operator=(object_name const &);

  // public member functions
  bool empty() const noexcept;
  std::size_t size() const noexcept;
  const char * c_str() const noexcept;
  void swap(object_name &) noexcept;

  // public static functions
  static object_name from_native(const char *);
  static object_name from_native(std::string const &);

  // friend functions
  friend void swap(object_name &, object_name &) noexcept;
  friend std::string to_string(object_name const &);
  friend bool operator==(object_name const &, object_name const &) noexcept;
  friend bool operator!=(object_name const &, object_name const &) noexcept;
  friend bool operator<(object_name const &, object_name const &) noexcept;
  friend bool operator>(object_name const &, object_name const &) noexcept;
  friend bool operator<=(object_name const &, object_name const &) noexcept;
  friend bool operator>=(object_name const &, object_name const &) noexcept;
  template<typename CharT, typename TraitsT> 
    friend std::basic_ostream< CharT, TraitsT > & 
    operator<<(std::basic_ostream< CharT, TraitsT > &, object_name const &);
};

Description

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. The format of the name is specific to the operating system and the object_name class provides an abstraction for names of objects. It also provides means for scoping, which allows to avoid name clashes between different processes.

The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:

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
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
0 1 2 3 4 5 6 7 8 9 . _ -

	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).

Use of other characters may result in non-portable system-specific behavior.

The name can have one of the following scopes:

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 extended privileges. This scope is not available for Windows Store applications.
user - objects within this scope can be opened by processes running under the same user as the current process.
session - objects within this scope are visible to processes within the session of the current process. The definition of a session may vary between operating systems. On POSIX, a session is typically a group of processes attached to a single virtual terminal device. On Windows a session is started when a user logs into the system. There is also a separate session for Windows services.
process_group - objects within this scope are visible to processes within the process group of the current process. Currently, on Windows all processes running in the current session are considered members of the same process group. This may change in future.

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.

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. The scope is only used to help avoid name clashes between processes using object_name to identify objects.

`object_name` public construct/copy/destruct

```
object_name() noexcept;
```
Default constructor. The method creates an empty object name.

Postconditions:

empty() == true

object_name(object_name && that) noexcept;

Move constructor.

```
object_name(object_name const & that);
```
Copy constructor.
```
object_name(scope ns, const char * str);
```
Constructor from the object name

Parameters:

ns

The scope of the object name

str

The object name, must not be NULL.
```
object_name(scope ns, std::string const & str);
```
Constructor from the object name

Parameters:

ns

The scope of the object name

str

The object name

object_name & operator=(object_name && that) noexcept;

Move assignment

object_name & operator=(object_name const & that);

Copy assignment

`object_name` public member functions

```
bool empty() const noexcept;
```
Returns true if the object name is empty
```
std::size_t size() const noexcept;
```
Returns length of the name, in bytes
```
const char * c_str() const noexcept;
```
Returns the name string
```
void swap(object_name & that) noexcept;
```
Swaps the object name with another object name

`object_name` public static functions

```
static object_name from_native(const char * str);
```
Constructor from the native string.

Parameters:

str

The object name string, must not be NULL. The string format is specific to the operating system.
```
static object_name from_native(std::string const & str);
```
Constructor from the native string.

Parameters:

str

The object name string. The string format is specific to the operating system.

`object_name` friend functions

friend void swap(object_name & left, object_name & right) noexcept;

Swaps two object names

friend std::string to_string(object_name const & name);

Returns string representation of the object name

friend bool operator==(object_name const & left, object_name const & right) noexcept;

Equality operator

friend bool operator!=(object_name const & left, object_name const & right) noexcept;

Inequality operator

friend bool operator<(object_name const & left, object_name const & right) noexcept;

Less operator

friend bool operator>(object_name const & left, object_name const & right) noexcept;

Greater operator

friend bool operator<=(object_name const & left, object_name const & right) noexcept;

Less or equal operator

friend bool operator>=(object_name const & left, object_name const & right) noexcept;

Greater or equal operator

template<typename CharT, typename TraitsT> 
  friend std::basic_ostream< CharT, TraitsT > & 
  operator<<(std::basic_ostream< CharT, TraitsT > & strm, 
             object_name const & name);

Stream ouput operator

Boost C++ Libraries