zeroc-ice 3.7.9.1 → 3.8.0

data/dist/ice/cpp/include/Ice/Plugin.h

@@ -0,0 +1,73 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef ICE_PLUGIN_H
+#define ICE_PLUGIN_H
+
+#include "Ice/BuiltinSequences.h"
+
+#include <memory>
+
+namespace Ice
+{
+    /// Represents a communicator plug-in. A plug-in generally adds a feature to a communicator, such as support for an
+    /// additional transport.
+    /// The communicator loads its plug-ins in two stages: the first stage creates the plug-ins, and the second stage
+    /// calls Plugin::initialize on each one.
+    /// @headerfile Ice/Ice.h
+    class ICE_API Plugin
+    {
+    public:
+        virtual ~Plugin();
+
+        /// Performs any necessary initialization steps.
+        virtual void initialize() = 0;
+
+        /// Destroys this plugin. This function is called when the communicator is destroyed.
+        virtual void destroy() = 0;
+    };
+
+    /// A shared pointer to a Plugin.
+    using PluginPtr = std::shared_ptr<Plugin>;
+
+    /// Manages the plug-ins of a communicator.
+    /// @headerfile Ice/Ice.h
+    class ICE_API PluginManager
+    {
+    public:
+        virtual ~PluginManager();
+
+        /// Initializes the configured plug-ins. The communicator automatically initializes the plug-ins by default, but
+        /// an application may need to interact directly with a plug-in prior to initialization. In this case, the
+        /// application must set `Ice.InitPlugins=0` and then invoke `initializePlugins` manually. The plug-ins are
+        /// initialized in the order in which they are loaded. If a plug-in throws an exception during initialization,
+        /// the communicator calls Plugin::destroy on the plug-ins that have already been initialized.
+        /// @throws InitializationException Thrown when the plug-ins have already been initialized.
+        virtual void initializePlugins() = 0;
+
+        /// Gets the installed plug-ins.
+        /// @return The names of the installed plug-ins.
+        /// @see #getPlugin
+        virtual StringSeq getPlugins() = 0;
+
+        /// Gets a plug-in by name.
+        /// @param name The plug-in's name.
+        /// @return The plug-in.
+        /// @throws NotRegisteredException Thrown when no plug-in is found with the given name.
+        virtual PluginPtr getPlugin(std::string_view name) = 0;
+
+        /// Installs a new plug-in.
+        /// @param name The plug-in's name.
+        /// @param pi The plug-in.
+        /// @throws AlreadyRegisteredException Thrown when a plug-in already exists with the given name.
+        virtual void addPlugin(std::string name, PluginPtr pi) = 0;
+
+        /// @private
+        /// Destroys this plug-in manager. Called when the communicator is being destroyed.
+        virtual void destroy() noexcept = 0;
+    };
+
+    /// A shared pointer to a PluginManager.
+    using PluginManagerPtr = std::shared_ptr<PluginManager>;
+}
+
+#endif

data/dist/ice/cpp/include/Ice/PluginFactory.h

