Attachment class

Author: asfernandes

src/lib/Attachment.cpp

@@ -0,0 +1,91 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 Adriano dos Santos Fernandes
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "Attachment.h"
+#include "Client.h"
+#include "Exception.h"
+
+using namespace fbcpp;
+using namespace fbcpp::impl;
+
+
+Attachment::Attachment(Client& client, const std::string& uri, const AttachmentOptions& options)
+	: client{client}
+{
+	const auto master = client.getMaster();
+
+	const auto status = client.newStatus();
+	StatusWrapper statusWrapper{client, status.get()};
+
+	auto dpbBuilder = fbUnique(master->getUtilInterface()->getXpbBuilder(&statusWrapper, fb::IXpbBuilder::DPB,
+		reinterpret_cast<const std::uint8_t*>(options.getDpb().data()),
+		static_cast<unsigned>(options.getDpb().size())));
+
+	if (const auto connectionCharSet = options.getConnectionCharSet())
+		dpbBuilder->insertString(&statusWrapper, isc_dpb_lc_ctype, connectionCharSet->c_str());
+
+	if (const auto userName = options.getUserName())
+		dpbBuilder->insertString(&statusWrapper, isc_dpb_user_name, userName->c_str());
+
+	if (const auto password = options.getPassword())
+		dpbBuilder->insertString(&statusWrapper, isc_dpb_password, password->c_str());
+
+	if (const auto role = options.getRole())
+		dpbBuilder->insertString(&statusWrapper, isc_dpb_sql_role_name, role->c_str());
+
+	auto dispatcher = fbRef(master->getDispatcher());
+	const auto dpbBuffer = dpbBuilder->getBuffer(&statusWrapper);
+	const auto dpbBufferLen = dpbBuilder->getBufferLength(&statusWrapper);
+
+	if (options.getCreateDatabase())
+		handle.reset(dispatcher->createDatabase(&statusWrapper, uri.c_str(), dpbBufferLen, dpbBuffer));
+	else
+		handle.reset(dispatcher->attachDatabase(&statusWrapper, uri.c_str(), dpbBufferLen, dpbBuffer));
+}
+
+void Attachment::disconnectOrDrop(bool drop)
+{
+	assert(isValid());
+
+	const auto status = client.newStatus();
+	StatusWrapper statusWrapper{client, status.get()};
+
+	if (drop)
+		handle->dropDatabase(&statusWrapper);
+	else
+		handle->detach(&statusWrapper);
+
+	handle.reset();
+}
+
+
+void Attachment::disconnect()
+{
+	disconnectOrDrop(false);
+}
+
+void Attachment::dropDatabase()
+{
+	disconnectOrDrop(true);
+}

src/lib/Attachment.h

