xtd 0.2.0
xtd::environment Class Referencefinal

Definition

The environment class.

Namespace
xtd
Library
xtd.core
Examples
The following example demonstrates displays a list of information about the current environment.
#include <xtd/console>
#include <xtd/environment>
#include <xtd/startup>
using namespace xtd;
namespace environment_example {
class program {
public:
// The main entry point for the application.
static auto main() {
auto nl = environment::new_line();
//
console::write_line("-- environment members --");
// Invoke this sample with an arbitrary set of command line arguments.
console::write_line("get_command_line_args: {}", ustring::join(", ", arguments));
// <-- Keep this information secure! -->
// <-- Keep this information secure! -->
console::write_line("new_line: {0} first line{0} second line{0} third line", environment::new_line());
// <-- Keep this information secure! -->
// <-- Keep this information secure! -->
// <-- Keep this information secure! -->
// No example for Exit(exitCode) because doing so would terminate this example.
// <-- Keep this information secure! -->
auto query = ustring::format("My home folder is %{}% and user is %{}%", environment::os_version().is_windows_platform() ? "HOMEPATH" : "HOME", environment::os_version().is_windows_platform() ? "USERNAME" : "USER");
console::write_line("expand_environment_variables: {} {}", nl, str);
console::write_line("get_environment_variable: {} My temporary directory is {}.", nl, environment::get_environment_variable(environment::os_version().is_windows_platform() ? "TEMP" : "TMPDIR"));
console::write_line("get_environment_variables: ");
auto environment_variables = environment::get_environment_variables();
for (auto de : environment_variables)
console::write_line(" {} = {1}", de.first, de.second);
console::write_line("GetLogicalDrives: {}", ustring::join(", ", drives));
}
};
}
startup_(environment_example::program::main);
// This example produces results similar to the following:
// (Any result that is lengthy or reveals information that should remain
// secure has been omitted and marked "!---OMITTED---!".)
//
// -- environment members --
// command_line: !---OMITTED---!/environment ARBITRARY TEXT
// get_command_line_args: !---OMITTED---!/environment, ARBITRARY, TEXT
// current_directory: !---OMITTED---!/environment/environment/Debug
// exit_code: 0
// has_shutdown_started: false
// machine_name: !---OMITTED---!
// new_line:
// first line
// second line
// third line
// os_version: macOS 12.6.0
// stack_trace: ' at xtd::environment::stack_trace()
// at environment_example::program::main()
// at main::startup::run(void (*)(), int, char**)'
// system_directory: /System
// tick_count: 3.01:15:01:827000000
// user_domain_name: !---OMITTED---!
// user_interactive: true
// user_name: !---OMITTED---!
// version: 0.2.0
// working_set: 0
// expand_environment_variables:
// My home folder is /Users/!---OMITTED---! and user is !---OMITTED---!
// get_environment_variable:
// My temporary directory is /var/folders/xg/2fvdl7v939g9kbp8xn1dpgg00000gn/T/.
// get_environment_variables:
// !---OMITTED---!
// get_folder_path: /System
// GetLogicalDrives: /, /dev, /System/Volumes/Hardware, /System/Volumes/Update, /System/Volumes/Preboot, /System/Volumes/xarts, /System/Volumes/VM, /System/Volumes/Data, /System/Volumes/iSCPreboot, /System/Volumes/Data/home, /Volumes/Data

Classes

class  xtd_library
 Represents a xtd library that contains name, version and paths. More...
 

Public Types

enum  special_folder {
  special_folder::desktop = 0,
  special_folder::programs = 2,
  special_folder::my_documents = 5,
  special_folder::personal = 5,
  special_folder::favorites = 6,
  special_folder::startup = 7,
  special_folder::recent = 8,
  special_folder::send_to = 9,
  special_folder::start_menu = 11,
  special_folder::my_music = 13,
  special_folder::my_videos = 14,
  special_folder::desktop_directory = 16,
  special_folder::my_computer = 17,
  special_folder::network_shortcuts = 19,
  special_folder::fonts = 20,
  special_folder::templates = 21,
  special_folder::common_start_menu = 22,
  special_folder::common_programs = 23,
  special_folder::common_startup = 24,
  special_folder::common_desktop_directory = 25,
  special_folder::application_data = 26,
  special_folder::printer_shortcuts = 27,
  special_folder::local_application_data = 28,
  special_folder::internet_cache = 32,
  special_folder::cookies = 33,
  special_folder::history = 34,
  special_folder::common_application_data = 35,
  special_folder::windows = 36,
  special_folder::system = 37,
  special_folder::program_files = 38,
  special_folder::my_pictures = 39,
  special_folder::user_profile = 40,
  special_folder::system_x86 = 41,
  special_folder::program_files_x86 = 42,
  special_folder::common_program_files = 43,
  special_folder::common_program_files_x86 = 44,
  special_folder::common_templates = 45,
  special_folder::common_documents = 46,
  special_folder::common_admin_tools = 47,
  special_folder::admin_tools = 48,
  special_folder::common_music = 53,
  special_folder::common_pictures = 54,
  special_folder::common_videos = 55,
  special_folder::resources = 56,
  special_folder::localized_resources = 57,
  special_folder::common_oem_links = 58,
  special_folder::cd_burning = 59,
  special_folder::home = 64,
  special_folder::xtd_install = 1000,
  special_folder::xtd_locale = 1001,
  special_folder::xtd_reference_guide = 1002,
  special_folder::xtd_themes = 1003,
  special_folder::xtd_include = 1004,
  special_folder::xtd_libraries = 1005,
  special_folder::xtd_resources = 1006,
  special_folder::xtd_console_include = 1007,
  special_folder::xtd_console_libraries = 1008,
  special_folder::xtd_drawing_include = 1009,
  special_folder::xtd_drawing_libraries = 1010,
  special_folder::xtd_drawing_resources = 1011,
  special_folder::xtd_forms_include = 1012,
  special_folder::xtd_forms_libraries = 1013,
  special_folder::xtd_forms_resources = 1014,
  special_folder::xtd_tunit_include = 1015,
  special_folder::xtd_tunit_libraries = 1016
}
 