@@ -0,0 +1,77 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef ICE_PLUGIN_FACTORY_H
+#define ICE_PLUGIN_FACTORY_H
+
+#include "CommunicatorF.h"
+#include "Config.h"
+#include "Ice/BuiltinSequences.h"
+#include "Plugin.h"
+
+#include <string>
+
+namespace Ice
+{
+    class Plugin;
+
+    /// A plug-in factory function responsible for creating an Ice plug-in.
+    /// For plug-ins that may be loaded dynamically, these functions are extern "C" to avoid name mangling.
+    /// @param communicator The communicator in which the plug-in will be installed.
+    /// @param name The name assigned to the plug-in.
+    /// @param args Additional arguments included in the plug-in's configuration.
+    /// @return The new plug-in object.
+    using PluginFactoryFunc = Plugin* (*)(const CommunicatorPtr& communicator,
+                                          const std::string& name,
+                                          const StringSeq& args);
+
+    /// Represents a plug-in factory.
+    /// @see InitializeData::pluginFactories
+    struct PluginFactory
+    {
+        /// The default and preferred name for plug-ins created by this factory.
+        std::string pluginName;
+
+        /// The factory function.
+        PluginFactoryFunc factoryFunc;
+    };
+
+    // Transport plug-ins provided by the Ice library.
+
+    /// Returns the factory for the UDP transport plug-in, IceUDP.
+    /// @return The factory for the IceUDP plug-in.
+    /// @remark You only need to call this function if you are using static libraries. The Ice shared library adds the
+    /// IceUDP plug-in automatically.
+    /// @see InitializationData::pluginFactories
+    ICE_API PluginFactory udpPluginFactory();
+
+    /// Returns the factory for the WebSocket transport plug-in, IceWS.
+    /// @return The factory for the IceWS plug-in.
+    /// @remark You only need to call this function if you are using static libraries. The Ice shared library adds the
+    /// IceWS plug-in automatically.
+    /// @see InitializationData::pluginFactories
+    ICE_API PluginFactory wsPluginFactory();
+
+#if (defined(__APPLE__) && TARGET_OS_IPHONE != 0) || defined(ICE_DOXYGEN)
+    /// Returns the factory for the iAP transport plug-in, IceIAP.
+    /// @return The factory for the IceIAP plug-in.
+    /// @see InitializationData::pluginFactories
+    ICE_API PluginFactory iapPluginFactory();
+#endif
+
+    /// @cond INTERNAL
+    // Not exported because they are always registered by the Ice library.
+    PluginFactory tcpPluginFactory();
+    PluginFactory sslPluginFactory();
+    /// @endcond
+}
+
+namespace IceInternal
+{
+    /// Indicates whether the current Ice library provides the minimum set of built-in plug-ins, namely IceTCP and
+    /// IceSSL.
+    /// @return `true` when the Ice library provides the minimum set of built-in plug-ins, `false` when it also provides
+    /// IceUDP and IceWS.
+    ICE_API bool isMinBuild();
+}
+
+#endif

data/dist/ice/cpp/include/Ice/PopDisableWarnings.h

@@ -0,0 +1,16 @@
+// Copyright (c) ZeroC, Inc.
+
+/*! \file
+    \hideincludedbygraph
+*/
+
+// No pragma once as this file can be included several times in a translation
+// unit
+
+#if defined(_MSC_VER)
+#    pragma warning(pop)
+#elif defined(__clang__)
+#    pragma clang diagnostic pop
+#elif defined(__GNUC__)
+#    pragma GCC diagnostic pop
+#endif

data/dist/ice/cpp/include/Ice/Properties.h