@@ -0,0 +1,263 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 Adriano dos Santos Fernandes
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#ifndef FBCPP_ATTACHMENT_H
+#define FBCPP_ATTACHMENT_H
+
+#include "fb-api.h"
+#include "SmartPtrs.h"
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+#include <cstddef>
+
+
+///
+/// fb-cpp namespace.
+///
+namespace fbcpp
+{
+	class Client;
+
+	///
+	/// Represents options used when creating an Attachment object.
+	///
+	class AttachmentOptions final
+	{
+	public:
+		///
+		/// Returns the character set which will be used for the connection.
+		///
+		const std::optional<std::string>& getConnectionCharSet() const
+		{
+			return connectionCharSet;
+		}
+
+		///
+		/// Sets the character set which will be used for the connection.
+		///
+		AttachmentOptions& setConnectionCharSet(const std::string& value)
+		{
+			connectionCharSet = value;
+			return *this;
+		}
+
+		///
+		/// Returns the user name which will be used to connect to the database.
+		///
+		const std::optional<std::string>& getUserName() const
+		{
+			return userName;
+		}
+
+		///
+		/// Sets the user name which will be used to connect to the database.
+		///
+		AttachmentOptions& setUserName(const std::string& value)
+		{
+			userName = value;
+			return *this;
+		}
+
+		///
+		/// Returns the password which will be used to connect to the database.
+		///
+		const std::optional<std::string>& getPassword() const
+		{
+			return password;
+		}
+
+		///
+		/// Sets the password which will be used to connect to the database.
+		///
+		AttachmentOptions& setPassword(const std::string& value)
+		{
+			password = value;
+			return *this;
+		}
+
+		///
+		/// Returns the role which will be used to connect to the database.
+		///
+		const std::optional<std::string>& getRole() const
+		{
+			return role;
+		}
+
+		///
+		/// Sets the role which will be used to connect to the database.
+		///
+		AttachmentOptions& setRole(const std::string& value)
+		{
+			role = value;
+			return *this;
+		}
+
+		///
+		/// Returns the DPB (Database Parameter Block) which will be used to connect to the database.
+		///
+		const std::vector<std::byte>& getDpb() const
+		{
+			return dpb;
+		}
+
+		///
+		/// Sets the DPB (Database Parameter Block) which will be used to connect to the database.
+		///
+		AttachmentOptions& setDpb(const std::vector<std::byte>& value)
+		{
+			dpb = value;
+			return *this;
+		}
+
+		///
+		/// Sets the DPB (Database Parameter Block) which will be used to connect to the database.
+		///
+		AttachmentOptions& setDpb(std::vector<std::byte>&& value)
+		{
+			dpb = std::move(value);
+			return *this;
+		}
+
+		///
+		/// Returns whether the database should be created instead of connected to.
+		///
+		bool getCreateDatabase() const
+		{
+			return createDatabase;
+		}
+
+		///
+		/// Sets whether the database should be created instead of connected to.
+		///
+		AttachmentOptions& setCreateDatabase(bool value)
+		{
+			createDatabase = value;
+			return *this;
+		}
+
+	private:
+		std::optional<std::string> connectionCharSet;
+		std::optional<std::string> userName;
+		std::optional<std::string> password;
+		std::optional<std::string> role;
+		std::vector<std::byte> dpb;
+		bool createDatabase = false;
+	};
+
+	///
+	/// Represents a connection to a Firebird database.
+	/// The Attachment must exist and remain valid while there are other objects using it, such as Transaction and
+	/// Statement.
+	///
+	class Attachment final
+	{
+	public:
+		///
+		/// Constructs an Attachment object that connects to (or creates) the database specified by the URI
+		/// using the specified Client object and options.
+		///
+		explicit Attachment(Client& client, const std::string& uri, const AttachmentOptions& options = {});
+
+		///
+		/// Move constructor.
+		/// A moved Attachment object becomes invalid.
+		///
+		Attachment(Attachment&& o) noexcept
+			: client{o.client},
+			  handle{std::move(o.handle)}
+		{
+		}
+
+		Attachment& operator=(Attachment&&) = delete;
+
+		Attachment(const Attachment&) = delete;
+		Attachment& operator=(const Attachment&) = delete;
+
+		///
+		/// Disconnects from the database.
+		///
+		~Attachment() noexcept
+		{
+			if (isValid())
+			{
+				try
+				{
+					disconnectOrDrop(false);
+				}
+				catch (...)
+				{
+					// swallow
+				}
+			}
+		}
+
+	public:
+		///
+		/// Returns whether the Attachment object is valid.
+		///
+		bool isValid() noexcept
+		{
+			return handle != nullptr;
+		}
+
+		///
+		/// Returns the Client object reference used to create this Attachment object.
+		///
+		Client& getClient() noexcept
+		{
+			return client;
+		}
+
+		///
+		/// Returns the internal Firebird IAttachment handle.
+		///
+		FbRef<fb::IAttachment> getHandle() noexcept
+		{
+			return handle;
+		}
+
+		///
+		/// Disconnects from the database.
+		///
+		void disconnect();
+
+		///
+		/// Drops the database.
+		///
+		void dropDatabase();
+
+	private:
+		void disconnectOrDrop(bool drop);
+
+	private:
+		Client& client;
+		FbRef<fb::IAttachment> handle;
+	};
+}  // namespace fbcpp
+
+
+#endif  // FBCPP_ATTACHMENT_H

src/lib/fb-cpp.h

@@ -26,5 +26,6 @@
 #define FBCPP_H
 
 #include "Client.h"
+#include "Attachment.h"
 
 #endif  // FBCPP_H