enum  special_folder_option {
  special_folder_option::none = 0,
  special_folder_option::do_not_verify = 16384,
  special_folder_option::create = 32768
}
 Specifies options to use for getting the path to a special folder. More...
 
using xtd_library_collection = std::vector< xtd_library >
 Represents a xtd libraries collection. More...
 

Properties

static xtd::ustring command_line () noexcept
 Gets the command line for this process. More...
 
static xtd::compiler compiler_version () noexcept
 Gets an xtd::compiler object that contains the current compiler identifier and version number. More...
 
static xtd::cpp_language cpp_version () noexcept
 Gets an xtd::cpp_language object that contains the current c++ standard identifier and version number. More...
 
static xtd::ustring current_directory ()
 Gets the fully qualified path of the current working directory. More...
 
static void current_directory (const xtd::ustring &directory_name)
 Sets the fully qualified path of the current working directory. More...
 
static int32 current_managed_thread_id () noexcept
 Gets a unique identifier for the current managed thread. More...
 
static intptr current_thread_id () noexcept
 Gets a unique identifier for the current thread. More...
 
static int32 exit_code () noexcept
 Gets the exit code of the process. More...
 
static void exit_code (int32 value) noexcept
 Sets the exit code of the process. More...
 
static bool has_shutdown_started ()
 Gets a value that indicates whether the current application domain is shutting down. More...
 
static bool is_64_bit_operating_system () noexcept
 Determines whether the current operating system is a 64-bit operating system. More...
 
static bool is_64_bit_process () noexcept
 Determines whether the current process is a 64-bit process. More...
 
static std::locale locale () noexcept
 Gets a copy of the global C++ locale, which is the locale most recently used as the argument to See std::locale::global or a copy of See std::locale::classic() if no call to See std::locale::global has been made. More...
 
static xtd::ustring machine_name ()
 Gets the NetBIOS name of this local computer. More...
 
static xtd::ustring new_line () noexcept
 Gets the newline string defined for this environment. More...
 
template<class char_t , class traits_t >
static std::basic_ostream< char_t, traits_t > & new_line (std::basic_ostream< char_t, traits_t > &os)
 Inserts a new-line character and flushes the stream. More...
 
static xtd::operating_system os_version () noexcept
 Gets an xtd::operating_system object that contains the current platform identifier and version number. More...
 
static uint32 processor_count ()
 Gets the number of processors on the current machine. More...
 
static xtd::processor processor_information ()
 Gets an xtd::processor object that contains the processor identifier. More...
 
static xtd::ustring stack_trace ()
 Gets current stack trace information. More...
 
static xtd::ustring system_directory ()
 Gets the fully qualified path of the system directory. More...
 
static size_t system_page_size ()
 Gets the number of bytes in the operating system's memory page. More...
 
static xtd::target_type target_type () noexcept
 Gets an xtd::target_type object that contains the current target identifier. More...
 
static std::chrono::milliseconds tick_count ()
 Gets the number of milliseconds elapsed since the system started. More...
 
static xtd::toolkit toolkit_version ()
 Gets the current toolkit version. More...
 
static bool user_administrator ()
 Gets a value indicating whether the current user is an administrator. More...
 
static xtd::ustring user_domain_name ()
 Gets the network domain name associated with the current user. More...
 
static bool user_interactive ()
 Gets a value indicating whether the current process is running in user interactive mode. More...
 
static xtd::ustring user_name ()
 Gets the user name of the person who is currently logged on to the operating system. More...
 
static xtd::version version () noexcept
 Gets a version consisting of the major, minor, build, and revision numbers of the xtd framework. More...
 
static int64 working_set ()
 Gets the amount of physical memory mapped to the process context. More...
 
static const xtd_library_collectionxtd_libraries () noexcept
 Gets an xtd::environment::xtd_library array that represent the xtd libraries name, version and paths. More...
 

Events

static event< environment, signal_cancel_event_handlercancel_signal
 Occurs when a signal is sent to the current process. More...
 
static event< environment, program_exit_event_handlerprogram_exit
 Occurs when the terminates normally (via xtd::environment::exit or returning from the main function). More...
 

Methods

static void abort ()
 Causes abnormal program termination unless xtd::signal::abnormal_termination is being caught by a xtd::environment::cancel_signal event. More...
 
static void exit ()
 Terminates this process and returns an exit code to the operating system. More...
 
static void exit (int32 exit_code)
 Terminates this process and returns an exit code to the operating system. More...
 
static void exit (xtd::exit_status exit_status)
 Terminates this process and returns an exit status to the operating system. More...
 