@@ -0,0 +1,307 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef ICE_PROPERTIES_H
+#define ICE_PROPERTIES_H
+
+#include "Config.h"
+#include "Ice/BuiltinSequences.h"
+#include "Ice/PropertyDict.h"
+#include "PropertiesF.h"
+#include "StringConverter.h"
+
+#include <mutex>
+#include <set>
+#include <string>
+#include <string_view>
+
+namespace Ice
+{
+    /// Converts an argument vector into a string sequence.
+    /// @param argc The number of arguments in argv.
+    /// @param argv The arguments.
+    /// @return A string sequence containing the arguments.
+    ICE_API StringSeq argsToStringSeq(int argc, const char* const argv[]);
+
+#if defined(_WIN32) || defined(ICE_DOXYGEN)
+    /// @copydoc argsToStringSeq(int, const char* const[])
+    /// @remark Windows only.
+    ICE_API StringSeq argsToStringSeq(int argc, const wchar_t* const argv[]);
+#endif
+
+    /// Updates @p argv to match the contents of @p seq. This function assumes that @p seq contains only elements of
+    /// @p argv. The function shifts the argument vector elements so that the vector matches the contents of the
+    /// sequence.
+    /// @param seq The string sequence returned from a call to #argsToStringSeq.
+    /// @param[in,out] argc The number of arguments, updated to reflect the size of the sequence.
+    /// @param argv The arguments, shifted to match @p seq.
+    ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const char* argv[]);
+
+    /// @copydoc stringSeqToArgs(const StringSeq&, int&, const char*[])
+    inline void stringSeqToArgs(const StringSeq& seq, int& argc, char* argv[])
+    {
+        return stringSeqToArgs(seq, argc, const_cast<const char**>(argv));
+    }
+
+#if defined(_WIN32) || defined(ICE_DOXYGEN)
+    /// @copydoc stringSeqToArgs(const StringSeq&, int&, const char*[])
+    /// @remark Windows only.
+    ICE_API void stringSeqToArgs(const StringSeq& seq, int& argc, const wchar_t* argv[]);
+
+    /// @copydoc stringSeqToArgs(const StringSeq&, int&, const char*[])
+    /// @remark Windows only.
+    inline void stringSeqToArgs(const StringSeq& seq, int& argc, wchar_t* argv[])
+    {
+        return stringSeqToArgs(seq, argc, const_cast<const wchar_t**>(argv));
+    }
+#endif
+
+    /// Represents a set of properties used to configure Ice and Ice-based applications. A property is a key/value pair,
+    /// where both the key and the value are strings. By convention, property keys should have the form
+    /// `application-name[.category[.sub-category]].name`.
+    /// @remark This class is thread-safe: multiple threads can safely read and write the properties.
+    /// @headerfile Ice/Ice.h
+    class ICE_API Properties final
+    {
+    public:
+        /// Constructs an empty property set.
+        Properties() = default;
+
+        /// Constructs a property set, loads the configuration files specified by the `Ice.Config` property or the
+        /// `ICE_CONFIG` environment variable, and then parses Ice properties from @p args.
+        /// @param args The command-line arguments. This constructor parses arguments starting with `--` and one
+        /// of the reserved prefixes (Ice, IceSSL, etc.) as properties and removes these elements from the vector. If
+        /// there is an argument starting with `--Ice.Config`, this constructor loads the specified configuration file.
+        /// When the same property is set in a configuration file and through a command-line argument, the command-line
+        /// setting takes precedence.
+        /// @param defaults Default values for the new Properties object. Settings in configuration files and the
+        /// arguments override these defaults.
+        /// @remarks This constructor loads properties from files specified by the `ICE_CONFIG` environment variable
+        /// when there is no `--Ice.Config` command-line argument.
+        explicit Properties(StringSeq& args, const PropertiesPtr& defaults = nullptr);
+
+        /// Constructs a property set, loads the configuration files specified by the `Ice.Config` property or the
+        /// `ICE_CONFIG` environment variable, and then parses Ice properties from @p args.
+        /// @tparam ArgvT The type of the argument vector, such as char**, const char**, or wchar_t** (on Windows).
+        /// @param[in, out] argc The number of command-line arguments in @p argv. When this constructor
+        /// parses properties from @p argv, it reshuffles the arguments so that the remaining arguments start at the
+        /// beginning of @p argv, and updates @p argc accordingly.
+        /// @param argv The command-line arguments. This constructor parses arguments starting with `--` and one of the
+        /// reserved prefixes (Ice, IceSSL, etc.) as properties. If there is an argument starting with `--Ice.Config`,
+        /// this constructor loads the specified configuration file. When the same property is set in a configuration
+        /// file and through a command-line argument, the command-line setting takes precedence.
+        /// @param defaults Default values for the new Properties object. Settings in configuration files and the
+        /// arguments override these defaults.
+        /// @remarks This constructor loads properties from files specified by the `ICE_CONFIG` environment variable
+        /// when there is no `--Ice.Config` command-line argument.
+        template<typename ArgvT>
+        Properties(int& argc, ArgvT argv, const PropertiesPtr& defaults = nullptr) : Properties{defaults}
+        {
+            StringSeq args = argsToStringSeq(argc, argv);
+            loadArgs(args);
+            stringSeqToArgs(args, argc, argv);
+        }
+
+        /// @private
+        /// Constructs an empty property set with additional reserved prefixes such as "IceBox", "IceStorm", etc.
+        /// @param firstOptInPrefix The first opt-in prefix.
+        /// @param remainingOptInPrefixes The remaining opt-in prefixes.
+        template<typename... T>
+        Properties(std::string firstOptInPrefix, T... remainingOptInPrefixes)
+            : _optInPrefixes{std::move(firstOptInPrefix), std::move(remainingOptInPrefixes)...}
+        {
+        }
+
+        /// @private
+        /// Constructs a property set, loads the configuration files specified by the `Ice.Config` property or the
+        /// `ICE_CONFIG` environment variable, and then parses Ice properties from @p args.
+        /// @tparam ArgvT The type of the argument vector, such as char**, const char**, or wchar_t** (on Windows).
+        /// @param[in, out] argc The number of command-line arguments in @p argv.
+        /// @param argv The command-line arguments. This constructor parses arguments starting with `--` and one of the
+        /// reserved prefixes (Ice, IceSSL, etc.) as properties and moves these arguments to the end of the array. If
+        /// there is an argument starting with `--Ice.Config`, this constructor loads the specified configuration file.
+        /// When the same property is set in a configuration file and through a command-line argument, the command-line
+        /// setting takes precedence.
+        /// @param firstOptInPrefix The first opt-in prefix.
+        /// @param remainingOptInPrefixes The remaining opt-in prefixes.
+        /// @remarks This constructor loads properties from files specified by the `ICE_CONFIG` environment variable
+        /// when there is no `--Ice.Config` command-line argument.
+        template<typename ArgvT, typename... T>
+        Properties(int& argc, ArgvT argv, std::string firstOptInPrefix, T... remainingOptInPrefixes)
+            : Properties{std::move(firstOptInPrefix), std::move(remainingOptInPrefixes)...}
+        {
+            StringSeq args = argsToStringSeq(argc, argv);
+            loadArgs(args);
+            stringSeqToArgs(args, argc, argv);
+        }
+
+        /// Copy constructor.
+        /// @param source The property set to copy.
+        Properties(const Properties& source);
+
+        Properties(Properties&&) = delete;
+        Properties& operator=(const Properties& rhs) = delete;
+        Properties& operator=(Properties&& rhs) = delete;
+
+        /// Gets a property by key.
+        /// @param key The property key.
+        /// @return The property value, or the empty string if the property is not set.
+        /// @see #setProperty
+        std::string getProperty(std::string_view key);
+
+        /// Gets an Ice property by key.
+        /// @param key The property key.
+        /// @return The property value, or the default value for this property if the property is not set.
+        /// @throws PropertyException Thrown when the property is not a known Ice property.
+        /// @see #setProperty
+        std::string getIceProperty(std::string_view key);
+
+        /// Gets a property by key.
+        /// @param key The property key.
+        /// @param value The default value to return if the property is not set.
+        /// @return The property value or the default value if the property is not set.
+        /// @see #setProperty
+        std::string getPropertyWithDefault(std::string_view key, std::string_view value);
+
+        /// Gets a property as an integer.
+        /// @param key The property key.
+        /// @return The property value interpreted as an integer, or 0 if the property is not set.
+        /// @throws PropertyException Thrown when the property value is not a valid integer.
+        /// @see #setProperty
+        int getPropertyAsInt(std::string_view key);
+
+        /// Gets an Ice property as an integer.
+        /// @param key The property key.
+        /// @return The property value interpreted as an integer, or the default value if the property is not set.
+        /// @throws PropertyException Thrown when the property is not a known Ice property or the value is not a valid
+        /// integer.
+        /// @see #setProperty
+        int getIcePropertyAsInt(std::string_view key);
+
+        /// Gets a property as an integer.
+        /// @param key The property key.
+        /// @param value The default value to return if the property does not exist.
+        /// @return The property value interpreted as an integer, or the default value if the property is not set.
+        /// @throws PropertyException Thrown when the property value is not a valid integer.
+        /// @see #setProperty
+        int getPropertyAsIntWithDefault(std::string_view key, int value);
+
+        /// Gets a property as a list of strings. The strings must be separated by whitespace or comma. The strings in
+        /// the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
+        /// mismatched, an empty list is returned. Within single quotes or double quotes, you can escape the quote in
+        /// question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// @param key The property key.
+        /// @return The property value interpreted as a list of strings, or an empty list if the property is not set.
+        /// @see #setProperty
+        StringSeq getPropertyAsList(std::string_view key);
+
+        /// Gets an Ice property as a list of strings. The strings must be separated by whitespace or comma. The strings
+        /// in the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
+        /// mismatched, the default list is returned.  Within single quotes or double quotes, you can escape the quote
+        /// in question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// @param key The property key.
+        /// @return The property value interpreted as a list of strings, or the default value if the property is not
+        ///     set.
+        /// @throws PropertyException Thrown when the property is not a known Ice property.
+        /// @see #setProperty
+        StringSeq getIcePropertyAsList(std::string_view key);
+
+        /// Gets a property as a list of strings. The strings must be separated by whitespace or comma. The strings in
+        /// the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
+        /// mismatched, the default list is returned. Within single quotes or double quotes, you can escape the quote
+        /// in question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// @param key The property key.
+        /// @param value The default value to use if the property is not set.
+        /// @return The property value interpreted as a list of strings, or the default value if the property is not
+        ///     set.
+        /// @see #setProperty
+        StringSeq getPropertyAsListWithDefault(std::string_view key, const StringSeq& value);
+
+        /// Gets all properties whose keys begin with @p prefix. If @p prefix is the empty string, then all properties
+        /// are returned.
+        /// @param prefix The prefix to search for.
+        /// @return The matching property set.
+        PropertyDict getPropertiesForPrefix(std::string_view prefix);
+
+        /// Sets a property. To unset a property, set it to the empty string.
+        /// @param key The property key.
+        /// @param value The property value.
+        /// @see #getProperty
+        void setProperty(std::string_view key, std::string_view value);
+
+        /// Gets a sequence of command-line options that is equivalent to this property set. Each element of the
+        /// returned sequence is a command-line option of the form `--key=value`.
+        /// @return The command line options for this property set.
+        StringSeq getCommandLineOptions();
+
+        /// Converts a sequence of command-line options into properties. All options that start with `--prefix.` are
+        /// converted into properties. If the prefix is empty, all options that begin with `--` are converted to
+        /// properties.
+        /// @param prefix The property prefix, or the empty string to convert all options starting with `--`.
+        /// @param options The command-line options.
+        /// @return The command-line options that do not start with the specified prefix, in their original order.
+        StringSeq parseCommandLineOptions(std::string_view prefix, const StringSeq& options);
+
+        /// Converts a sequence of command-line options into properties. All options that start with one of the
+        /// reserved Ice prefixes (`--Ice`, `--IceSSL`, etc.) are converted into properties.
+        /// @param options The command-line options.
+        /// @return The command-line options that do not start with one of the reserved prefixes, in their original
+        /// order.
+        StringSeq parseIceCommandLineOptions(const StringSeq& options);
+
+        /// Loads properties from a file.
+        /// @param file The property file.
+        void load(std::string_view file);
+
+        /// Creates a copy of this property set.
+        /// @return A copy of this property set.
+        PropertiesPtr clone() { return std::make_shared<Properties>(*this); }
+
+        /// Gets the properties that were never read.
+        /// @return A list of unused properties.
+        std::set<std::string> getUnusedProperties();
+
+        /// Parses a sequence of options into a map of key value pairs starting with a prefix. The options are expected
+        /// to be of the form `--key=value`.
+        /// @param prefix The prefix to match.
+        /// @param options The options to parse.
+        /// @return A pair containing a map of matched key value pairs and a sequence of unmatched options.
+        static std::pair<PropertyDict, StringSeq> parseOptions(std::string_view prefix, const StringSeq& options);
+
+    private:
+        static std::optional<std::pair<std::string, std::string>>
+        parseLine(std::string_view, const StringConverterPtr&);
+
+        Properties(const PropertiesPtr& defaults);
+
+        void loadArgs(StringSeq& args);
+        void loadConfig();
+
+        struct PropertyValue
+        {
+            PropertyValue() : used(false) {}
+
+            PropertyValue(std::string v, bool u) : value(std::move(v)), used(u) {}
+
+            std::string value;
+            bool used;
+        };
+
+        std::map<std::string, PropertyValue, std::less<>> _propertySet;
+        // List of "opt-in" property prefixes to allow in the property set. Setting a property for a property prefix
+        // that is opt-in (eg. IceGrid, IceStorm, Glacier2, etc.) but not in this list is considered an error.
+        std::vector<std::string> _optInPrefixes;
+        mutable std::mutex _mutex;
+    };
+
+    /// Creates a new shared Properties object.
+    /// @param args The arguments to forward to `make_shared<Properties>`.
+    /// @return A new property set.
+    /// @remarks This function is provided for backwards compatibility. New code should call
+    /// `std::make_shared<Properties>` directly.
+    template<class... T> inline PropertiesPtr createProperties(T&&... args)
+    {
+        return std::make_shared<Properties>(std::forward<T>(args)...);
+    }
+}
+
+#endif

data/dist/ice/cpp/include/Ice/PropertiesF.h

@@ -0,0 +1,19 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef ICE_PROPERTIES_F_H
+#define ICE_PROPERTIES_F_H
+
+#include <memory>
+
+namespace Ice
+{
+    class Properties;
+
+    /// A shared pointer to a Properties.
+    using PropertiesPtr = std::shared_ptr<Properties>;
+
+    class PropertiesAdmin;
+    class PropertiesAdminPrx;
+}
+
+#endif