static xtd::ustring expand_environment_variables (const xtd::ustring &name)
 Replaces the name of each environment variable embedded in the specified string with the string equivalent of the value of the variable, then returns the resulting string. More...
 
static xtd::collections::specialized::string_vector get_command_line_args ()
 Returns a string array containing the command-line arguments for the current process. More...
 
static xtd::ustring get_environment_variable (const xtd::ustring &variable)
 Retrieves the value of an environment variable from the current process. More...
 
static xtd::ustring get_environment_variable (const xtd::ustring &variable, environment_variable_target target)
 Retrieves the value of an environment variable from the current process or from the Windows operating system registry key for the current user or local machine. More...
 
static std::map< std::string, std::string > & get_environment_variables ()
 Retrieves all environment variable names and their values from the current process. More...
 
static std::map< std::string, std::string > & get_environment_variables (environment_variable_target target)
 Retrieves all environment variable names and their values from the current process, or from the Windows operating system registry key for the current user or local machine. More...
 
static xtd::ustring get_folder_path (environment::special_folder folder)
 Gets the path to the system special folder that is identified by the specified enumeration. More...
 
static xtd::ustring get_folder_path (environment::special_folder folder, environment::special_folder_option option)
 Gets the path to the system special folder that is identified by the specified enumeration, and uses a specified option for accessing special folders. More...
 
static xtd::collections::specialized::string_vector get_logical_drives ()
 Returns an array of string containing the names of the logical drives on the current computer. More...
 
static void quick_exit () noexcept
 Terminates this process and returns an exit code to the operating system without completely cleaning the resources.. More...
 
static void quick_exit (int32 exit_code) noexcept
 Terminates this process and returns an exit code to the operating system without completely cleaning the resources.. More...
 
static void quick_exit (xtd::exit_status exit_status) noexcept
 Terminates this process and returns an exit status to the operating system without completely cleaning the resources.. More...
 
static void raise (xtd::signal signal)
 Sends xtd::signal to the program. The xtd::environment::cancel_signal event is invoked with the specified signal. More...
 
static void set_environment_variable (const xtd::ustring &variable, const xtd::ustring &value)
 Creates, modifies, or deletes an environment variable stored in the current process. More...
 
static void set_environment_variable (const xtd::ustring &variable, const xtd::ustring &value, environment_variable_target target)
 Creates, modifies, or deletes an environment variable stored in the current process or in the Windows operating system registry key reserved for the current user or local machine. More...
 

Member Typedef Documentation

◆ xtd_library_collection

Represents a xtd libraries collection.

Member Enumeration Documentation

◆ special_folder

Enumerator
desktop 

The logical Desktop rather than the physical file system location.

programs 

The directory that contains the user's program groups.

my_documents 

The My Documents folder. This member is equivalent to Personal.

personal 

The directory that serves as a common repository for documents. This member is equivalent to MyDocuments.

favorites 

The directory that serves as a common repository for the user's favorite items.

startup 

The directory that corresponds to the user's Startup program group. The system starts these programs whenever a user logs on or starts Windows NT or later, or starts Windows 98.

recent 

The directory that contains the user's most recently used documents.

send_to 

The directory that contains the Send To menu items.

start_menu 

The directory that contains the Start menu items.

my_music 

The My Music folder.

my_videos 

The file system directory that serves as a repository for videos that belong to a user.

desktop_directory 

The directory used to physically store file objects on the desktop. Do not confuse this directory with the desktop folder itself, which is a virtual folder.

my_computer 

The My Computer folder. The MyComputer constant always yields the empty string ("") because no path is defined for the My Computer folder.

network_shortcuts 

A file system directory that contains the link objects that may exist in the My Network Places virtual folder.

fonts 

A virtual folder that contains fonts.

templates 

The directory that serves as a common repository for document templates.

common_start_menu 

The file system directory that contains the programs and folders that appear on the Start menu for all users. This special folder is valid only for Windows NT systems.

common_programs 

A folder for components that are shared across applications. This special folder is valid only for Windows NT, Windows 2000, and Windows XP systems.

common_startup 

The file system directory that contains the programs that appear in the Startup folder for all users. This special folder is valid only for Windows NT systems.

common_desktop_directory 

The file system directory that contains files and folders that appear on the desktop for all users. This special folder is valid only for Windows NT systems.

application_data 

The directory that serves as a common repository for application-specific data for the current roaming user. A roaming user works on more than one computer on a network. A roaming user's profile is kept on a server on the network and is loaded onto a system when the user logs on.

printer_shortcuts 

The file system directory that contains the link objects that can exist in the Printers virtual folder.

local_application_data 

The directory that serves as a common repository for application-specific data that is used by the current, non-roaming user.

internet_cache 

The directory that serves as a common repository for temporary Internet files.

cookies 

The directory that serves as a common repository for Internet cookies.

history 

The directory that serves as a common repository for Internet history items.

common_application_data 

The directory that serves as a common repository for application-specific data that is used by all users.

windows 

The Windows directory or SYSROOT. This corresponds to the windir% or SYSTEMROOT% environment variables.

system 

The System directory.

program_files 

The program files directory.On a non-x86 system, passing ProgramFiles to the GetFolderPath method returns the path for non-x86 programs. To get the x86 program files directory on a non-x86 system, use the ProgramFilesX86 member.

my_pictures 

The My Pictures folder.

user_profile 

The user's profile folder. Applications should not create files or folders at this level; they should put their data under the locations referred to by ApplicationData.

system_x86 

The Windows System folder.

program_files_x86 

The Program Files folder On an x86 system, passing the ProgramFilesX86 member to the Environment.GetFolderPath method returns string.Empty; use the ProgramFiles member instead. You can determine whether Windows is a 32-bit operating system by calling the Environment.Is64BitOperatingSystem property.

common_program_files 

The directory for components that are shared across applications.To get the x86 common program files directory on a non-x86 system, use the ProgramFilesX86 member.

common_program_files_x86 

The Program Files folder.

common_templates 

The file system directory that contains the templates that are available to all users. This special folder is valid only for Windows NT systems.

common_documents 

The file system directory that contains documents that are common to all users. This special folder is valid for Windows NT systems, Windows 95, and Windows 98 systems with Shfolder.dll installed.

common_admin_tools 

The file system directory that contains administrative tools for all users of the computer.

admin_tools 

The file system directory that is used to store administrative tools for an individual user. The Microsoft Management Console (MMC) will save customized consoles to this directory, and it will roam with the user.

common_music 

The file system directory that serves as a repository for music files common to all users.

common_pictures 

The file system directory that serves as a repository for image files common to all users.

common_videos 

The file system directory that serves as a repository for video files common to all users.

resources 

The file system directory that contains resource data.

localized_resources 

The file system directory that contains localized resource data.

common_oem_links 

This value is recognized in Windows Vista for backward compatibility, but the special folder itself is no longer used.

cd_burning 

The file system directory that acts as a staging area for files waiting to be written to a CD.

home 

The file system directory that contains home folder.

xtd_install 

The installation folder of xtd.

xtd_locale 

The xtd locale folder.

xtd_reference_guide 

The xtd reference guide folder.

xtd_themes 

The xtd themes folder.

xtd_include 

The xtd inlude folder.

xtd_libraries 

The xtd libraries folder.

xtd_resources 

The xtd resources folder.

xtd_console_include 

The xtd::console include folder.

xtd_console_libraries 

The xtd::console libraries folder.

xtd_drawing_include 

The xtd::drawing include folder.

xtd_drawing_libraries 

The xtd::drawing libraries folder.

xtd_drawing_resources 

The xtd::drawing resources folder.

xtd_forms_include 

The xtd::forms include folder.

xtd_forms_libraries 

The xtd::forms libraries folder.

xtd_forms_resources 

The xtd::forms resources folder.

xtd_tunit_include 

The xtd::tunit include folder.

xtd_tunit_libraries 

The xtd::tunit libraries folder.

◆ special_folder_option

Specifies options to use for getting the path to a special folder.

Remarks
The xtd::environment::special_folder_option enumeration is used to define the precise behavior of the xtd::environment::get_folder_path method.
Enumerator
none 

The path to the folder is verified. If the folder exists, the path is returned. If the folder does not exist, an empty string is returned. This is the default behavior.

do_not_verify 

The path to the folder is returned without verifying whether the path exists. If the folder is located on a network, specifying this option can reduce lag time.

create 

The path to the folder is created if it does not already exist.

Member Function Documentation

◆ abort()

static void xtd::environment::abort ( )
static

Causes abnormal program termination unless xtd::signal::abnormal_termination is being caught by a xtd::environment::cancel_signal event.

◆ command_line()

static xtd::ustring xtd::environment::command_line ( )
staticnoexcept

Gets the command line for this process.

Returns
A string containing command-line arguments.
Remarks
This method provides access to the program name and any arguments specified on the command line when the current process was started.
The program name can include path information, but is not required to do so. Use the xtd::environment::get_command_line_args method to retrieve the command-line information parsed and stored in an array of strings.
The maximum size of the command-line buffer is not set to a specific number of characters; it varies depending on the operating system that is running on the computer.
Examples:
environment_command_line.cpp.

◆ compiler_version()

static xtd::compiler xtd::environment::compiler_version ( )
inlinestaticnoexcept

Gets an xtd::compiler object that contains the current compiler identifier and version number.

Returns
An object that contains the compiler identifier and version number.

◆ cpp_version()

static xtd::cpp_language xtd::environment::cpp_version ( )
inlinestaticnoexcept

Gets an xtd::cpp_language object that contains the current c++ standard identifier and version number.

Returns
An object that contains the c++ standard identifier and version number.

◆ current_directory() [1/2]

static xtd::ustring xtd::environment::current_directory ( )
static

Gets the fully qualified path of the current working directory.

Returns
xtd::ustring A string containing a directory path.
Remarks
By definition, if this process starts in the root directory of a local or network drive, the value returned by this method is the drive name followed by a trailing slash (for example, "C:\"). If this process starts in a subdirectory, the value returned by this method is the drive and subdirectory path, without a trailing slash (for example, "C:\mySubDirectory").
Exceptions
xtd::not_supported_exceptionThe operating system does not have current directory functionality.
Examples:
environment_current_directory.cpp, and test_forms.cpp.

◆ current_directory() [2/2]

static void xtd::environment::current_directory ( const xtd::ustring directory_name)
static

Sets the fully qualified path of the current working directory.

Parameters
directory_nameA string containing a directory path.
Exceptions
xtd::argument_exceptionAttempted to set to an empty string ("").
xtd::io::io_exceptionAn I/O error occurred.
xtd::io::directory_not_found_exceptionAttempted to set a local path that cannot be found.
xtd::security::security_exceptionThe caller does not have the appropriate permission.

◆ current_managed_thread_id()

static int32 xtd::environment::current_managed_thread_id ( )
staticnoexcept

Gets a unique identifier for the current managed thread.

Returns
An id that represents a unique identifier for this thread.

◆ current_thread_id()

static intptr xtd::environment::current_thread_id ( )
staticnoexcept

Gets a unique identifier for the current thread.

Returns
An id that represents a unique identifier for this thread.

◆ exit() [1/3]

static void xtd::environment::exit ( )
static

Terminates this process and returns an exit code to the operating system.

Remarks
Use xtd::environment::exit_code method to return to the operating system.
Examples:
environment_cancel_signal.cpp, environment_exit.cpp, environment_program_exit.cpp, and system_sounds.cpp.

◆ exit() [2/3]

static void xtd::environment::exit ( int32  exit_code)
static

Terminates this process and returns an exit code to the operating system.

Parameters
exit_codeThe exit code to return to the operating system. Use 0 (zero) to indicate that the process completed successfully.
Remarks
For the exit_code parameter, use a non-zero number to indicate an error. In your application, you can define your own error codes in an enumeration, and return the appropriate error code based on the scenario. For example, return a value of 1 to indicate that the required file is not present, and a value of 2 to indicate that the file is in the wrong format.

◆ exit() [3/3]

static void xtd::environment::exit ( xtd::exit_status  exit_status)
static

Terminates this process and returns an exit status to the operating system.

Parameters
exit_statusOne of xtd::exit_status values.

◆ exit_code() [1/2]

static int32 xtd::environment::exit_code ( )
staticnoexcept

Gets the exit code of the process.

Returns
A 32-bit signed integer containing the exit code. The default value is 0 (zero), which indicates that the process completed successfully.
Remarks
If the main method returns void, you can use this property to set the exit code that will be returned to the calling environment. If Main does not return void, this property is ignored. The initial value of this property is zero.
Warning
The xtd::environment::exit_code property is a signed 32-bit integer. To prevent the property from returning a negative exit code, you should not use values greater than or equal to 0x80000000.
Remarks
Use a non-zero number to indicate an error. In your application, you can define your own error codes in an enumeration, and return the appropriate error code based on the scenario. For example, return a value of 1 to indicate that the required file is not present and a value of 2 to indicate that the file is in the wrong format.
Examples:
main1.cpp.

◆ exit_code() [2/2]

static void xtd::environment::exit_code ( int32  value)
staticnoexcept

Sets the exit code of the process.

Parameters
valueA 32-bit signed integer containing the exit code. The default value is 0 (zero), which indicates that the process completed successfully.
Remarks
If the main method returns void, you can use this property to set the exit code that will be returned to the calling environment. If Main does not return void, this property is ignored. The initial value of this property is zero.
Warning
The xtd::environment::exit_code property is a signed 32-bit integer. To prevent the property from returning a negative exit code, you should not use values greater than or equal to 0x80000000.
Remarks
Use a non-zero number to indicate an error. In your application, you can define your own error codes in an enumeration, and return the appropriate error code based on the scenario. For example, return a value of 1 to indicate that the required file is not present and a value of 2 to indicate that the file is in the wrong format.

◆ expand_environment_variables()

static xtd::ustring xtd::environment::expand_environment_variables ( const xtd::ustring name)
static

Replaces the name of each environment variable embedded in the specified string with the string equivalent of the value of the variable, then returns the resulting string.

Parameters
nameA string containing the names of zero or more environment variables. Each environment variable is quoted with the percent sign character (%).
Returns
A string with each environment variable replaced by its value.
Remarks
Replacement only occurs for environment variables that are set. For example, suppose name is "MyENV = %MyENV%". If the environment variable, MyENV, is set to 42, this method returns "MyENV = 42". If MyENV is not set, no change occurs; this method returns "MyENV = %MyENV%".
Examples:
environment_expand_environment_variables.cpp.

◆ get_command_line_args()

static xtd::collections::specialized::string_vector xtd::environment::get_command_line_args ( )
static

Returns a string array containing the command-line arguments for the current process.

Returns
An array of string where each element contains a command-line argument. The first element is the executable file name, and the following zero or more elements contain the remaining command-line arguments.
Remarks
The first element in the array contains the file name of the executing program. If the file name is not available, the first element is equal to string empty "". The remaining elements contain any additional tokens entered on the command line.
The program file name can, but is not required to, include path information.
Command line arguments are delimited by spaces. You can use double quotation marks (") to include spaces within an argument. The single quotation mark ('), however, does not provide this functionality.
If a double quotation mark follows two or an even number of backslashes, each proceeding backslash pair is replaced with one backslash and the double quotation mark is removed. If a double quotation mark follows an odd number of backslashes, including just one, each preceding pair is replaced with one backslash and the remaining backslash is removed; however, in this case the double quotation mark is not removed.
The following table shows how command line arguments can be delimited, and assumes MyApp as the current executing application.
Input at the command line Resulting command line arguments
MyApp alpha beta MyApp, alpha, beta
MyApp "alpha with spaces" "beta with spaces" MyApp, alpha with spaces, beta with spaces
MyApp 'alpha with spaces' beta MyApp, 'alpha, with, spaces', beta
MyApp \ \\"beta <td> MyApp, \\\alpha, \\beta <tr><td> MyApp \\\\\"alpha "beta MyApp, \"alpha, "beta
To obtain the command line as a single string, use the xtd::environment::command_line method.
Examples:
action1.cpp, action2.cpp, action3.cpp, main1.cpp, main2.cpp, and main5.cpp.

◆ get_environment_variable() [1/2]

static xtd::ustring xtd::environment::get_environment_variable ( const xtd::ustring variable)
static

Retrieves the value of an environment variable from the current process.

Parameters
variableThe name of the environment variable.
Returns
xtd::ustring The value of the environment variable specified by variable, or empty "" if the environment variable is not found.
Remarks
The get_environment_variable(xtd::ustring) method retrieves an environment variable from the environment block of the current process only. It is equivalent to calling the xtd::environment::get_environment_variable(xtd::ustring, xtd::environment_variable_target) method with a target value of xtd::environment_variable_target::process.
To retrieve all environment variables along with their values, call the xtd::environment::get_environment_variables method.
Environment variable names are case-sensitive on Linux and macOS but are not case-sensitive on Windows.

◆ get_environment_variable() [2/2]

static xtd::ustring xtd::environment::get_environment_variable ( const xtd::ustring variable,
environment_variable_target  target 
)
static

Retrieves the value of an environment variable from the current process or from the Windows operating system registry key for the current user or local machine.

Parameters
variableThe name of an environment variable.
targetOne of the EnvironmentVariableTarget values.
Exceptions
std::invalid_argumenttarget is not a valid environment_variable_target value.
Returns
xtd::ustring The value of the environment variable specified by the variable and target parameters, or empty "" if the environment variable is not found.
Remarks
To retrieve all environment variables along with their values, call the xtd::environment::get_environment_variables method.
Environment variable names are case-sensitive on Linux and macOS but are not case-sensitive on Windows.
Todo:
Add xtd::registry and uncomment lines.

◆ get_environment_variables() [1/2]

static std::map<std::string, std::string>& xtd::environment::get_environment_variables ( )
static

Retrieves all environment variable names and their values from the current process.

Returns
std::map A dictionary that contains all environment variable names and their values; otherwise, an empty dictionary if no environment variables are found.
Remarks
The names and values for the environment variables are stored as key-value pairs in the returned std::map.

◆ get_environment_variables() [2/2]

static std::map<std::string, std::string>& xtd::environment::get_environment_variables ( environment_variable_target  target)
static

Retrieves all environment variable names and their values from the current process, or from the Windows operating system registry key for the current user or local machine.

Parameters
targetOne of the environment_variable_target values.
Returns
std::map A dictionary that contains all environment variable names and their values from the source specified by the target parameter; otherwise, an empty dictionary if no environment variables are found.
Exceptions
std::invalid_argumenttarget is not a valid environment_variable_target value.
Remarks
The names and values for the environment variables are stored as key-value pairs in the returned std::map.
Todo:
Add xtd::registry and uncomment lines.

◆ get_folder_path() [1/2]

static xtd::ustring xtd::environment::get_folder_path ( environment::special_folder  folder)
static

Gets the path to the system special folder that is identified by the specified enumeration.

Parameters
folderOne of enumeration values that identifies a system special folder.
Returns
The path to the specified system special folder, if that folder physically exists on your computer; otherwise, an empty string ("").
Remarks
This method retrieves the path to a system special folder, such as Program Files, Programs, System, or Startup, which can be used to access common information. Special folders are set by default by the system, or explicitly by the user, when installing a version of Windows.
Examples:
directory_assert.cpp, directory_assert_are_equal.cpp, directory_assert_are_not_equal.cpp, directory_assume.cpp, directory_assume_are_equal.cpp, directory_assume_are_not_equal.cpp, directory_valid.cpp, directory_valid_are_equal.cpp, directory_valid_are_not_equal.cpp, environment_current_directory.cpp, open_file_dialog.cpp, process_form.cpp, save_file_box.cpp, save_file_dialog.cpp, and test_forms.cpp.

◆ get_folder_path() [2/2]

static xtd::ustring xtd::environment::get_folder_path ( environment::special_folder  folder,
environment::special_folder_option  option 
)
static

Gets the path to the system special folder that is identified by the specified enumeration, and uses a specified option for accessing special folders.

Parameters
folderOne of the enumeration values that identifies a system special folder.
optionOne of the enumeration values that specifies options to use for accessing a special folder.
Returns
The path to the specified system special folder, if that folder physically exists on your computer; otherwise, an empty string ("").
Remarks
This method retrieves the path to a system special folder, such as Program Files, Programs, System, or Startup, which can be used to access common information. Special folders are set by default by the system, or explicitly by the user, when installing a version of Windows.

◆ get_logical_drives()

static xtd::collections::specialized::string_vector xtd::environment::get_logical_drives ( )
static

Returns an array of string containing the names of the logical drives on the current computer.

Returns
An array of strings where each element contains the name of a logical drive. For example, if the computer's hard drive is the first logical drive, the first element returned is "C:\".

◆ has_shutdown_started()

static bool xtd::environment::has_shutdown_started ( )
static

Gets a value that indicates whether the current application domain is shutting down.

Returns
bool true if the current application domain is shutting down; otherwise, false.
Remarks
At this time the return value is always false for macOS and linux.

◆ is_64_bit_operating_system()

static bool xtd::environment::is_64_bit_operating_system ( )
staticnoexcept

Determines whether the current operating system is a 64-bit operating system.

Returns
true if the operating system is 64-bit; otherwise, false.

◆ is_64_bit_process()

static bool xtd::environment::is_64_bit_process ( )
staticnoexcept

Determines whether the current process is a 64-bit process.

Returns
true if the process is 64-bit; otherwise, false.

◆ locale()

static std::locale xtd::environment::locale ( )
staticnoexcept

Gets a copy of the global C++ locale, which is the locale most recently used as the argument to See std::locale::global or a copy of See std::locale::classic() if no call to See std::locale::global has been made.

Returns
A copy of the global C++ locale.
Remarks
See std::locale for more information.

◆ machine_name()

static xtd::ustring xtd::environment::machine_name ( )
static

Gets the NetBIOS name of this local computer.

Returns
A string containing the name of this computer.
Remarks
The name of this computer is established at system startup when the name is read from the registry. If this computer is a node in a cluster, the name of the node is returned.

◆ new_line() [1/2]

static xtd::ustring xtd::environment::new_line ( )
staticnoexcept

◆ new_line() [2/2]

template<class char_t , class traits_t >
static std::basic_ostream<char_t, traits_t>& xtd::environment::new_line ( std::basic_ostream< char_t, traits_t > &  os)
inlinestatic

Inserts a new-line character and flushes the stream.

Parameters
osOutput stream object affected. Because this function is a manipulator, it is designed to be used alone with no arguments in conjunction with the insertion (<<) operations on output streams (see example below).
Returns
Argument os.

◆ os_version()

static xtd::operating_system xtd::environment::os_version ( )
staticnoexcept

Gets an xtd::operating_system object that contains the current platform identifier and version number.

Returns
An object that contains the platform identifier and version number.
Examples:
environment.cpp, process_form.cpp, and version_os.cpp.

◆ processor_count()

static uint32 xtd::environment::processor_count ( )
static

Gets the number of processors on the current machine.

Returns
The 32-bit unsigned integer that specifies the number of processors on the current machine. There is no default. If the current machine contains multiple processor groups, this property returns the number of logical processors that are available for use.
Examples:
form_and_thread.cpp.

◆ processor_information()

static xtd::processor xtd::environment::processor_information ( )
static

Gets an xtd::processor object that contains the processor identifier.

Returns
An object that contains the procesor identifier.

◆ quick_exit() [1/3]

static void xtd::environment::quick_exit ( )
staticnoexcept

Terminates this process and returns an exit code to the operating system without completely cleaning the resources..

Remarks
Use xtd::environment::exit_code method to return to the operating system.
Examples:
environment_program_exit.cpp.

◆ quick_exit() [2/3]

static void xtd::environment::quick_exit ( int32  exit_code)
staticnoexcept

Terminates this process and returns an exit code to the operating system without completely cleaning the resources..

Parameters
exit_codeThe exit code to return to the operating system. Use 0 (zero) to indicate that the process completed successfully.
Remarks
For the exit_code parameter, use a non-zero number to indicate an error. In your application, you can define your own error codes in an enumeration, and return the appropriate error code based on the scenario. For example, return a value of 1 to indicate that the required file is not present, and a value of 2 to indicate that the file is in the wrong format.

◆ quick_exit() [3/3]

static void xtd::environment::quick_exit ( xtd::exit_status  exit_status)
staticnoexcept

Terminates this process and returns an exit status to the operating system without completely cleaning the resources..

Parameters
exit_statusOne of xtd::exit_status values.

◆ raise()

static void xtd::environment::raise ( xtd::signal  signal)
static

Sends xtd::signal to the program. The xtd::environment::cancel_signal event is invoked with the specified signal.

Parameters
signalOne of xtd::signal values that represents the signal sent to the program.
Examples:
environment_cancel_signal.cpp.

◆ set_environment_variable() [1/2]

static void xtd::environment::set_environment_variable ( const xtd::ustring variable,
const xtd::ustring value 
)
static

Creates, modifies, or deletes an environment variable stored in the current process.

Parameters
variableThe name of an environment variable.
valueA value to assign to variable.
Remarks
Calling this method is equivalent to calling the xtd::environment::set_environment_variable(xtd::ustring, xtd::ustring, environment_variable_target) overload with a value of xtd::environment_variable_target::process for the target argument.
If the value argument is not empty and the environment variable named by the variable parameter does not exist, the environment variable is created and assigned the contents of value. If it does exist, its value is modified. Because the environment variable is defined in the environment block of the current process only, it does not persist after the process has ended.
If value is empty and the environment variable named by variable exists, the environment variable is deleted. If variable does not exist, no error occurs even though the operation cannot be performed.

◆ set_environment_variable() [2/2]

static void xtd::environment::set_environment_variable ( const xtd::ustring variable,
const xtd::ustring value,
environment_variable_target  target 
)
static

Creates, modifies, or deletes an environment variable stored in the current process or in the Windows operating system registry key reserved for the current user or local machine.

Parameters
variableThe name of an environment variable.
valueA value to assign to variable.
Remarks
The xtd::environment::set_environment_variable(xtd::ustring, xtd::ustring, environment_variable_target) method lets you define an environment variable that is available to the current process (the xtd::environment_variable_target::process value). Environment variables that are unique to the current process environment block persist only until the process ends.
In addition, on Windows systems only, the xtd::environment::set_environment_variable(xtd::ustring, xtd::ustring, environment_variable_target) method lets you define an environment variable that is available to all processes that run on a machine (the xtd::environment_variable_target::machine value) and to all processes run by a user (the xtd::environment_variable_target::user value). Per-machine and per-user environment variables are copied into the environment block of the current process.
If the value argument is not empty and the environment variable named by the variable argument does not exist, the environment variable is created and assigned the contents of value. If it does exist, its value is modified.
If value is empty and the environment variable named by variable exists, the environment variable is deleted. If variable does not exist, no error occurs even though the operation cannot be performed.
Todo:
Add xtd::registry and uncomment lines.

◆ stack_trace()

static xtd::ustring xtd::environment::stack_trace ( )
static

Gets current stack trace information.

Returns
A string containing stack trace information. This value can be empty "".
Examples:
environment_stack_trace.cpp.

◆ system_directory()

static xtd::ustring xtd::environment::system_directory ( )
static

Gets the fully qualified path of the system directory.

Returns
A string containing a directory path.
Remarks
An example of the value returned is the string "C:\Windows".
Examples:
environment.cpp.

◆ system_page_size()

static size_t xtd::environment::system_page_size ( )
static

Gets the number of bytes in the operating system's memory page.

Returns
The number of bytes in the system memory page.

◆ target_type()

static xtd::target_type xtd::environment::target_type ( )
inlinestaticnoexcept

Gets an xtd::target_type object that contains the current target identifier.

Returns
An object that contains the target identifier.

◆ tick_count()

static std::chrono::milliseconds xtd::environment::tick_count ( )
static

Gets the number of milliseconds elapsed since the system started.

Returns
A 32-bit unsigned integer containing the amount of time in milliseconds that has passed since the last time the computer was started.
Examples:
environment_tick_count.cpp.

◆ toolkit_version()

static xtd::toolkit xtd::environment::toolkit_version ( )
static

Gets the current toolkit version.

Returns
The current toolkit version.

◆ user_administrator()

static bool xtd::environment::user_administrator ( )
static

Gets a value indicating whether the current user is an administrator.

Returns
bool true if the current user is an administrator; otherwise, false.

◆ user_domain_name()

static xtd::ustring xtd::environment::user_domain_name ( )
static

Gets the network domain name associated with the current user.

Returns
The network domain name associated with the current user.

◆ user_interactive()

static bool xtd::environment::user_interactive ( )
static

Gets a value indicating whether the current process is running in user interactive mode.

Returns
bool true if the current process is running in user interactive mode; otherwise, false.
Remarks
The user_interactive method reports false for a Os process or a service like IIS that runs without a user interface. If this property is false, do not display modal dialogs or message boxes because there is no graphical user interface for the user to interact with.
Return always true for now.
Todo:
check if process is an operating system process or service process...

◆ user_name()

static xtd::ustring xtd::environment::user_name ( )
static

Gets the user name of the person who is currently logged on to the operating system.

Returns
The user name of the person who is logged on to the operating system.
Examples:
environment.cpp, hello_world_environment.cpp, and hello_world_environment2.cpp.

◆ version()

static xtd::version xtd::environment::version ( )
staticnoexcept

Gets a version consisting of the major, minor, build, and revision numbers of the xtd framework.

Returns
The version of the xtd framework.

◆ working_set()

static int64 xtd::environment::working_set ( )
static

Gets the amount of physical memory mapped to the process context.

Returns
Int64 A 64-bit signed integer containing the number of bytes of physical memory mapped to the process context.
Remarks
Windows 98, Windows Millennium Edition, Linux, macOS, Android,... Platform Note: This property always returns zero.
Example
The following example displays the size of the working set of the computer that runs the code example.

◆ xtd_libraries()

static const xtd_library_collection& xtd::environment::xtd_libraries ( )
staticnoexcept

Gets an xtd::environment::xtd_library array that represent the xtd libraries name, version and paths.

Returns
an xtd::environment::xtd_library array.

Member Data Documentation

◆ cancel_signal

event<environment, signal_cancel_event_handler> xtd::environment::cancel_signal
static

Occurs when a signal is sent to the current process.

Remarks
This event is used in conjunction with xtd::signal_cancel_event_handler and xtd::signal_cancel_event_args. The xtd::environment::cancel_signal event enables a xtd::signal so the event handler can decide whether to continue executing or terminate.
For more information about handling events, see Handling and Raising Events.
Warning
The xtd::signal::interrupt and xtd::console_special_key::control_c use the same signal (SIGINT).
The xtd::signal::interrupt and xtd::console_special_key::control_c can be cancelled with xtd::environment::cancel_signal event or xtd::console::cancel_key_press event. Both of these events are called when SIGINT is raised.
Examples:
environment_cancel_signal.cpp.

◆ program_exit

event<environment, program_exit_event_handler> xtd::environment::program_exit
static

Occurs when the terminates normally (via xtd::environment::exit or returning from the main function).

Remarks
For more information about handling events, see Handling and Raising Events.
Examples:
application_application_exit.cpp, and environment_program_exit.cpp.

The documentation for this class was generated from the following file: