diff --git a/Package.swift b/Package.swift index 95ec840..c661d71 100644 --- a/Package.swift +++ b/Package.swift @@ -36,24 +36,24 @@ let package = Package( ]), .binaryTarget( name:"GMP", - url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0-rc5/gmp-6.3.0.xcframework.zip", - checksum: "2a7e88b4a73c43772037ae14100a3ad47060464a8a0c48bfecb29ba3584b6ca3"), + url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0/gmp-6.3.0.xcframework.zip", + checksum: "ce6cf0eed23bc77ee42022753e51a0cb3826ab486094c56cf2101b92935b858c"), .binaryTarget( name:"POCO", - url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0-rc5/poco-1.13.2.xcframework.zip", - checksum: "6d154cf6734d574b2358cd1d52997c5e4e10f5ae27dd9d2715704b50cd9ccca9"), + url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0/poco-1.13.2.xcframework.zip", + checksum: "4cf1de72810bcabce2393e023f3aae299775cc68ea7314abc8c9d532f4c2348e"), .binaryTarget( name:"PSON", - url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0-rc5/pson-1.0.7.xcframework.zip", - checksum: "20bd578fc4f54af200d9915bc7dcd8cc60464b62591140cc25d301a8bae3989a"), + url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0/pson-1.0.7.xcframework.zip", + checksum: "c4a4cbaf063ebfcbb78b7e5396507664caed95be9c5d49013623974260ea1275"), .binaryTarget( name:"OpenSSL", - url:"https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0-rc5/openssl-3.0.17.xcframework.zip", - checksum: "69b9074f3a74805f43288ab71c06db00c9597e940ef0732ffa6ce842b8fae91a"), + url:"https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0/openssl-3.0.17.xcframework.zip", + checksum: "f062d32b63759750c6b38c82f289f686cea8e60eb6a3c9fa87245b9fdaa10c46"), .binaryTarget( name:"PrivMXEndpoint", - url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0-rc5/privmx-endpoint-v2.6.0-rc5.xcframework.zip", - checksum: "6f917ab9058382a5f0429884b9099a89603a84487711023f0d799725fd8ab224") + url: "https://github.com/simplito/privmx-endpoint-xcframeworks/releases/download/2.6.0/privmx-endpoint-v2.6.0.xcframework.zip", + checksum: "62e7ce5c1fa193a11a45a449c083821f315686934de064aa6e1e2e8adc945c57") ], cxxLanguageStandard: .cxx17 diff --git a/Sources/PrivMXEndpointSwift/Core/BackendRequester.swift b/Sources/PrivMXEndpointSwift/Core/BackendRequester.swift index 2a2ab60..c0fee3a 100644 --- a/Sources/PrivMXEndpointSwift/Core/BackendRequester.swift +++ b/Sources/PrivMXEndpointSwift/Core/BackendRequester.swift @@ -12,33 +12,27 @@ import Foundation import PrivMXEndpointSwiftNative -/// Tool for direct requests to PrivMX Bridge. +/// 'BackendRequester' provides functions to call PrivMX Bridge API. public enum BackendRequester{ /// Makes a direct request to PrivMX Bridge. - /// - /// This function allows you to make direct API requests to PrivMX Bridge with the required authorization and parameters. The response is returned as a string, representing the result of the request. - /// - /// - Parameters: - /// - serverUrl: The URL of PrivMX cloud server to which the request will be sent. - /// - memberToken: The authorization token for the member making the request. - /// - method: The API method or endpoint to be called on PrivMX Bridge. - /// - paramsAsJson: The parameters for the request, formatted as a JSON string. - /// - /// - Throws: - /// - `PrivMXEndpointError.failedRequestingBackend` if the request to the backend fails due to any error from the bridge or incorrect request formatting. - /// - Any other unexpected errors that might occur during the execution of the request. - /// - /// - Returns: - /// - A string containing the response from PrivMX Bridge, typically in JSON format. + /// + /// - Parameter serverUrl: PrivMX Bridge server URL + /// - Parameter accessToken: token for authorization (see PrivMX Bridge API for more details) + /// - Parameter method: API method to call + /// - Parameter paramsAsJson: API method's parameters in JSON format + /// + /// - Throws: `PrivMXEndpointError.failedRequestingBackend` if the request to the backend fails due to any error from the bridge or incorrect request formatting. And any other unexpected errors that might occur during the execution of the request. + /// + /// - Returns: JSON string representing raw server response public static func backendRequest( serverUrl: std.string, - memberToken: std.string, + accessToken: std.string, method: std.string, paramsAsJson: std.string ) throws -> std.string { let res = privmx.NativeBackendRequesterWrapper.backendRequest(serverUrl, - memberToken, + accessToken, method, paramsAsJson) guard res.error.value == nil else{ @@ -53,21 +47,29 @@ public enum BackendRequester{ return result } - /// Makes a direct request to PrivMX Bridge. - /// - /// This function allows you to make direct API requests to PrivMX Bridge with the required parameters. The response is returned as a string, representing the result of the request. + @available(*, deprecated, renamed: "backendRequest(serverUrl:accessToken:method:paramsAsJson:)") + public static func backendRequest( + serverUrl: std.string, + memberToken: std.string, + method: std.string, + paramsAsJson: std.string + ) throws -> std.string { + try self.backendRequest( + serverUrl: serverUrl, + accessToken: memberToken, + method: method, + paramsAsJson: paramsAsJson) + } + + /// Sends request to PrivMX Bridge API. /// - /// - Parameters: - /// - serverUrl: The URL of PrivMX cloud server to which the request will be sent. - /// - method: The API method or endpoint to be called on PrivMX Bridge. - /// - paramsAsJson: The parameters for the request, formatted as a JSON string. + /// - Parameter serverUrl: PrivMX Bridge server URL + /// - Parameter method: API method to call + /// - Parameter paramsAsJson: API method's parameters in JSON format /// - /// - Throws: - /// - `PrivMXEndpointError.failedRequestingBackend` if the request to the backend fails due to any error from the bridge or incorrect request formatting. - /// - Any other unexpected errors that might occur during the execution of the request. + /// - Throws: `PrivMXEndpointError.failedRequestingBackend` if the request to the backend fails due to any error from the bridge or incorrect request formatting. And any other unexpected errors that might occur during the execution of the request. /// - /// - Returns: - /// - A string containing the response from PrivMX Bridge, typically in JSON format. + /// - Returns: JSON string representing raw server response public static func backendRequest( serverUrl: std.string, method: std.string, @@ -91,13 +93,13 @@ public enum BackendRequester{ /// Sends a request to PrivMX Bridge API using pair of API KEY ID and API KEY SECRET for authorization. /// - /// - Parameters: - /// - serverUrl: PrivMX Bridge server URL - /// - apiKeyId: API KEY ID (see PrivMX Bridge API for more details) - /// - apiKeySecret: API KEY SECRET (see PrivMX Bridge API for more details) - /// - mode: allows you to set whether the request should be signed (mode = 1) or plain (mode = 0) - /// - method: API method to call - /// - paramsAsJson: API method's parameters in JSON format + /// - Parameter serverUrl: PrivMX Bridge server URL + /// - Parameter apiKeyId: API KEY ID (see PrivMX Bridge API for more details) + /// - Parameter apiKeySecret: API KEY SECRET (see PrivMX Bridge API for more details) + /// - Parameter mode: allows you to set whether the request should be signed (mode = 1) or plain (mode = 0) + /// - Parameter method: API method to call + /// - Parameter paramsAsJson: API method's parameters in JSON format + /// /// - Returns: A string containing the response from PrivMX Bridge, typically in JSON format. public static func backendRequest( serverUrl: std.string, diff --git a/Sources/PrivMXEndpointSwift/Core/Connection.swift b/Sources/PrivMXEndpointSwift/Core/Connection.swift index a80bb1a..51af42d 100644 --- a/Sources/PrivMXEndpointSwift/Core/Connection.swift +++ b/Sources/PrivMXEndpointSwift/Core/Connection.swift @@ -15,6 +15,8 @@ import Cxx import CxxStdlib import PrivMXEndpointSwiftNative +/// 'Connection' represents and manages the current connection between the Endpoint and the Bridge server. +/// /// Swift wrapper for `privmx.NativeConnectionWrapper`, used to establish and manage secure connections with PrivMX platform. public class Connection{ @@ -37,17 +39,16 @@ public class Connection{ /// An instance of the wrapped C++ class. internal var api: privmx.NativeConnectionWrapper - /// Creates a new connection instance to PrivMX platform using a private key. - /// - /// The path to the certificates must be set beforehand using `setCertsPath()`. This connection is used to interact with secured operations such as Inboxes, Threads, and Stores. + /// Connects to the PrivMX Bridge server. /// - /// - Parameter userPrivKey: The user's private key in WIF format, required for authentication. - /// - Parameter solutionId: The ID of the Solution that the connection targets. - /// - Parameter bridgeUrl: The URL of PrivMX platform endpoint. + /// - Parameter userPrivKey: user's private key + /// - Parameter solutionId: ID of the Solution + /// - Parameter bridgeUrl: Bridge Server URL + /// - Parameter verificationOptions: PrivMX Bridge server instance verification options using a PKI server /// /// - Throws: `PrivMXEndpointError.failedConnecting` if establishing the connection fails. /// - /// - Returns: A `Connection` instance that can be used for further operations. + /// - Returns: Connection object public static func connect( userPrivKey: std.string, solutionId: std.string, @@ -104,17 +105,17 @@ public class Connection{ return Connection(api:result.pointee) } - /// Creates a new public connection to PrivMX platform. + /// Connects to the PrivMX Bridge Server as a guest user. /// /// The path to the certificates must be set beforehand using `setCertsPath()`. This type of connection is primarily used for public operations, such as inbound Inbox traffic, where authentication is not required. /// - /// - Parameter solutionId: The ID of the Solution that the connection targets. - /// - Parameter bridgeUrl: The URL of PrivMX platform endpoint. - /// - Parameter verificationOptions: Options used to verify if Bridge on given url is the one you expect. - /// + /// - Parameter solutionId: ID of the Solution + /// - Parameter bridgeUrl: Bridge Server URL + /// - Parameter verificationOptions: PrivMX Bridge server instance verification options using a PKI server + /// /// - Throws: `PrivMXEndpointError.failedConnecting` if establishing the connection fails. /// - /// - Returns: A public `Connection` instance that can be used for non-authenticated operations. + /// - Returns: Connection object public static func connectPublic( solutionId: std.string, bridgeUrl: std.string, @@ -166,13 +167,11 @@ public class Connection{ return Connection(api:result.pointee) } - /// Retrieves the unique ID of the connection. - /// - /// Each connection instance has a unique identifier that can be used to track and manage multiple connections. + /// Gets the ID of the current connection. /// /// - Throws: `PrivMXEndpointError.failedGettingConnectionId` if retrieving the connection ID fails. /// - /// - Returns: The unique ID of the current connection as an `Int64`. + /// - Returns: ID of the connection public func getConnectionId( ) throws -> Int64 { let res = api.getConnectionId() @@ -194,9 +193,7 @@ public class Connection{ self.api = api } - /// Disconnects the current connection to PrivMX platform. - /// - /// Once disconnected, the `Connection` instance, along with any associated API instances like `StoreApi` or `ThreadApi`, becomes unusable. It is important to call this method when the connection is no longer needed to free up resources. + ///Disconnects from the PrivMX Bridge server. /// /// - Throws: `PrivMXEndpointError.failedDisconnecting` if the disconnection process fails. public func disconnect( @@ -207,15 +204,15 @@ public class Connection{ } } - /// Lists all Contexts available to the currently connected user. + /// Gets a list of Contexts available for the user. /// /// Contexts represent different environments or groups to which the user has access. This method returns a list of these Contexts. /// - /// - Parameter query: A `PagingQuery` object that specifies the filtering and pagination options for the query. + /// - Parameter query: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingContexts` if listing the Contexts fails. /// - /// - Returns: A `ContextList` structure containing the total number of Contexts and a list of the retrieved Contexts. + /// - Returns: struct containing a list of Contexts public func listContexts( query: privmx.endpoint.core.PagingQuery )throws -> privmx.ContextList{ @@ -232,13 +229,13 @@ public class Connection{ return result } - /// Retrieves a list of Users from a particular Context. + /// Gets a list of users with their status and the last status change. /// - /// - parameter contextId: Id of the Context. + /// - parameter contextId: ID of the Context /// /// - throws: When the operation fails. /// - /// - returns: a list of UserInfo objects. + /// - returns: List of users with their status and the last status change public func listContextUsers( contextId: std.string, query: privmx.endpoint.core.PagingQuery @@ -275,13 +272,13 @@ public class Connection{ } } - /// Subscribe for the events on the given subscription query. + /// Subscribe for the Context events on the given subscription query. /// - /// - Parameter subscriptionQueries: list of queries + /// - Parameter subscriptionQueries: List of queries /// /// - Throws: When subscribing for events fails. /// - /// - Returns: list of subscriptionIds in maching order to subscriptionQueries. + /// - Returns: List of subscriptionIds in matching order to subscriptionQueries public func subscribeFor( subscriptionQueries: privmx.SubscriptionQueryVector ) throws -> privmx.SubscriptionIdVector { @@ -300,19 +297,23 @@ public class Connection{ /// Unsubscribe from events for the given subscriptionId. /// - /// - Parameter subscriptionIds: list of subscriptionId + /// - Parameter subscriptionIds: List of subscriptionId /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } } - + /// Generate subscription Query for the Context events. + /// + /// - Parameter eventType: type of event which you listen for + /// - Parameter selectorType: scope on which you listen for events + /// - Parameter selectorId: ID of the selector public func buildSubscriptionQuery( eventType: privmx.endpoint.core.EventType, selectorType: privmx.endpoint.core.EventSelectorType, diff --git a/Sources/PrivMXEndpointSwift/Core/Utils.swift b/Sources/PrivMXEndpointSwift/Core/Utils.swift index f94a367..eef326b 100644 --- a/Sources/PrivMXEndpointSwift/Core/Utils.swift +++ b/Sources/PrivMXEndpointSwift/Core/Utils.swift @@ -14,7 +14,9 @@ import PrivMXEndpointSwiftNative public enum Hex{ /// Encodes buffer to a string in Hex format. + /// /// - Parameter data: buffer to encode + /// /// - Returns: string in Hex format public static func encode( data: privmx.endpoint.core.Buffer @@ -34,7 +36,9 @@ public enum Hex{ } /// Decodes string in Hex to buffer. + /// /// - Parameter hex_data: string to decode + /// /// - Returns: buffer with decoded data public static func decode( hex_data: std.string @@ -53,7 +57,9 @@ public enum Hex{ } /// Checks if given string is in Hex format. + /// /// - Parameter data: string to check + /// /// - Returns: check result public static func `is`( data: std.string @@ -76,7 +82,9 @@ public enum Hex{ public enum Base32{ /// Encodes buffer to a string in Base32 format. + /// /// - Parameter data: buffer to encode + /// /// - Returns: string in Hex format public static func encode( data: privmx.endpoint.core.Buffer @@ -96,7 +104,9 @@ public enum Base32{ } /// Decodes string in Base32 to buffer. + /// /// - Parameter base32_data: string to decode + /// /// - Returns: buffer with decoded data public static func decode( base32_data: std.string @@ -115,7 +125,9 @@ public enum Base32{ } /// Checks if given string is in Base32 format. + /// /// - Parameter data: string to check + /// /// - Returns: check result public static func `is`( data: std.string @@ -138,7 +150,9 @@ public enum Base32{ public enum Base64{ /// Encodes buffer to a string in Base64 format. + /// /// - Parameter data: buffer to encode + /// /// - Returns: string in Hex format public static func encode( data: privmx.endpoint.core.Buffer @@ -158,7 +172,9 @@ public enum Base64{ } /// Decodes string in Base64 to buffer. + /// /// - Parameter base64_data: string to decode + /// /// - Returns: buffer with decoded data public static func decode( base64_data: std.string @@ -177,7 +193,9 @@ public enum Base64{ } /// Checks if given string is in Base64 format. + /// /// - Parameter data: string to check + /// /// - Returns: check result public static func `is`( data: std.string @@ -201,7 +219,9 @@ public enum Base64{ public enum Utils{ /// Removes all trailing whitespace. - /// - Parameter data: + /// + /// - Parameter data: string to trim + /// /// - Returns: copy of the string with removed trailing whitespace. public static func trim( data: std.string @@ -220,8 +240,8 @@ public enum Utils{ } /// Removes all whitespace from the left of given string. - /// - Parameter data: inout string to trim - /// - Returns: copy of the string with removed leading whitespace. + /// + /// - Parameter data: reference to string public static func ltrim( data: inout std.string ) throws -> Void { @@ -232,8 +252,8 @@ public enum Utils{ } /// Removes all whitespace from the right of given string. - /// - Parameter data: inout string to trim - /// - Returns: copy of the string with removed trailing whitespace. + /// + /// - Parameter data: reference to string public static func rtrim( data: inout std.string ) throws -> Void { @@ -247,6 +267,7 @@ public enum Utils{ /// /// - Parameter data: string to split /// - Parameter delimiter: string which will be split + /// /// - Returns: vector containing all split parts public static func split( data: std.string, diff --git a/Sources/PrivMXEndpointSwift/Crypto/BIP39.swift b/Sources/PrivMXEndpointSwift/Crypto/BIP39.swift index ba82595..0bbd28c 100644 --- a/Sources/PrivMXEndpointSwift/Crypto/BIP39.swift +++ b/Sources/PrivMXEndpointSwift/Crypto/BIP39.swift @@ -13,7 +13,7 @@ import PrivMXEndpointSwiftNative /// Struct containing ECC generated key using BIP-39. /// -/// This struct is used for safe handling of potentially throwing methods of ExtKey +/// This struct is used for safe handling of potentially throwing methods of ExtKey. public struct BIP39{ internal var wrapped: privmx.endpoint.crypto.BIP39_t diff --git a/Sources/PrivMXEndpointSwift/Crypto/CryptoApi.swift b/Sources/PrivMXEndpointSwift/Crypto/CryptoApi.swift index 5f0876e..75c9022 100644 --- a/Sources/PrivMXEndpointSwift/Crypto/CryptoApi.swift +++ b/Sources/PrivMXEndpointSwift/Crypto/CryptoApi.swift @@ -14,17 +14,17 @@ import Cxx import CxxStdlib import PrivMXEndpointSwiftNative -/// Swift wrapper for `privmx.NativeCryptoApiWrapper`. +/// 'CryptoApi' is a class representing Endpoint's API for cryptographic operations. /// -/// This class provides cryptographic functions such as key generation, encryption, and decryption, as well as signing data. It wraps the underlying C++ implementation for use in Swift. +/// This class wraps the underlying C++ implementation for use in Swift. public class CryptoApi{ /// An instance of the wrapped C++ class. private var api: privmx.NativeCryptoApiWrapper - /// Creates a new `CryptoApi` instance. + /// Creates instance of 'CryptoApi'. /// - /// - Returns: A new `CryptoApi` instance. + /// - Returns: CryptoApi object public static func create( ) -> CryptoApi { CryptoApi(api: privmx.NativeCryptoApiWrapper.create()) @@ -36,18 +36,14 @@ public class CryptoApi{ self.api = api } - /// Signs the given data using the specified private key. + /// Creates a signature of data using given key. /// - /// This method takes raw binary data and a WIF (Wallet Import Format) private key to generate a cryptographic signature. The resulting signature can be used to verify the authenticity and integrity of the signed data. + /// - Parameter data: buffer to sign + /// - Parameter privateKey: key used to sign data /// - /// - Parameters: - /// - data: The binary data to be signed, typically a message or a file. - /// - privateKey: The WIF private key used to sign the data. + /// - Returns: signature of data /// - /// - Returns: The cryptographic signature as a binary buffer (`privmx.endpoint.core.Buffer`). - /// - /// - Throws: - /// - `PrivMXEndpointError.failedSigning` if the signing process fails due to an invalid key or data error. + /// - Throws: `PrivMXEndpointError.failedSigning` if the signing process fails due to an invalid key or data error. public func signData( data: privmx.endpoint.core.Buffer, privateKey: std.string @@ -68,10 +64,11 @@ public class CryptoApi{ /// Validate a signature of data using given key. /// - /// - Parameter data: buffer containing the data signature of which is being verified. - /// - Parameter signature: signature to be verified. - /// - Parameter publicKey: public ECC key in BASE58DER format used to validate data. - /// - Returns: data validation result. + /// - Parameter data: buffer + /// - Parameter signature: signature of data to verify + /// - Parameter publicKey: public ECC key in BASE58DER format used to validate data + /// + /// - Returns: data validation result /// /// - Throws: `PrivMXEndpointError.failedVerifyingSignature` if an verification process fails. public func verifySignature( @@ -94,17 +91,11 @@ public class CryptoApi{ return result } - /// Generates a new symmetric key (AES-256) for encryption and decryption. - /// - /// Symmetric encryption uses the same key for both encryption and decryption, and AES-256 is a widely adopted standard for secure encryption. This method generates a 256-bit key which can be used for encrypting sensitive data. - /// - /// **Use case:** This is typically used when you need to secure data in transit or at rest. The same key will be required to decrypt the data that was encrypted with it. + /// Generates a new symmetric key. /// - /// - Returns: A 256-bit symmetric key as a binary buffer (`privmx.endpoint.core.Buffer`). - /// - /// - Throws: - /// - `PrivMXEndpointError.failedGeneratingSymmetricKey` if there is an issue generating the key, for instance due to insufficient entropy or a system-level error. + /// - Returns: generated key /// + /// - Throws: `PrivMXEndpointError.failedGeneratingSymmetricKey` if there is an issue generating the key, for instance due to insufficient entropy or a system-level error. public func generateKeySymmetric( ) throws -> privmx.endpoint.core.Buffer { let res = api.generateKeySymmetric() @@ -120,20 +111,13 @@ public class CryptoApi{ return result } - /// Generates a new private key in WIF (Wallet Import Format). - /// - /// The private key can be used for various cryptographic operations such as signing data, generating public keys, and encrypting sensitive information. You can optionally provide a seed to generate a deterministic key, or omit the seed to generate a random key. Here it can be used for identifying and authorizing User (after previous adding its Public Key to PrivMX Bridge) - /// - /// **Use case:** Private keys are used in both asymmetric encryption and signing operations. This method is useful when you need a fresh key pair for a new user or system process. + /// Generates a new private ECC key. /// - /// - Parameter randomSeed: An optional seed to generate a deterministic private key. If `nil` is provided, a random key will be generated. + /// - Parameter randomSeed: optional string used as the base to generate the new key /// - /// - Returns: The generated private key in WIF format. + /// - Returns: generated ECC key in WIF format /// - /// - Throws: - /// - `PrivMXEndpointError.failedGeneratingPrivKey` if the key generation fails, potentially due to a system error or invalid seed. - /// - /// **Security Note:** Private keys should be stored securely, ideally in an encrypted keystore or hardware security module (HSM). + /// - Throws: `PrivMXEndpointError.failedGeneratingPrivKey` if the key generation fails, potentially due to a system error or invalid seed. public func generatePrivateKey( randomSeed: std.string? ) throws -> std.string { @@ -155,22 +139,14 @@ public class CryptoApi{ return result } - /// Derives a private key from a given password and salt using a key derivation function. - /// - /// This method generates a private key based on a user-provided password and salt. The combination of the two ensures that the key is unique for each user and is always generated deterministically, and the salt prevents dictionary attacks. - /// - /// **Use case:** Useful in scenarios where users are authenticated via passwords, but cryptographic operations require a private key. By deriving the key from a password, you avoid directly storing or transferring the private key. + /// Generates a new private ECC key from a password using pbkdf2. /// - /// - Parameters: - /// - password: The base string (usually a user password) used for deriving the key. - /// - salt: The salt value that makes the derived key unique, even if the same password is used by multiple users. + /// - Parameter password: the password used to generate the new key + /// - Parameter salt: random string (additional input for the hashing function) /// - /// - Returns: The derived private key in WIF format. + /// - Returns: generated ECC key in WIF format /// - /// - Throws: - /// - `PrivMXEndpointError.failedGeneratingPrivKey` if the key derivation fails, such as when using invalid input or a weak password. - /// - /// **Security Note:** Passwords should never be stored or transmitted in plain text. Ensure that the salt is unique and sufficiently random to prevent predictable key generation. + /// - Throws: `PrivMXEndpointError.failedGeneratingPrivKey` if the key derivation fails, such as when using invalid input or a weak password. @available(*,deprecated,renamed: "derivePrivateKey2(password:salt:)") public func derivePrivateKey( password: std.string, @@ -189,22 +165,17 @@ public class CryptoApi{ } return result } - /// Derives a private key from a given password and salt using a key derivation function. - /// - /// This method generates a private key based on a user-provided password and salt. The combination of the two ensures that the key is unique for each user and is always generated deterministically, and the salt prevents dictionary attacks. - /// - /// **Use case:** Useful in scenarios where users are authenticated via passwords, but cryptographic operations require a private key. By deriving the key from a password, you avoid directly storing or transferring the private key. + + /// Generates a new private ECC key from a password using pbkdf2. /// - /// - Parameters: - /// - password: The base string (usually a user password) used for deriving the key. - /// - salt: The salt value that makes the derived key unique, even if the same password is used by multiple users. + /// This version of the derive function has a rounds count increased to 200k. This makes using this function a safer choice, but it makes the received key different than in the original version. /// - /// - Returns: The derived private key in WIF format. + /// - Parameter password: the password used to generate the new key + /// - Parameter salt: random string (additional input for the hashing function) /// - /// - Throws: - /// - `PrivMXEndpointError.failedGeneratingPrivKey` if the key derivation fails, such as when using invalid input or a weak password. + /// - Returns: generated ECC key in WIF format /// - /// **Security Note:** Passwords should never be stored or transmitted in plain text. Ensure that the salt is unique and sufficiently random to prevent predictable key generation. + /// - Throws: `PrivMXEndpointError.failedGeneratingPrivKey` if the key derivation fails, such as when using invalid input or a weak password. public func derivePrivateKey2( password: std.string, salt: std.string @@ -223,18 +194,13 @@ public class CryptoApi{ return result } - /// Derives a public key from the given private key. - /// - /// In public-key cryptography, a public key is derived from a private key and can be shared publicly to allow others to verify signatures or encrypt messages for the private key holder. The private key remains secret. + /// Generates a new public ECC key as a pair for an existing private key. /// - /// **Use case:** This function is used to generate a public key for a user or system after they have generated or provided a private key. Public keys have to be registered in PrivMX Bridge for encryption or verification. This should be done via Bridge REST API. + /// - Parameter privKey: private ECC key in WIF format /// - /// - Parameter privKey: The WIF private key from which the public key will be derived. + /// - Returns: generated ECC key in BASE58DER format /// - /// - Returns: The derived public key in WIF format. - /// - /// - Throws: - /// - `PrivMXEndpointError.failedGeneratingPubKey` if the derivation process fails, such as if the private key is invalid. + /// - Throws: `PrivMXEndpointError.failedGeneratingPubKey` if the derivation process fails, such as if the private key is invalid. public func derivePublicKey( privKey: std.string ) throws -> std.string { @@ -252,21 +218,14 @@ public class CryptoApi{ } - /// Encrypts the given data using AES-256 symmetric encryption. + /// Encrypts buffer with a given key using AES. /// - /// This method encrypts the data using the provided symmetric key. Symmetric encryption is fast and suitable for large data volumes, such as files or communication payloads. + /// - Parameter data: buffer to encrypt + /// - Parameter symmetricKey: key used to encrypt data /// - /// **Use case:** This function is used to securely store or transmit data, ensuring that only those with the correct key can decrypt and access the original content. - /// - /// - Parameters: - /// - data: The data to be encrypted. - /// - symmetricKey: The 256-bit key used for encryption (must be the same key used for decryption). - /// - /// - Returns: The encrypted data as a binary buffer. - /// - /// - Throws: - /// - `PrivMXEndpointError.failedEncrypting` if the encryption process fails, typically due to an invalid key or data format. + /// - Returns: encrypted data buffer /// + /// - Throws: `PrivMXEndpointError.failedEncrypting` if the encryption process fails, typically due to an invalid key or data format. public func encryptDataSymmetric( data: privmx.endpoint.core.Buffer, symmetricKey: privmx.endpoint.core.Buffer @@ -286,17 +245,12 @@ public class CryptoApi{ } - /// Decrypts the given data using AES-256 symmetric encryption. + /// Decrypts buffer with a given key using AES. /// - /// This method decrypts data that was previously encrypted using the same symmetric key. If the correct key is not provided, the decryption will fail, resulting in corrupted or unreadable data. + /// - Parameter data: buffer to decrypt + /// - Parameter symmetricKey: key used to decrypt data /// - /// **Use case:** Decryption is used to retrieve the original content that was securely encrypted, ensuring the data’s confidentiality and integrity. - /// - /// - Parameters: - /// - data: The encrypted data to be decrypted. - /// - symmetricKey: The 256-bit key that was used for encryption (must match the key used during encryption). - /// - /// - Returns: The decrypted data as a binary buffer. + /// - Returns: plain (decrypted) data buffer /// /// - Throws: /// - `PrivMXEndpointError.failedDecrypting` if the decryption process fails, often due to an incorrect key or tampered data. @@ -319,19 +273,13 @@ public class CryptoApi{ } - /// Converts a PEM-formatted key to WIF (Wallet Import Format). - /// - /// This function converts keys that are in the PEM format, commonly used in SSL certificates and other cryptographic contexts, to WIF format, which is more commonly used in wallet and blockchain-based systems. - /// - /// **Use case:** Useful when migrating keys from a PEM-based system to a WIF-compatible system, such as moving from an SSL-based infrastructure to a blockchain-based system. + /// Converts given private key in PEM format to its WIF format. /// - /// - Parameter pemKey: The key in PEM format to be converted. + /// - Parameter pemKey: private key to convert /// - /// - Returns: The converted key in WIF format. - /// - /// - Throws: - /// - `PrivMXEndpointError.failedConvertingKeyToWIF` if the conversion fails due to an invalid key or format. + /// - Returns: private key in WIF format /// + /// - Throws: `PrivMXEndpointError.failedConvertingKeyToWIF` if the conversion fails due to an invalid key or format. public func convertPEMKeyToWIFKey( pemKey: std.string )throws -> std.string{ @@ -403,8 +351,8 @@ public class CryptoApi{ /// Generates ECC key using BIP-39 mnemonic. /// - /// - Parameters mnemonic: the BIP-39 entropy used to generate the Key - /// - Parameters mnemonic: the password used to generate the Key + /// - Parameter mnemonic: the BIP-39 entropy used to generate the Key + /// - Parameter password: the password used to generate the Key /// /// - Throws: `PrivMXEndpointError.failedGeneratingBIP39` if the generating fails. /// @@ -430,8 +378,8 @@ public class CryptoApi{ /// Generates ECC key using BIP-39 entropy. /// - /// - Parameters entropy: the BIP-39 entropy used to generate the Key - /// - Parameters password: the password used to generate the Key + /// - Parameter entropy: the BIP-39 entropy used to generate the Key + /// - Parameter password: the password used to generate the Key /// /// - Throws: `PrivMXEndpointError.failedGeneratingBIP39` if the generating fails. /// diff --git a/Sources/PrivMXEndpointSwift/Crypto/ExtKey.swift b/Sources/PrivMXEndpointSwift/Crypto/ExtKey.swift index 9ef19ac..5c0a37c 100644 --- a/Sources/PrivMXEndpointSwift/Crypto/ExtKey.swift +++ b/Sources/PrivMXEndpointSwift/Crypto/ExtKey.swift @@ -23,7 +23,9 @@ public class ExtKey{ } /// Creates ExtKey from given seed. + /// /// - Parameter seed: the seed used to generate Key + /// /// - Returns: `ExtKey` object public static func fromSeed( seed: privmx.endpoint.core.Buffer @@ -42,7 +44,9 @@ public class ExtKey{ } /// Decodes ExtKey from Base58 format. - /// - Parameter base58:the ExtKey in Base58 + /// + /// - Parameter base58: the ExtKey in Base58 + /// /// - Returns: `ExtKey` object public static func fromBase58( base58: std.string @@ -61,6 +65,7 @@ public class ExtKey{ } /// Generates a new ExtKey. + /// /// - Returns: `ExtKey` object public static func generateRandom( ) throws -> ExtKey { @@ -78,7 +83,9 @@ public class ExtKey{ } /// Generates child ExtKey from a current ExtKey using BIP32. + /// /// - Parameter index: number from 0 to 2^31-1 + /// /// - Returns: `ExtKey` object public func derive( index:UInt32 @@ -97,7 +104,9 @@ public class ExtKey{ } /// Generates hardened child ExtKey from a current ExtKey using BIP32. + /// /// - Parameter index: number from 0 to 2^31-1 + /// /// - Returns: `ExtKey` object public func deriveHardened( index:UInt32 @@ -116,6 +125,7 @@ public class ExtKey{ } /// Converts ExtKey to Base58 string. + /// /// - Returns: `ExtKey` in Base58 format public func getPrivatePartAsBase58( ) throws -> std.string { @@ -133,6 +143,7 @@ public class ExtKey{ } /// Converts the public part of ExtKey to Base58 string. + /// /// - Returns: `ExtKey` in Base58 format public func getPublicPartAsBase58( ) throws -> std.string { @@ -150,6 +161,7 @@ public class ExtKey{ } /// Extracts ECC PrivateKey. + /// /// - Returns: ECC key in WIF format public func getPrivateKey( ) throws -> std.string { @@ -167,6 +179,7 @@ public class ExtKey{ } /// Extracts ECC PublicKey. + /// /// - Returns: ECC key in BASE58DER format public func getPublicKey( ) throws -> std.string { @@ -184,6 +197,7 @@ public class ExtKey{ } /// Extracts ECC PublicKey Address. + /// /// - Returns: ECC Address in BASE58 format public func getPublicKeyAsBase58Address( ) throws -> std.string { @@ -201,6 +215,7 @@ public class ExtKey{ } /// Extracts raw ECC PrivateKey. + /// /// - Returns: ECC PrivateKey public func getPrivateEncKey( ) throws -> privmx.endpoint.core.Buffer { @@ -218,6 +233,7 @@ public class ExtKey{ } /// Gets the chain code of Extended Key. + /// /// - Returns: Raw chain code public func getChainCode( ) throws -> privmx.endpoint.core.Buffer { @@ -235,8 +251,10 @@ public class ExtKey{ } /// Validates a signature of a message. + /// /// - Parameter message: data used on validation /// - Parameter signature: signature of data to verify + /// /// - Returns: message validation result public func verifyCompactSignatureWithHash( message: privmx.endpoint.core.Buffer, @@ -258,6 +276,7 @@ public class ExtKey{ } /// Checks if ExtKey is Private. + /// /// - Returns: returns true if ExtKey is private public func isPrivate( ) throws -> Bool { diff --git a/Sources/PrivMXEndpointSwift/Events/EventApi.swift b/Sources/PrivMXEndpointSwift/Events/EventApi.swift index 920985b..cb211f8 100644 --- a/Sources/PrivMXEndpointSwift/Events/EventApi.swift +++ b/Sources/PrivMXEndpointSwift/Events/EventApi.swift @@ -11,6 +11,7 @@ import PrivMXEndpointSwiftNative +/// 'EventApi' is a class representing Endpoint's API for context custom events. public class EventApi{ internal var api : privmx.NativeEventApiWrapper @@ -20,15 +21,13 @@ public class EventApi{ self.api = api } - /// Creates a new instance of `EventApi` from a `Connection` object. + /// Creates an instance of 'EventApi'. /// - /// This method initializes the `EventApi` instance, enabling CustomEvent-related operations over the specified connection. - /// - /// - Parameter connection: The connection object to be used for interacting with Custom Events. + /// - Parameter connection: instance of 'Connection' /// /// - Throws: `PrivMXEndpointError.failedInstantiatingEventApi` if an error occurs during the initialization. /// - /// - Returns: A newly created `EventApi` instance. + /// - Returns: `EventApi` object public static func create( connection: inout Connection ) throws -> EventApi { @@ -58,7 +57,6 @@ public class EventApi{ /// - Parameter users: event's data /// /// - Throws: `PrivMXEndpointError.failedEmittingCustomEvent` if listing the messages fails. - /// public func emitEvent( contextId: std.string, users: privmx.UserWithPubKeyVector, @@ -76,7 +74,7 @@ public class EventApi{ } - /// Subscribe for the events on the given subscription query. + /// Subscribe for the custom events on the given subscription query. /// /// - Parameter subscriptionQueries: list of queries /// @@ -105,9 +103,9 @@ public class EventApi{ /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } @@ -115,13 +113,11 @@ public class EventApi{ /// Generate subscription Query for the Custom events. /// - /// - Parameter eventType: type of event which you listen for - /// - Parameter selectorType: scope on which you listen for events + /// - Parameter channelName: name of the Channel + /// - Parameter selectorType: selector of scope on which you listen for events /// - Parameter selectorId: ID of the selector /// /// - Throws: When building the subscription Query fails. - /// - /// - Returns: a properly formatted event subscription request. public func buildSubscriptionQuery( channelName: std.string, selectorType: privmx.endpoint.event.EventSelectorType, diff --git a/Sources/PrivMXEndpointSwift/Events/EventHandler.swift b/Sources/PrivMXEndpointSwift/Events/EventHandler.swift index a19b47a..fb630be 100644 --- a/Sources/PrivMXEndpointSwift/Events/EventHandler.swift +++ b/Sources/PrivMXEndpointSwift/Events/EventHandler.swift @@ -17,12 +17,12 @@ import PrivMXEndpointSwiftNative /// and extract the events if present. It acts as a Swift wrapper for PrivMX Core Event handling mechanisms. public enum EventHandler{ - /// Checks if the `EventHolder` contains a `LibConnectedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'LibConnectedEvent' /// - /// This method queries the provided `EventHolder` to determine if it contains an event that corresponds to a `LibConnectedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'LibConnectedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the `EventHolder` contains a `LibConnectedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in the underlying C++ code or another issue arises. public static func isLibConnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -40,12 +40,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `LibDisconnectedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'LibDisconnectedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` to determine if it contains an event that corresponds to a `LibDisconnectedEvent`. + /// - Returns: true for 'LibDisconnectedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the `EventHolder` contains a `LibDisconnectedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in the underlying C++ code or another issue arises. public static func isLibDisconnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -65,10 +65,10 @@ public enum EventHandler{ /// Checks if the `EventHolder` contains a `LibPlatformDisconnectedEvent`. /// - /// This method queries the provided `EventHolder` to determine if it contains an event that corresponds to a `LibPlatformDisconnectedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'LibPlatformDisconnectedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the `EventHolder` contains a `LibPlatformDisconnectedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in the underlying C++ code or another issue arises. public static func isLibPlatformDisconnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -86,12 +86,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `CollectionChangedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'CollectionChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` to determine if it contains an event that corresponds to a `CollectionChangedEvent`. + /// - Returns: true for 'CollectionChangedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the `EventHolder` contains a `CollectionChangedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in the underlying C++ code or another issue arises. public static func isCollectionChangedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -109,10 +109,12 @@ public enum EventHandler{ return result } - /// Extracts a `LibConnectedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'LibConnectedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'LibConnectedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `LibConnectedEvent`. - /// - Returns: The extracted `LibConnectedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. public static func extractLibConnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -130,10 +132,12 @@ public enum EventHandler{ return result } - /// Extracts a `LibDisconnectedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'LibDisconnectedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'LibDisconnectedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `LibDisconnectedEvent`. - /// - Returns: The extracted `LibDisconnectedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. public static func extractLibDisconnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -151,10 +155,12 @@ public enum EventHandler{ return result } - /// Extracts a `LibPlatformDisconnectedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'LibPlatformDisconnectedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'LibPlatformDisconnectedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `LibPlatformDisconnectedEvent`. - /// - Returns: The extracted `LibPlatformDisconnectedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. public static func extractLibPlatformDisconnectedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -172,12 +178,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `LibBreakEvent`. + /// Checks whether event held in the 'EventHolder' is an 'LibBreakEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` to determine if it contains a `LibBreakEvent`. + /// - Returns: true for 'LibBreakEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the `EventHolder` contains a `LibBreakEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs in the underlying C++ code or another issue arises. public static func isLibBreakEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -195,10 +201,12 @@ public enum EventHandler{ return result } - /// Extracts a `LibBreakEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'LibBreakEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'LibBreakEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `LibBreakEvent`. - /// - Returns: The extracted `LibBreakEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. public static func extractLibBreakEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -216,10 +224,150 @@ public enum EventHandler{ return result } - /// Extracts a `CollectionChangedEvent` from the provided `EventHolder`. + /// Checks whether event held in the 'EventHolder' is an 'ContextUsersStatusChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ContextUsersStatusChangedEvent', else otherwise + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs in the underlying C++ code or another issue arises. + public static func isContextUsersStatusChangedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> Bool{ + let res = privmx.CoreEventHandlerWrapper.isContextUsersStatusChangedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Gets Event held in the 'EventHolder' as an 'ContextUsersStatusChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ContextUsersStatusChangedEvent' object + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. + public static func extractContextUsersStatusChangedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> privmx.endpoint.core.ContextUsersStatusChangedEvent{ + let res = privmx.CoreEventHandlerWrapper.extractContextUsersStatusChangedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Checks whether event held in the 'EventHolder' is an 'ContextUserAddedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ContextUserAddedEvent', else otherwise + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs in the underlying C++ code or another issue arises. + public static func isContextUserAddedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> Bool{ + let res = privmx.CoreEventHandlerWrapper.isContextUserAddedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Gets Event held in the 'EventHolder' as an 'ContextUserAddedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ContextUserAddedEvent' object + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. + public static func extractContextUserAddedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> privmx.endpoint.core.ContextUserAddedEvent{ + let res = privmx.CoreEventHandlerWrapper.extractContextUserAddedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Checks whether event held in the 'EventHolder' is an 'ContextUserRemovedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ContextUserRemovedEvent', else otherwise + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs in the underlying C++ code or another issue arises. + public static func isContextUserRemovedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> Bool{ + let res = privmx.CoreEventHandlerWrapper.isContextUserRemovedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Gets Event held in the 'EventHolder' as an 'ContextUserRemovedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ContextUserRemovedEvent' object + /// + /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. + public static func extractContextUserRemovedEvent( + eventHolder: privmx.endpoint.core.EventHolder + ) throws -> privmx.endpoint.core.ContextUserRemovedEvent{ + let res = privmx.CoreEventHandlerWrapper.extractContextUserRemovedEvent(eventHolder) + guard res.error.value == nil else { + throw PrivMXEndpointError.failedExtractingEventFromHolder(res.error.value!) + } + guard let result = res.result.value else { + var err = privmx.InternalError() + err.name = "Value error" + err.description = "Unexpectedly received nil result" + throw PrivMXEndpointError.failedExtractingEventFromHolder(err) + } + return result + } + + /// Gets Event held in the 'EventHolder' as an 'CollectionChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'CollectionChangedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `CollectionChangedEvent`. - /// - Returns: The extracted `CollectionChangedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if an error occurs while extracting the event. public static func extractCollectionChangedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -237,13 +385,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreCreatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreCreatedEvent' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreCreatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'StoreCreatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreCreatedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -261,14 +408,13 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreUpdatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreUpdatedEvent' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreUpdatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreUpdatedEvent`; otherwise, `false`. - /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. + /// + /// - Throws: true for 'StoreUpdatedEvent', else otherwise public static func isStoreUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -285,13 +431,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreDeletedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreDeletedEvent`. + /// - Returns:true for 'StoreDeletedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreDeletedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -309,13 +454,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreStatsChangedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreStatsChangedEvent' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreStatsChangedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'StoreStatsChangedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreStatsChangedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreStatsChangedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -333,13 +477,13 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreFileCreatedEvent`. + + /// Checks whether event held in the 'EventHolder' is an 'StoreFileCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreFileCreatedEvent`. + /// - Returns: true for 'StoreFileCreatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreFileCreatedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreFileCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -357,13 +501,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreFileUpdatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreFileUpdatedEvent' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreFileUpdatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'StoreFileUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreFileUpdatedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreFileUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -381,13 +524,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `StoreFileDeletedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'StoreFileDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method queries the provided `EventHolder` instance to determine if it holds an event - /// that corresponds to a `StoreFileDeletedEvent`. + /// - Returns: true for 'StoreFileDeletedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance to be queried. - /// - Returns: `true` if the event contained within the `EventHolder` is a `StoreFileDeletedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs in querying the event. public static func isStoreFileDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -405,10 +547,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreCreatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreCreatedEvent`. - /// - Returns: The extracted `StoreCreatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -426,10 +570,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreCreatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreCreatedEvent`. - /// - Returns: The extracted `StoreCreatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -447,10 +593,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreDeletedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreDeletedEvent`. - /// - Returns: The extracted `StoreDeletedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -468,10 +616,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreStatsChangedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreStatsChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreStatsChangedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreStatsChangedEvent`. - /// - Returns: The extracted `StoreStatsChangedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreStatsChangedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -489,10 +639,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreFileCreatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreFileCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreFileCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreFileCreatedEvent`. - /// - Returns: The extracted `StoreFileCreatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreFileCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -510,10 +662,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreFileUpdatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreFileUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreFileUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreFileUpdatedEvent`. - /// - Returns: The extracted `StoreFileUpdatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreFileUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -531,10 +685,12 @@ public enum EventHandler{ return result } - /// Extracts a `StoreFileDeletedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'StoreFileDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'StoreFileDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` containing a `StoreFileDeletedEvent`. - /// - Returns: The extracted `StoreFileDeletedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractStoreFileDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -553,13 +709,12 @@ public enum EventHandler{ } - /// Checks if the `EventHolder` contains a `ThreadCreatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadCreatedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadCreatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadCreatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadCreatedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -577,13 +732,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadUpdatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadUpdatedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadUpdatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadUpdatedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -601,13 +755,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadDeletedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadDeletedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadDeletedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadDeletedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadDeletedEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -625,13 +778,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadStatsEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadStatsChangedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadStatsEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadStatsChangedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadStatsEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadStatsEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -649,13 +801,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadNewMessageEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadNewMessageEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadNewMessageEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadNewMessageEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadNewMessageEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadNewMessageEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -698,13 +849,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadMessageEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadMessageDeletedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadDeletedMessageEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadMessageDeletedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadDeletedMessageEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadMessageDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -722,13 +872,12 @@ public enum EventHandler{ return result } - /// Checks if the `EventHolder` contains a `ThreadDeletedMessageEvent`. + /// Checks whether event held in the 'EventHolder' is an 'ThreadMessageUpdatedEvent' /// - /// This method verifies whether the provided `EventHolder` instance contains an event - /// that corresponds to a `privmx.endpoint.thread.ThreadDeletedMessageEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'ThreadMessageUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: The `EventHolder` instance containing an event to check. - /// - Returns: `true` if the `EventHolder` contains a `ThreadDeletedMessageEvent`; otherwise, `false`. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if an error occurs during querying. public static func isThreadMessageUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -747,10 +896,12 @@ public enum EventHandler{ } - /// Extracts a `ThreadCreatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadCreatedEvent`. - /// - Returns: The extracted `ThreadCreatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -768,10 +919,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadUpdatedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadUpdatedEvent`. - /// - Returns: The extracted `ThreadUpdatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -789,10 +942,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadDeletedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadDeletedEvent`. - /// - Returns: The extracted `ThreadDeletedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -810,10 +965,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadStatsEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadStatsChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadStatsChangedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadStatsEvent`. - /// - Returns: The extracted `ThreadStatsEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadStatsEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -831,10 +988,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadNewMessageEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadNewMessageEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadNewMessageEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadNewMessageEvent`. - /// - Returns: The extracted `ThreadNewMessageEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadNewMessageEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -875,10 +1034,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadMessageDeletedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadMessageDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadMessageDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadMessageDeletedEvent`. - /// - Returns: The extracted `ThreadMessageDeletedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadMessageDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -896,10 +1057,12 @@ public enum EventHandler{ return result } - /// Extracts a `ThreadMessageDeletedEvent` from the provided `EventHolder`. + /// Gets Event held in the 'EventHolder' as an 'ThreadMessageUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ThreadMessageUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the `ThreadMessageUpdatedEvent`. - /// - Returns: The extracted `ThreadMessageUpdatedEvent`. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. public static func extractThreadMessageUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder @@ -917,14 +1080,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder indicates an inbox creation. + /// Checks whether event held in the 'EventHolder' is an 'InboxCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance represents - /// an inbox creation event. + /// - Returns: true for 'InboxCreatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is an inbox creation event (`true`) or not (`false`). public static func isInboxCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -941,13 +1103,13 @@ public enum EventHandler{ return result } - /// Extracts the inbox creation event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'InboxCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `InboxCreatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'InboxCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `InboxCreatedEvent` containing the details of the created inbox event. public static func extractInboxCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.inbox.InboxCreatedEvent { @@ -964,14 +1126,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder indicates an inbox update. + /// Checks whether event held in the 'EventHolder' is an 'InboxUpdatedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance represents - /// an inbox update event. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'InboxUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is an inbox update event (`true`) or not (`false`). public static func isInboxUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -988,13 +1149,13 @@ public enum EventHandler{ return result } - /// Extracts the inbox update event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'InboxUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `InboxUpdatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'InboxUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `InboxUpdatedEvent` containing the details of the updated inbox event. public static func extractInboxUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.inbox.InboxUpdatedEvent { @@ -1011,14 +1172,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder indicates an inbox deletion. + /// Checks whether event held in the 'EventHolder' is an 'InboxDeletedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance represents - /// an inbox deletion event. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'InboxDeletedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is an inbox deletion event (`true`) or not (`false`). public static func isInboxDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1035,13 +1195,13 @@ public enum EventHandler{ return result } - /// Extracts the inbox deletion event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'InboxDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `InboxDeletedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'InboxDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `InboxDeletedEvent` containing the details of the deleted inbox event. public static func extractInboxDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.inbox.InboxDeletedEvent { @@ -1058,14 +1218,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder indicates the creation of an inbox entry. + /// Checks whether event held in the 'EventHolder' is an 'InboxEntryCreatedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance represents - /// an inbox entry creation event. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'InboxEntryCreatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is an inbox entry creation event (`true`) or not (`false`). public static func isInboxEntryCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1082,13 +1241,13 @@ public enum EventHandler{ return result } - /// Extracts the inbox entry creation event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'InboxEntryCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `InboxEntryCreatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'InboxEntryCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `InboxEntryCreatedEvent` containing the details of the created inbox entry event. public static func extractInboxEntryCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.inbox.InboxEntryCreatedEvent { @@ -1105,14 +1264,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder indicates the deletion of an inbox entry. + /// Checks whether event held in the 'EventHolder' is an 'InboxEntryDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance represents - /// an inbox entry deletion event. + /// - Returns: true for 'InboxEntryDeletedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is an inbox entry deletion event (`true`) or not (`false`). public static func isInboxEntryDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1129,13 +1287,13 @@ public enum EventHandler{ return result } - /// Extracts the inbox entry deletion event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'InboxEntryDeletedEvent' /// - /// This method retrieves an `InboxEntryDeletedEvent` object from the event contained in the given `EventHolder`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'InboxEntryDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `InboxEntryDeletedEvent` containing the details of the deleted inbox entry event. public static func extractInboxEntryDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.inbox.InboxEntryDeletedEvent { @@ -1152,13 +1310,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a Custom Event. + /// Checks whether event held in the 'EventHolder' is an 'ContextCustomEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance is a Custom Event. + /// - Returns: true for 'ContextCustomEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a Custom Event (`true`) or not (`false`). public static func isContextCustomEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1175,13 +1333,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. - /// - /// This method retrieves a `ContextCustomEvent` object from the event contained in the given `EventHolder`. - /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. + /// Gets Event held in the 'EventHolder' as an 'ContextCustomEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'ContextCustomEvent' object + /// /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: An `ContextCustomEvent` that was emitted by one of the users of the Context. public static func extractContextCustomEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.event.ContextCustomEvent { @@ -1198,13 +1356,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a `KvdbCreatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbCreatedEvent`. + /// - Returns: true for 'KvdbCreatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbCreatedEvent` (`true`) or not (`false`). public static func isKvdbCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1221,13 +1379,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbCreatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `KvdbCreatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'KvdbCreatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbCreatedEvent` instance. public static func extractKvdbCreatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbCreatedEvent { @@ -1244,13 +1402,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a `KvdbUpdatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbUpdatedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbUpdatedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'KvdbUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbUpdatedEvent` (`true`) or not (`false`). public static func isKvdbUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1267,13 +1425,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `KvdbUpdatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'KvdbUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbUpdatedEvent` instance. public static func extractKvdbUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbUpdatedEvent { @@ -1290,13 +1448,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a `KvdbStatsChangedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbStatsChangedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbStatsChangedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'KvdbStatsChangedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbStatsChangedEvent` (`true`) or not (`false`). public static func isKvdbStatsChangedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1313,13 +1471,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbStatsChangedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `KvdbStatsChangedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'KvdbStatsChangedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbStatsChangedEvent` instance. public static func extractKvdbStatsChangedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbStatsChangedEvent { @@ -1336,13 +1494,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a `KvdbDeletedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbDeletedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbDeletedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'KvdbDeletedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbDeletedEvent` (`true`) or not (`false`). public static func isKvdbDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1359,13 +1517,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `KvdbDeletedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'KvdbDeletedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbDeletedEvent` instance. public static func extractKvdbDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbDeletedEvent { @@ -1383,13 +1541,13 @@ public enum EventHandler{ } - /// Determines if the event contained in the event holder is a `KvdbNewEntryEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbNewEntryEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbNewEntryEvent`. + /// - Returns: true for 'KvdbNewEntryEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a Custom Event (`true`) or not (`false`). public static func isKvdbNewEntryEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1406,13 +1564,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbNewEntryEvent' /// - /// This method retrieves an `KvdbNewEntryEvent` object from the event contained in the given `EventHolder`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'KvdbNewEntryEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbNewEntryEvent` instance. public static func extractKvdbNewEntryEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbNewEntryEvent { @@ -1430,13 +1588,13 @@ public enum EventHandler{ } - /// Determines if the event contained in the event holder is a `KvdbEntryUpdatedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbEntryUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbEntryUpdatedEvent`. + /// - Returns: true for 'KvdbEntryUpdatedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbEntryUpdatedEvent` (`true`) or not (`false`). public static func isKvdbEntryUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1453,13 +1611,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. + /// Gets Event held in the 'EventHolder' as an 'KvdbEntryUpdatedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' /// - /// This method retrieves an `KvdbEntryUpdatedEvent` object from the event contained in the given `EventHolder`. + /// - Returns: 'KvdbEntryUpdatedEvent' object /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbEntryUpdatedEvent` instance. public static func extractKvdbEntryUpdatedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbEntryUpdatedEvent { @@ -1476,13 +1634,13 @@ public enum EventHandler{ return result } - /// Determines if the event contained in the event holder is a `KvdbEntryDeletedEvent`. + /// Checks whether event held in the 'EventHolder' is an 'KvdbEntryDeletedEvent' /// - /// This method checks if the event within the provided `EventHolder` instance is a `KvdbEntryDeletedEvent`. + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: true for 'KvdbEntryDeletedEvent', else otherwise /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be checked. /// - Throws: `PrivMXEndpointError.failedQueryingEventHolder` if there is an error during the check. - /// - Returns: A `Bool` indicating whether the event is a `KvdbEntryDEletedEvent` (`true`) or not (`false`). public static func isKvdbEntryDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> Bool { @@ -1499,13 +1657,13 @@ public enum EventHandler{ return result } - /// Extracts the custom event from the provided event holder. - /// - /// This method retrieves an `KvdbEntryDeletedEvent` object from the event contained in the given `EventHolder`. - /// - /// - Parameter eventHolder: An `EventHolder` instance containing the event to be extracted. + /// Gets Event held in the 'EventHolder' as an 'KvdbEntryDeletedEvent' + /// + /// - Parameter eventHolder: holder object that wraps the 'Event' + /// + /// - Returns: 'KvdbEntryDeletedEvent' object + /// /// - Throws: `PrivMXEndpointError.failedExtractingEventFromHolder` if the extraction process fails. - /// - Returns: A `KvdbEntryDeletedEvent` instance. public static func extractKvdbEntryDeletedEvent( eventHolder: privmx.endpoint.core.EventHolder ) throws -> privmx.endpoint.kvdb.KvdbEntryDeletedEvent { diff --git a/Sources/PrivMXEndpointSwift/Events/EventQueue.swift b/Sources/PrivMXEndpointSwift/Events/EventQueue.swift index 3a4998a..d802e0d 100644 --- a/Sources/PrivMXEndpointSwift/Events/EventQueue.swift +++ b/Sources/PrivMXEndpointSwift/Events/EventQueue.swift @@ -25,12 +25,10 @@ public class EventQueue { self.api = api } - /// Retrieves a singleton instance of `EventQueue`. + /// Gets the EventQueue instance. /// - /// This method attempts to access the global instance of `EventQueue`, ensuring only one instance - /// of the event queue wrapper exists. It should be used whenever event queue interaction is needed. + /// - Returns: EventQueue object /// - /// - Returns: The singleton `EventQueue` instance. /// - Throws: `PrivMXEndpointError.failedInstantiatingEventQueue` if an error occurs while instantiating the event queue. public static func getInstance( ) throws -> EventQueue{ @@ -47,10 +45,9 @@ public class EventQueue { return EventQueue(api: result) } - /// Inserts a special break event into the event queue. + /// Puts the break event on the events queue. /// - /// This method emits a special event, `privmx.endpoint.core.libBreakEvent`, into the event queue. - /// This break event can be used to interrupt or signal specific conditions in the event processing flow. + /// You can use it to break the `waitEvent` loop. /// /// - Throws: `PrivMXEndpointError.failedEmittingBreakEvent` if an error occurs during event emission. public func emitBreakEvent( @@ -61,13 +58,10 @@ public class EventQueue { } } - /// Waits for the next event in the queue. + /// Starts a loop waiting for an Event. /// - /// This method will pause and wait until a new event arrives in the queue. If there are - /// any unprocessed events already in the queue, it will return the first unprocessed event. - /// The returned event should be queried using `is*Event` methods and extracted with the appropriate method. + /// - Returns: EventHolder object /// - /// - Returns: An `EventHolder` object containing the next available event. /// - Throws: `PrivMXEndpointError.failedWaitingForEvent` if an error occurs while waiting for the event. public func waitEvent( ) throws -> privmx.endpoint.core.EventHolder{ @@ -84,13 +78,10 @@ public class EventQueue { return result } - /// Attempts to retrieve the next unprocessed event from the queue. - /// - /// This method retrieves the next unprocessed event from the queue without waiting. If there are - /// no unprocessed events, it will simply return `nil`. The returned event, if present, should be - /// queried using `is*Event` methods and extracted with the appropriate method. - /// - /// - Returns: An `EventHolder` containing the next unprocessed event, or `nil` if no unprocessed events are available. + /// Gets the first event from the events queue. + /// + /// - Returns: EventHolder object (optional) + /// /// - Throws: `PrivMXEndpointError.failedGettingEvent` if an error occurs while retrieving the event. public func getEvent( ) throws -> privmx.endpoint.core.EventHolder?{ diff --git a/Sources/PrivMXEndpointSwift/Inboxes/InboxApi.swift b/Sources/PrivMXEndpointSwift/Inboxes/InboxApi.swift index 1397bc8..79585a1 100644 --- a/Sources/PrivMXEndpointSwift/Inboxes/InboxApi.swift +++ b/Sources/PrivMXEndpointSwift/Inboxes/InboxApi.swift @@ -19,16 +19,15 @@ public class InboxApi{ internal var api: privmx.NativeInboxApiWrapper - /// Creates a new instance of `InboxApi` using a connection, `threadApi`, and `StoreApi`. + /// Creates an instance of 'InboxApi'. /// - /// - Parameters: - /// - connection: The connection object to interact with PrivMX. - /// - threadApi: The Thread API instance. - /// - storeApi: The Store API instance. + /// - Parameter connection: instance of 'Connection' + /// - Parameter threadApi: instance of 'ThreadApi' + /// - Parameter storeApi: instance of 'StoreApi' /// /// - Throws: `PrivMXEndpointError.failedInstantiatingInboxApi` if an error occurs during initialization. /// - /// - Returns: A new `InboxApi` instance. + /// - Returns: InboxApi object public static func create( connection:inout Connection, threadApi: inout ThreadApi, @@ -56,22 +55,19 @@ public class InboxApi{ self.api = api } - /// Creates a new Inbox in the specified context. + /// Creates a new Inbox. /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - contextId: The ID of the context where the Inbox should be created. - /// - users: A vector of users who will have access to the Inbox. - /// - managers: A vector of users who will manage the Inbox. - /// - publicMeta: Public metadata that is not encrypted. - /// - privateMeta: Private metadata that is encrypted. - /// - filesConfig: An optional configuration for file storage. - /// - policies: A set of policies for the Container. + /// - Parameter contextId: ID of the Context of the new Inbox + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access to the created Inbox + /// - Parameter managers: vector of UserWithPubKey structs which indicates who will have access (and management rights) to + /// - Parameter publicMeta: public (unencrypted) metadata + /// - Parameter privateMeta: private (encrypted) metadata + /// - Parameter filesConfig: struct to override default file configuration + /// - Parameter policies: Inbox policies /// /// - Throws: `PrivMXEndpointError.failedCreatingInbox` if Inbox creation fails. /// - /// - Returns: The ID of the newly created Inbox as a `std.string`. + /// - Returns: ID of the created Inbox public func createInbox( contextId: std.string, users: privmx.UserWithPubKeyVector, @@ -113,21 +109,19 @@ public class InboxApi{ return result } - /// Updates an existing Inbox with new metadata and configuration. - /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - inboxId: The ID of the Inbox to be updated. - /// - users: A vector of users who will have access to the Inbox. - /// - managers: A vector of users who will manage the Inbox. - /// - publicMeta: Updated public metadata for the Inbox. - /// - privateMeta: Updated private metadata for the Inbox. - /// - filesConfig: An optional configuration for file storage. - /// - version: The current version of the Inbox for version control. - /// - force: Whether to force the update, ignoring version control. - /// - forceGenerateNewKey: Whether to force regeneration of a new key for the Inbox. - /// - policies: New set of policies for the Container. + /// Updates an existing Inbox. + /// + /// - Parameter inboxId: ID of the Inbox to update + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access to the created Inbox + /// - Parameter managers: vector of UserWithPubKey structs which indicates who will have access (and management rights) to + /// the created Inbox + /// - Parameter publicMeta: public (unencrypted) metadata + /// - Parameter privateMeta: private (encrypted) metadata + /// - Parameter filesConfig: struct to override default files configuration + /// - Parameter version: current version of the updated Inbox + /// - Parameter force: force update (without checking version) + /// - Parameter forceGenerateNewKey: force to regenerate a key for the Inbox + /// - Parameter policies: Inbox policies /// /// - Throws: `PrivMXEndpointError.failedUpdatingInbox` if the update process fails. public func updateInbox( @@ -170,13 +164,13 @@ public class InboxApi{ } } - /// Retrieves detailed information about a specific Inbox. + /// Gets a single Inbox by given Inbox ID. /// - /// - Parameter inboxId: The ID of the Inbox to retrieve. + /// - Parameter inboxId: ID of the Inbox to get /// /// - Throws: `PrivMXEndpointError.failedGettingInbox` if fetching Inbox details fails. /// - /// - Returns: An `Inbox` instance containing Inbox details. + /// - Returns: struct containing information about the Inbox public func getInbox( inboxId: std.string ) throws -> privmx.endpoint.inbox.Inbox{ @@ -194,15 +188,14 @@ public class InboxApi{ return result } - /// Lists all Inboxes within a specified context. + /// Gets s list of Inboxes in given Context. /// - /// - Parameters: - /// - contextId: The ID of the context from which to list Inboxes. - /// - pagingQuery: A query object to filter and paginate the results. + /// - Parameter contextId: ID of the Context to get Inboxes from + /// - Parameter pagingQuery: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingInboxes` if listing Inboxes fails. /// - /// - Returns: An `InboxList` containing the list of Inboxes. + /// - Returns: struct containing list of Inboxes public func listInboxes( contextId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -223,13 +216,14 @@ public class InboxApi{ return result } - /// Retrieves the public view of a specific Inbox. + /// Gets public data of given Inbox. + /// You do not have to be logged in to call this function. /// - /// - Parameter inboxId: The ID of the Inbox to retrieve the public view for. + /// - Parameter inboxId: ID of the Inbox to get /// /// - Throws: `PrivMXEndpointError.failedGettingInboxPublicView` if fetching the public view fails. /// - /// - Returns: An `InboxPublicView` containing the public view of the Inbox. + /// - Returns: struct containing public accessible information about the Inbox public func getInboxPublicView( inboxId: std.string ) throws -> privmx.endpoint.inbox.InboxPublicView { @@ -247,9 +241,9 @@ public class InboxApi{ return result } - /// Deletes a specified Inbox. + /// Deletes an Inbox by given Inbox ID. /// - /// - Parameter inboxId: The ID of the Inbox to delete. + /// - Parameter inboxId: ID of the Inbox to delete /// /// - Throws: `PrivMXEndpointError.failedDeletingInbox` if deleting the Inbox fails. public func deleteInbox( @@ -263,19 +257,18 @@ public class InboxApi{ } } - /// Prepares a new entry to be sent to the Inbox. - /// - /// If the entry contains files, they must first be prepared using `createFileHandle()` and attached to the entry. + /// Prepares a request to send data to an Inbox. + /// You do not have to be logged in to call this function. /// - /// - Parameters: - /// - inboxId: The ID of the Inbox to which the entry will be sent. - /// - data: The data to be included in the entry. - /// - inboxFileHandles: An optional vector of file handles to be attached to the entry. By default, no files are attached. - /// - userPrivKey: An optional private key of the user preparing the entry, if required. + /// - Parameter inboxId: ID of the Inbox to which the request applies + /// - Parameter data: entry data to send + /// - Parameter inboxFileHandles: optional list of file handles that will be sent with the request + /// - Parameter userPrivKey: sender can optionally provide a private key, which will be used: 1) to sign the sent data, 2) to derivation of the public key, + /// which will then be transferred along with the sent data and can be used in the future for further secure communication with the sender /// /// - Throws: `PrivMXEndpointError.failedPreparingEntry` if preparing the entry fails. /// - /// - Returns: An `EntryHandle` representing the prepared entry, which should then be sent. + /// - Returns: handle public func prepareEntry( inboxId: std.string, data: privmx.endpoint.core.Buffer, @@ -304,11 +297,10 @@ public class InboxApi{ return result } - /// Sends a previously prepared entry to the Inbox. + /// Sends data to an Inbox. + /// You do not have to be logged in to call this function. /// - /// This method finalizes the process of sending an entry and handles closing of uploaded files. - /// - /// - Parameter entryHandle: The handle of the prepared entry to be sent. + /// - Parameter entryHandle: ID of the Inbox to which the request applies /// /// - Throws: `PrivMXEndpointError.failedSendingEntry` if sending the entry fails. public func sendEntry( @@ -334,13 +326,13 @@ public class InboxApi{ } } - /// Retrieves an entry from a specific Inbox. + /// Gets an entry from an Inbox. /// - /// - Parameter inboxEntryId: The ID of the entry to be retrieved. + /// - Parameter inboxEntryId: ID of an entry to read from the Inbox /// /// - Throws: `PrivMXEndpointError.failedReadingEntry` if retrieving the entry fails. /// - /// - Returns: An `InboxEntry` instance representing the entry. + /// - Returns: struct containing data of the selected entry stored in the Inbox public func readEntry( inboxEntryId: std.string ) throws -> privmx.endpoint.inbox.InboxEntry { @@ -357,15 +349,14 @@ public class InboxApi{ return result } - /// Lists entries within a specific Inbox. + /// Gets list of entries in given Inbox. /// - /// - Parameters: - /// - inboxId: The ID of the Inbox from which to list entries. - /// - pagingQuery: A query object to filter and paginate the results. + /// - Parameter inboxId: ID of the Inbox + /// - Parameter pagingQuery: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingEntries` if listing the entries fails. /// - /// - Returns: An `InboxEntryList` containing the list of entries. + /// - Returns: struct containing list of entries public func listEntries( inboxId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -398,16 +389,16 @@ public class InboxApi{ } } - /// Creates a new file handle for writing data to the Inbox. + /// Creates a file handle to send a file to an Inbox. + /// You do not have to be logged in to call this function. /// - /// - Parameters: - /// - publicMeta: Public metadata for the file. - /// - privateMeta: Private metadata for the file. - /// - fileSize: The size of the file in bytes. + /// - Parameter publicMeta: file's public metadata + /// - Parameter privateMeta: file's private metadata + /// - Parameter fileSize: size of the file to send /// /// - Throws: `PrivMXEndpointError.failedCreatingFileHandle` if creating the file handle fails. /// - /// - Returns: An `InboxFileHandle` for writing data to the file. + /// - Returns: file handle public func createFileHandle( publicMeta:privmx.endpoint.core.Buffer, privateMeta:privmx.endpoint.core.Buffer, @@ -428,12 +419,13 @@ public class InboxApi{ return result } - /// Writes a chunk of data to a file in the Inbox. + /// Sends file's data chunk to an Inbox. + /// (note: To send the entire file - divide it into pieces of the desired size and call the function for each fragment.) + /// You do not have to be logged in to call this function. /// - /// - Parameters: - /// - entryHandle: Handle to the prepared Inbox entry - /// - inboxFileHandle: handle to the file where the uploaded chunk belongs - /// - Buffer: dataChunk - file chunk to send + /// - Parameter entryHandle: Handle to the prepared Inbox entry + /// - Parameter inboxFileHandle: handle to the file where the uploaded chunk belongs + /// - Parameter Buffer: dataChunk - file chunk to send /// /// - Throws: `PrivMXEndpointError.failedWritingToFile` if writing the data chunk fails. public func writeToFile( @@ -449,6 +441,7 @@ public class InboxApi{ } } + @available(*, deprecated, renamed: "writeToFile(entryHandle:inboxFileHandle:dataChunk:)") public func writeToFile( inboxHandle: privmx.EntryHandle, @@ -463,13 +456,13 @@ public class InboxApi{ } } - /// Opens a file for reading from the Inbox. + /// Opens a file to read. /// - /// - Parameter fileId: The ID of the file to open. + /// - Parameter fileId: ID of the file to read /// /// - Throws: `PrivMXEndpointError.failedOpeningFile` if opening the file fails. /// - /// - Returns: An `InboxFileHandle` for reading from the file. + /// - Returns: handle to read file data public func openFile( fileId: std.string ) throws -> privmx.InboxFileHandle { @@ -486,15 +479,15 @@ public class InboxApi{ return result } - /// Reads data from an open file in the inbox. + /// Reads file data. + /// Single read call moves the files's cursor position by declared length or set it at the end of the file. /// - /// - Parameters: - /// - fileHandle: The file handle to read from. - /// - length: The number of bytes to read. + /// - Parameter fileHandle: handle to the file + /// - Parameter length: size of data to read /// /// - Throws: `PrivMXEndpointError.failedReadingFromFile` if reading from the file fails. /// - /// - Returns: A buffer containing the read data. + /// - Returns: buffer with file data chunk public func readFromFile( fileHandle: privmx.InboxFileHandle, length: Int64 @@ -513,11 +506,10 @@ public class InboxApi{ return result } - /// Moves the read cursor in an open file. + /// Moves file's read cursor. /// - /// - Parameters: - /// - fileHandle: The file handle to move the cursor in. - /// - position: The new position of the cursor in bytes. + /// - Parameter fileHandle: handle to the file + /// - Parameter position: sets new cursor position /// /// - Throws: `PrivMXEndpointError.failedSeekingInFile` if moving the cursor fails. public func seekInFile( @@ -531,13 +523,13 @@ public class InboxApi{ } } - /// Closes an open file in the Inbox. + /// Closes a file by given handle. /// - /// - Parameter fileHandle: The file handle to close. + /// - Parameter fileHandle: handle to the file /// /// - Throws: `PrivMXEndpointError.failedClosingFile` if closing the file fails. /// - /// - Returns: The ID of the closed file as a `std.string`. + /// - Returns: ID of closed file public func closeFile( fileHandle: privmx.InboxFileHandle ) throws -> std.string { @@ -560,7 +552,7 @@ public class InboxApi{ /// /// - Throws: When subscribing for events fails. /// - /// - Returns: list of subscriptionIds in maching order to subscriptionQueries. + /// - Returns: list of subscriptionIds in maching order to subscriptionQueries public func subscribeFor( subscriptionQueries: privmx.SubscriptionQueryVector ) throws -> privmx.SubscriptionIdVector { @@ -583,9 +575,9 @@ public class InboxApi{ /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } diff --git a/Sources/PrivMXEndpointSwift/Kvdbs/KvdbApi.swift b/Sources/PrivMXEndpointSwift/Kvdbs/KvdbApi.swift index 526d380..c66678c 100644 --- a/Sources/PrivMXEndpointSwift/Kvdbs/KvdbApi.swift +++ b/Sources/PrivMXEndpointSwift/Kvdbs/KvdbApi.swift @@ -26,7 +26,7 @@ public class KvdbApi: @unchecked Sendable{ /// /// - Parameter connection: instance of 'Connection' /// - /// - Returns: `KvdbApi` object. + /// - Returns: KvdbApi object public static func create( connection: inout Connection ) throws -> KvdbApi { @@ -53,9 +53,8 @@ public class KvdbApi: @unchecked Sendable{ /// - Parameter publicMeta: public (unencrypted) metadata /// - Parameter privateMeta: private (encrypted) metadata /// - Parameter policies: KVDB's policies - /// - Parameter contextId: ID of the Context to create the KVDB in /// - /// - Returns: Id of the created KVDB + /// - Returns: ID of the created KVDB /// /// - Throws: `PrivMXEndpointError.failedCreatingKvdb` if creating a Kvdb fails. public func createKvdb( @@ -102,7 +101,6 @@ public class KvdbApi: @unchecked Sendable{ /// - Parameter force: force update (without checking version) /// - Parameter forceGenerateNewKey: force to regenerate a key for the KVDB /// - Parameter policies: KVDB's policies - /// - Parameter kvdbId: ID of the KVDB to update /// /// - Throws: `PrivMXEndpointError.failedUpdatingKvdb` when the operation fails. public func updateKvdb( @@ -152,7 +150,7 @@ public class KvdbApi: @unchecked Sendable{ } - ///Check whether the KVDB entry exists. + /// Check whether the KVDB entry exists. /// /// - Parameter kvdbId: KVDB ID of the KVDB entry to check /// - Parameter key: key of the KVDB entry to check @@ -175,9 +173,9 @@ public class KvdbApi: @unchecked Sendable{ return result } - ///Gets a KVDB by given KVDB ID. + /// Gets a KVDB by given KVDB ID. /// - /// - Parameter kvdbId:ID of KVDB to get + /// - Parameter kvdbId: ID of KVDB to get /// /// - Returns: struct containing info about the KVDB /// @@ -279,7 +277,7 @@ public class KvdbApi: @unchecked Sendable{ /// Gets a list of KVDB entries from a KVDB. /// /// - Parameter kvdbId: ID of the KVDB to list KVDB entries from - /// - Parameter pagingQuery: with list query parameters + /// - Parameter pagingQuery: with list query parameters /// /// - Returns: struct containing a list of KVDB entries /// @@ -309,6 +307,7 @@ public class KvdbApi: @unchecked Sendable{ /// - Parameter publicMeta: public KVDB entry metadata /// - Parameter privateMeta: private KVDB entry metadata /// - Parameter data: content of the KVDB entry + /// - Parameter version: when 0 indicates creation of new entry, otherwise required to be equal to the version provided by the server /// /// - Returns: ID of the new KVDB entry /// @@ -355,6 +354,8 @@ public class KvdbApi: @unchecked Sendable{ /// - Parameter keys: vector of the keys of the KVDB entries to delete /// /// - Returns: map with the statuses of deletion for every key + /// + /// - Throws: when an error occurs public func deleteEntries( kvdbId: std.string, keys: privmx.StringVector @@ -373,13 +374,13 @@ public class KvdbApi: @unchecked Sendable{ return result } - /// Subscribe for the Kvdb events on the given subscription query. + /// Subscribe for the KVDB events on the given subscription query. /// /// - Parameter subscriptionQueries: list of queries /// /// - Throws: When subscribing for events fails. /// - /// - Returns: list of subscriptionIds in maching order to subscriptionQueries. + /// - Returns: list of subscriptionIds in maching order to subscriptionQueries public func subscribeFor( subscriptionQueries: privmx.SubscriptionQueryVector ) throws -> privmx.SubscriptionIdVector { @@ -402,15 +403,15 @@ public class KvdbApi: @unchecked Sendable{ /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } } - /// Generate subscription Query for the Kvdb events. + /// Generate subscription Query for the KVDB events. /// /// - Parameter eventType: type of event which you listen for /// - Parameter selectorType: scope on which you listen for events @@ -437,11 +438,11 @@ public class KvdbApi: @unchecked Sendable{ return result } - /// Generate subscription Query for the KvdbEntry events. + /// Generate subscription Query for the KVDB events for single KvdbEntry. /// /// - Parameter eventType: type of event which you listen for - /// - Parameter kvdbId: ID of the KVDB - /// - Parameter kvdbEntryKey: key of the KVDB Entry + /// - Parameter kvdbId: Id of Kvdb + /// - Parameter kvdbEntryKey: Key of Kvdb Entry /// /// - Throws: When building the subscription Query fails. /// diff --git a/Sources/PrivMXEndpointSwift/Stores/StoreApi.swift b/Sources/PrivMXEndpointSwift/Stores/StoreApi.swift index 5ae2a84..6e3e7e5 100644 --- a/Sources/PrivMXEndpointSwift/Stores/StoreApi.swift +++ b/Sources/PrivMXEndpointSwift/Stores/StoreApi.swift @@ -14,22 +14,20 @@ import Cxx import CxxStdlib import PrivMXEndpointSwiftNative -/// Swift wrapper for `privmx.NativeStoreApiWrapper`, providing functionality to manage Stores and files within PrivMX platform. +/// 'StoreApi' is a class representing Endpoint's API for Stores and their files. public class StoreApi{ /// An instance of the wrapped C++ class. internal var api: privmx.NativeStoreApiWrapper - /// Creates a new instance of `StoreApi` from a connection object. - /// - /// This method initializes the `StoreApi` instance, enabling Store-related operations over the specified connection. - /// - /// - Parameter connection: The connection object used for Store operations. - /// - /// - Throws: `PrivMXEndpointError.failedInstantiatingStoreApi` if the initialization fails. - /// - /// - Returns: A newly created `StoreApi` instance. - public static func create( + /// Creates an instance of 'StoreApi'Gets a list of Stores in given Context. + /// + /// - Parameter connection: instance of 'ConnectionID of the Context to get the Stores from + /// + /// - Throws: `PrivMXEndpointError.failedInstantiatingStoreApi` if the initialization fails. + /// + /// - Returns: StoreApi struct with list query parameters + public static func create( connection: inout Connection ) throws -> StoreApi { let res = privmx.NativeStoreApiWrapper.create(&connection.api) @@ -52,15 +50,14 @@ public class StoreApi{ self.api = api } - /// Lists all Stores the user has access to within a specified Context. + /// struct containing list of Stores /// - /// - Parameters: - /// - contextId: The Context from which the Stores should be listed. - /// - pagingQuery: A `PagingQuery` object to filter and paginate the results. + /// - Parameter contextId: Gets a list of Stores in given Context. + /// - Parameter pagingQuery: ID of the Context to get the Stores from /// /// - Throws: `PrivMXEndpointError.failedListingStores` if listing Stores fails. /// - /// - Returns: A `privmx.StoreList` instance containing the list of Stores. + /// - Returns: struct with list query parameters public func listStores( contextId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -86,13 +83,13 @@ public class StoreApi{ try listStores(contextId: contextId, pagingQuery: query) } - /// Retrieves detailed information about a specified Store. + /// Gets a single Store by given Store ID. /// - /// - Parameter storeId: The unique identifier of the Store to retrieve. + /// - Parameter storeId: ID of the Store to get /// /// - Throws: `PrivMXEndpointError.failedGettingStore` if fetching the Store details fails. /// - /// - Returns: A `privmx.endpoint.store.Store` instance containing Store details. + /// - Returns: struct containing information about the Store public func getStore( storeId: std.string ) throws -> privmx.endpoint.store.Store{ @@ -110,23 +107,19 @@ public class StoreApi{ return result } - /// Creates a new Store within a specified Context. + /// Creates a new Store in given Context. /// - /// This method creates a new Store with specified users and managers. Note that managers must be added as users to gain access to the Store. - /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - contextId: The Context in which the Store should be created. - /// - users: A vector of users who will have access to the Store. - /// - managers: A vector of managers responsible for the Store. - /// - publicMeta: Public metadata for the Store, which will not be encrypted. - /// - privateMeta: Private metadata for the Store, which will be encrypted. - /// - policies: A set of policies for the Container. + /// - Parameter contextId: ID of the Context to create the Store in + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access to the created Store + /// - Parameter managers: vector of UserWithPubKey structs which indicates who will have access (and management rights) to the + /// created store + /// - Parameter publicMeta: public (unencrypted) metadata + /// - Parameter privateMeta: private (encrypted) metadata + /// - Parameter policies: Store's policies /// /// - Throws: `PrivMXEndpointError.failedCreatingStore` if Store creation fails. /// - /// - Returns: The ID of the newly created Store as a `std.string`. + /// - Returns: created Store ID public func createStore( contextId: std.string, users: privmx.UserWithPubKeyVector, @@ -160,21 +153,16 @@ public class StoreApi{ } /// Updates an existing Store. - /// - /// The provided values will override the existing ones. You can also force regeneration of the Store's key if needed. /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - storeId: The unique identifier of the Store to be updated. - /// - version: The current version of the Store for consistency checking. - /// - users: A vector of users who will have access to the Store. - /// - managers: A vector of managers responsible for the Store. - /// - publicMeta: New public metadata for the Store, which will not be encrypted. - /// - privateMeta: New private metadata for the Store, which will be encrypted. - /// - force: Whether to force the update, bypassing version control. - /// - forceGenerateNewKey: Whether to generate a new key for the Store. - /// - policies: New set of policies for the Container. + /// - Parameter storeId: ID of the Store to update + /// - Parameter version: vector of UserWithPubKey structs which indicates who will have access to the created Store + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access (and management rights) to the + /// - Parameter managers: public (unencrypted) metadata + /// - Parameter publicMeta: private (encrypted) metadata + /// - Parameter privateMeta: current version of the updated Store + /// - Parameter force: force update (without checking version) + /// - Parameter forceGenerateNewKey: force to regenerate a key for the Store + /// - Parameter policies: Store's policies /// /// - Throws: `PrivMXEndpointError.failedUpdatingStore` if updating the Store fails. public func updateStore( @@ -208,9 +196,9 @@ public class StoreApi{ } } - /// Deletes a specified Store. + /// Deletes a Store by given Store ID. /// - /// - Parameter storeId: The unique identifier of the Store to delete. + /// - Parameter storeId: ID of the Store to delete /// /// - Throws: `PrivMXEndpointError.failedDeletingStore` if deleting the Store fails. public func deleteStore( @@ -223,13 +211,13 @@ public class StoreApi{ } } - /// Retrieves detailed information about a specified file. + /// Gets a single file by the given file ID. /// - /// - Parameter fileId: The unique identifier of the file to retrieve. + /// - Parameter fileId: ID of the file to get /// /// - Throws: `PrivMXEndpointError.failedGettingFile` if fetching the file details fails. /// - /// - Returns: A `privmx.endpoint.store.File` instance representing the file details. + /// - Returns: struct containing information about the file public func getFile( fileId: std.string ) throws -> privmx.endpoint.store.File{ @@ -247,17 +235,14 @@ public class StoreApi{ return result } - /// Lists all files in a specified Store. + /// Gets a list of files in given Store. /// - /// This method retrieves metadata about files in the Store. To download files, use the `openFile()` and `readFile()` methods. - /// - /// - Parameters: - /// - storeId: The Store from which to list files. - /// - pagingQuery: A `PagingQuery` object to filter and paginate the results. + /// - Parameter storeId: ID of the Store to get files from + /// - Parameter pagingQuery: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingFiles` if listing the files fails. /// - /// - Returns: A `privmx.FileList` instance containing the list of files. + /// - Returns: struct containing list of files public func listFiles( storeId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -283,19 +268,17 @@ public class StoreApi{ try listFiles(storeId: storeId, pagingQuery: query) } - /// Creates a new file handle for writing in a Store. - /// - /// Use `writeToFile()` to upload data to this handle and `closeFile()` to finalize the process. + /// Creates a new file in a Store. /// - /// - Parameter storeId: The Store in which the file should be created. - /// - Parameter publicMeta: Public metadata for the file. - /// - Parameter privateMeta: Private metadata for the file. - /// - Parameter size: The size of the file in bytes. + /// - Parameter storeId: ID of the Store to create the file in + /// - Parameter publicMeta: public file metadata + /// - Parameter privateMeta: private file metadata + /// - Parameter size: size of the file /// - Parameter randomWriteSupport: enable random write support for file /// /// - Throws: `PrivMXEndpointError.failedCreatingFile` if creating the file handle fails. /// - /// - Returns: A `privmx.StoreFileHandle` for writing to the file. + /// - Returns: handle to write data public func createFile( storeId: std.string, publicMeta:privmx.endpoint.core.Buffer, @@ -316,11 +299,10 @@ public class StoreApi{ return result } - /// Moves the read cursor within an open file. + /// Moves read cursor. /// - /// - Parameters: - /// - handle: The handle to the open file. - /// - position: The new position of the read cursor in bytes. + /// - Parameter handle: handle to write file data + /// - Parameter position: new cursor position /// /// - Throws: `PrivMXEndpointError.failedSeekingInFile` if moving the cursor fails. public func seekInFile( @@ -333,19 +315,16 @@ public class StoreApi{ } } - /// Updates an existing file within a Store. + /// Update an existing file in a Store. /// - /// This method creates a new handle for updating the file's content and metadata. Use `writeToFile()` to upload data and `closeFile()` to finalize the update. - /// - /// - Parameters: - /// - fileId: The unique identifier of the file to be updated. - /// - publicMeta: New public metadata for the file. - /// - privateMeta: New private metadata for the file. - /// - size: The size of the updated file in bytes. + /// - Parameter fileId: ID of the file to update + /// - Parameter publicMeta: public file metadata + /// - Parameter privateMeta: private file metadata + /// - Parameter size: size of the file /// /// - Throws: `PrivMXEndpointError.failedUpdatingFile` if updating the file fails. /// - /// - Returns: A `privmx.StoreFileHandle` for writing to the updated file. + /// - Returns: handle to write file data public func updateFile( fileId: std.string, publicMeta:privmx.endpoint.core.Buffer, @@ -365,11 +344,11 @@ public class StoreApi{ return result } - /// Updates the metadata of an existing File. - /// - Parameters: - /// - fileId: id of a File to be updated - /// - publicMeta: new public metadata - /// - privateMeta: new private metadata + /// Update metadata of an existing file in a Store. + /// + /// - Parameter fileId: ID of the file to update + /// - Parameter publicMeta: public file metadata + /// - Parameter privateMeta: private file metadata /// /// - Throws: When an error occurs during updating metadata. public func updateFileMeta( @@ -383,15 +362,13 @@ public class StoreApi{ } } - /// Closes an open file handle. - /// - /// This method finalizes a file operation, such as writing or updating. + /// Closes the file handle. /// - /// - Parameter handle: The handle to the open file. + /// - Parameter handle: handle to read/write file data /// /// - Throws: `PrivMXEndpointError.failedClosingFile` if closing the file handle fails. /// - /// - Returns: The ID of the closed file as a `std.string`. + /// - Returns: ID of closed file public func closeFile( handle: privmx.StoreFileHandle ) throws -> std.string { @@ -408,13 +385,13 @@ public class StoreApi{ return result } - /// Opens a file for reading from the Store. + /// Opens a file to read. /// - /// - Parameter fileId: The unique identifier of the file to be opened. + /// - Parameter fileId: ID of the file to read /// /// - Throws: `PrivMXEndpointError.failedOpeningFile` if opening the file fails. /// - /// - Returns: A `privmx.StoreFileHandle` for reading the file. + /// - Returns: handle to read file data public func openFile( fileId: std.string ) throws -> privmx.StoreFileHandle { @@ -432,15 +409,15 @@ public class StoreApi{ } - /// Reads data from an open file. + /// Reads file data. + /// Single read call moves the files's cursor position by declared length or set it at the end of the file. /// - /// - Parameters: - /// - handle: The handle to the open file. - /// - length: The number of bytes to read. + /// - Parameter handle: handle to write file data + /// - Parameter length: size of data to read /// /// - Throws: `PrivMXEndpointError.failedReadingFromFile` if reading from the file fails. /// - /// - Returns: A buffer containing the read data. + /// - Returns: buffer with file data chunk public func readFromFile( handle: privmx.StoreFileHandle, length: Int64 @@ -458,10 +435,10 @@ public class StoreApi{ return result } - /// Writes a chunk of data to an open file on the platform. + /// Writes a file data. /// - /// - Parameter handle: The handle to the open file. - /// - Parameter dataChunk: The chunk of data to be written to the file. + /// - Parameter handle: handle to write file data + /// - Parameter dataChunk: file data chunk /// - Parameter truncate: truncate the file from: current pos + dataChunk size /// /// - Throws: `PrivMXEndpointError.failedWritingToFile` if writing to the file fails. @@ -477,9 +454,9 @@ public class StoreApi{ } } - /// Deletes a specified file from the Store. + /// Deletes a file by given ID. /// - /// - Parameter fileId: The unique identifier of the file to delete. + /// - Parameter fileId: ID of the file to delete /// /// - Throws: `PrivMXEndpointError.failedDeletingFile` if deleting the file fails. public func deleteFile( @@ -511,7 +488,7 @@ public class StoreApi{ /// /// - Throws: When subscribing for events fails. /// - /// - Returns: list of subscriptionIds in maching order to subscriptionQueries. + /// - Returns: list of subscriptionIds in maching order to subscriptionQueries public func subscribeFor( subscriptionQueries: privmx.SubscriptionQueryVector ) throws -> privmx.SubscriptionIdVector { @@ -534,9 +511,9 @@ public class StoreApi{ /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } diff --git a/Sources/PrivMXEndpointSwift/Threads/ThreadApi.swift b/Sources/PrivMXEndpointSwift/Threads/ThreadApi.swift index e7fa6c7..521afc5 100644 --- a/Sources/PrivMXEndpointSwift/Threads/ThreadApi.swift +++ b/Sources/PrivMXEndpointSwift/Threads/ThreadApi.swift @@ -14,7 +14,7 @@ import Cxx import CxxStdlib import PrivMXEndpointSwiftNative -/// Swift wrapper for `privmx.NativeThreadApiWrapper`, providing Thread-related operations within PrivMX platform. +/// 'ThreadApi' is a class representing Endpoint's API for Threads and their messages. public class ThreadApi{ /// An instance of the wrapped C++ class. @@ -24,15 +24,13 @@ public class ThreadApi{ self.api = api } - /// Creates a new instance of `ThreadApi` from a `Connection` object. + /// Creates an instance of 'ThreadApi'. /// - /// This method initializes the `ThreadApi` instance, enabling Thread-related operations over the specified connection. - /// - /// - Parameter connection: The connection object to be used for interacting with Threads. + /// - Parameter connection: instance of 'Connection' /// /// - Throws: `PrivMXEndpointError.failedInstantiatingThreadApi` if an error occurs during the initialization. /// - /// - Returns: A newly created `ThreadApi` instance. + /// - Returns: ThreadApi object public static func create( connection: inout Connection ) throws -> ThreadApi{ @@ -49,23 +47,19 @@ public class ThreadApi{ return ThreadApi(api: result) } - /// Creates a new Thread within PrivMX Bridge. - /// - /// This method creates a new Thread in the specified context, assigning users and managers to it. Note that managers must be added explicitly as users to access the Thread. + /// Creates a new Thread in given Context. /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - contextId: The context in which the Thread should be created. - /// - users: A vector of users who will have access to the Thread. - /// - managers: A vector of managers responsible for the Thread. - /// - publicMeta: Public metadata for the Thread, which will not be encrypted. - /// - privateMeta: Private metadata for the Thread, which will be encrypted. - /// - policies: A set of policies for the Container. + /// - Parameter contextId: ID of the Context to create the Thread in + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access to the created Thread + /// - Parameter managers: vector of UserWithPubKey structs which indicates who will have access (and management rights) to + /// the created Thread + /// - Parameter publicMeta: public (unencrypted) metadata + /// - Parameter privateMeta: private (encrypted) metadata + /// - Parameter policies: Thread's policies /// /// - Throws: `PrivMXEndpointError.failedCreatingThread` if the Thread creation fails. /// - /// - Returns: The ID of the newly created Thread as a `std.string`. + /// - Returns: ID of the created Thread public func createThread( contextId: std.string, users: privmx.UserWithPubKeyVector, @@ -98,13 +92,13 @@ public class ThreadApi{ return result } - /// Retrieves detailed information about a specific Thread. + /// Gets a Thread by given Thread ID. /// - /// - Parameter threadId: The unique identifier of the Thread to retrieve. + /// - Parameter threadId: ID of Thread to get /// /// - Throws: `PrivMXEndpointError.failedGettingThread` if fetching Thread details fails. /// - /// - Returns: A `privmx.endpoint.thread.Thread` instance representing the Thread details. + /// - Returns: Thread struct containing info about the Thread public func getThread( threadId: std.string ) throws -> privmx.endpoint.thread.Thread { @@ -122,22 +116,17 @@ public class ThreadApi{ return result } - /// Updates an existing Thread with new values. - /// - /// This method updates the metadata, users, and managers of a Thread. The update can be forced, and a new key can be generated if needed. - /// - /// If `policies` argument is set to `nil`, the default policies will be applied. - /// - /// - Parameters: - /// - threadId: The unique identifier of the Thread to be updated. - /// - version: The current version of the Thread to ensure version consistency. - /// - users: A vector of users who will have access to the Thread. - /// - managers: A vector of managers responsible for the Thread. - /// - publicMeta: New public metadata for the Thread, which will not be encrypted. - /// - privateMeta: New private metadata for the Thread, which will be encrypted. - /// - force: Whether to force the update, bypassing version control. - /// - forceGenerateNewKey: Whether to generate a new key for the Thread. - /// - policies: A new set of policies for the Container. + /// Updates an existing Thread. + /// + /// - Parameter threadId: ID of the Thread to update + /// - Parameter version: vector of UserWithPubKey structs which indicates who will have access to the created Thread + /// - Parameter users: vector of UserWithPubKey structs which indicates who will have access (and management rights) to + /// - Parameter managers: public (unencrypted) metadata + /// - Parameter publicMeta: private (encrypted) metadata + /// - Parameter privateMeta: current version of the updated Thread + /// - Parameter force: force update (without checking version) + /// - Parameter forceGenerateNewKey: force to regenerate a key for the Thread + /// - Parameter policies: Thread's policies /// /// - Throws: `PrivMXEndpointError.failedUpdatingThread` if the update process fails. public func updateThread( @@ -171,9 +160,9 @@ public class ThreadApi{ } } - /// Deletes a specified Thread. + /// Deletes a Thread by given Thread ID. /// - /// - Parameter threadId: The unique identifier of the Thread to delete. + /// - Parameter threadId: ID of the Thread to delete /// /// - Throws: `PrivMXEndpointError.failedDeletingThread` if the deletion fails. public func deleteThread( @@ -186,15 +175,14 @@ public class ThreadApi{ } } - /// Lists all Threads accessible to the user within a specified context. + /// Gets a list of Threads in given Context. /// - /// - Parameters: - /// - contextId: The unique identifier of the context from which to list Threads. - /// - pagingQuery: A query object to filter and paginate the results. + /// - Parameter contextId: ID of the Context to get the Threads from + /// - Parameter pagingQuery: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingThreads` if the listing process fails. /// - /// - Returns: A `privmx.ThreadList` instance containing the list of Threads. + /// - Returns: struct containing a list of Threads public func listThreads( contextId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -221,15 +209,14 @@ public class ThreadApi{ /// Sends a message in a Thread. /// - /// - Parameters: - /// - threadId: The unique identifier of the Thread to send the message to. - /// - publicMeta: Public metadata for the message, which will not be encrypted. - /// - privateMeta: Encrypted metadata for the message. - /// - data: The actual content of the message. + /// - Parameter threadId: ID of the Thread to send message to + /// - Parameter publicMeta: public message metadata + /// - Parameter privateMeta: private message metadata + /// - Parameter data: content of the message /// /// - Throws: `PrivMXEndpointError.failedCreatingMessage` if the message creation fails. /// - /// - Returns: The ID of the created message as a `std.string`. + /// - Returns: ID of the new message public func sendMessage( threadId: std.string, publicMeta: privmx.endpoint.core.Buffer, @@ -252,9 +239,9 @@ public class ThreadApi{ return result } - /// Deletes a specified message. + /// Deletes a message by given message ID. /// - /// - Parameter messageId: The unique identifier of the message to delete. + /// - Parameter messageId: ID of the message to delete /// /// - Throws: `PrivMXEndpointError.failedDeletingMessage` if the deletion process fails. public func deleteMessage( @@ -266,13 +253,13 @@ public class ThreadApi{ } } - /// Retrieves a specific message by its ID. + /// Gets a message by given message ID. /// - /// - Parameter messageId: The unique identifier of the message to retrieve. + /// - Parameter messageId: of the message to get /// /// - Throws: `PrivMXEndpointError.failedGettingMessage` if retrieving the message fails. /// - /// - Returns: A `privmx.endpoint.thread.Message` instance representing the message details. + /// - Returns: struct containing the message public func getMessage( _ messageId: std.string ) throws -> privmx.endpoint.thread.Message { @@ -290,15 +277,14 @@ public class ThreadApi{ return result } - /// Lists all messages from a specified Thread based on a query. + /// Gets a list of messages from a Thread. /// - /// - Parameters: - /// - threadId: The unique identifier of the Thread from which to list messages. - /// - pagingQuery: A query object to filter and paginate the results. + /// - Parameter threadId: ID of the Thread to list messages from + /// - Parameter pagingQuery: struct with list query parameters /// /// - Throws: `PrivMXEndpointError.failedListingMessages` if listing the messages fails. /// - /// - Returns: A `privmx.MessageList` instance containing the list of messages. + /// - Returns: struct containing a list of messages public func listMessages( threadId: std.string, pagingQuery: privmx.endpoint.core.PagingQuery @@ -323,13 +309,13 @@ public class ThreadApi{ ) throws -> privmx.MessageList { try listMessages(threadId: threadId, pagingQuery: query) } - /// Updates an existing message with new metadata and content. + + /// Update message in a Thread. /// - /// - Parameters: - /// - messageId: The unique identifier of the message to be updated. - /// - publicMeta: New public metadata for the message, which will not be encrypted. - /// - privateMeta: New encrypted metadata for the message. - /// - data: New content for the message, which will not be encrypted. + /// - Parameter messageId: ID of the message to update + /// - Parameter publicMeta: public message metadata + /// - Parameter privateMeta: private message metadata + /// - Parameter data: content of the message /// /// - Throws: `PrivMXEndpointError.failedUpdatingMessage` if the update fails. public func updateMessage( @@ -352,7 +338,7 @@ public class ThreadApi{ /// /// - Throws: When subscribing for events fails. /// - /// - Returns: list of subscriptionIds in maching order to subscriptionQueries. + /// - Returns: list of subscriptionIds in maching order to subscriptionQueries public func subscribeFor( subscriptionQueries: privmx.SubscriptionQueryVector ) throws -> privmx.SubscriptionIdVector { @@ -375,9 +361,9 @@ public class ThreadApi{ /// /// - Throws: When unsubscribing fails. public func unsubscribeFrom( - subscriptionId: privmx.SubscriptionIdVector + subscriptionIds: privmx.SubscriptionIdVector ) throws -> Void { - let res = api.unsubscribeFrom(subscriptionId) + let res = api.unsubscribeFrom(subscriptionIds) guard res.error.value == nil else { throw PrivMXEndpointError.failedUnsubscribingFromEvents(res.error.value!) } @@ -393,9 +379,9 @@ public class ThreadApi{ /// /// - Returns: a properly formatted event subscription request. public func buildSubscriptionQuery( - eventType: privmx.endpoint.thread.EventType, - selectorType: privmx.endpoint.thread.EventSelectorType, - selectorId: std.string + eventType: privmx.endpoint.thread.EventType, + selectorType: privmx.endpoint.thread.EventSelectorType, + selectorId: std.string ) throws -> privmx.SubscriptionQuery { let res = api.buildSubscriptionQuery(eventType, selectorType, selectorId) guard res.error.value == nil else { diff --git a/Sources/PrivMXEndpointSwiftNative/NativeConnectionWrapper.cpp b/Sources/PrivMXEndpointSwiftNative/NativeConnectionWrapper.cpp index 5f04513..7d31267 100644 --- a/Sources/PrivMXEndpointSwiftNative/NativeConnectionWrapper.cpp +++ b/Sources/PrivMXEndpointSwiftNative/NativeConnectionWrapper.cpp @@ -707,10 +707,10 @@ ResultWithError CoreEventHandlerWrapper::extractC return res; } -ResultWithError CoreEventHandlerWrapper::isContextUsersStatusChangeEvent(const core::EventHolder& eventHolder){ +ResultWithError CoreEventHandlerWrapper::isContextUsersStatusChangedEvent(const core::EventHolder& eventHolder){ ResultWithError res; try{ - res.result = core::Events::isContextUsersStatusChangeEvent(eventHolder); + res.result = core::Events::isContextUsersStatusChangedEvent(eventHolder); }catch(core::Exception& err){ res.error = { .name = err.getName(), @@ -733,10 +733,10 @@ ResultWithError CoreEventHandlerWrapper::isContextUsersStatusChangeEvent(c return res; } -ResultWithError CoreEventHandlerWrapper::extractContextUsersStatusChangeEvent(const core::EventHolder& eventHolder){ - ResultWithError res; +ResultWithError CoreEventHandlerWrapper::extractContextUsersStatusChangedEvent(const core::EventHolder& eventHolder){ + ResultWithError res; try{ - res.result = core::Events::extractContextUsersStatusChangeEvent(eventHolder); + res.result = core::Events::extractContextUsersStatusChangedEvent(eventHolder); }catch(core::Exception& err){ res.error = { .name = err.getName(), diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeBackendRequesterWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeBackendRequesterWrapper.hpp index 643f648..198f1ba 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeBackendRequesterWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeBackendRequesterWrapper.hpp @@ -17,49 +17,21 @@ namespace privmx{ class NativeBackendRequesterWrapper { public: - /** - * Sends a request to PrivMX Bridge API using access token for authorization. - * - * @param serverUrl PrivMX Bridge server URL - * @param accessToken token for authorization (see PrivMX Bridge API for more details) - * @param method API method to call - * @param params API method's parameters in JSON format - * - * @return JSON string representing raw server response - */ + static ResultWithError backendRequest( const std::string& serverUrl, const std::string& memberToken, const std::string& method, const std::string& paramsAsJson ); - /** - * Sends request to PrivMX Bridge API. - * - * @param serverUrl PrivMX Bridge server URL - * @param method API method to call - * @param params API method's parameters in JSON format - * - * @return JSON string representing raw server response - */ + static ResultWithError backendRequest( const std::string& serverUrl, const std::string& method, const std::string& paramsAsJson ); - /** - * Sends a request to PrivMX Bridge API using pair of API KEY ID and API KEY SECRET for authorization. - * - * @param serverUrl PrivMX Bridge server URL - * @param apiKeyId API KEY ID (see PrivMX Bridge API for more details) - * @param apiKeySecret API KEY SECRET (see PrivMX Bridge API for more details) - * @param mode allows you to set whether the request should be signed (mode = 1) or plain (mode = 0) - * @param method API method to call - * @param params API method's parameters in JSON format - * - * @return JSON string representing raw server response - */ + static ResultWithError backendRequest( const std::string& serverUrl, const std::string& apiKeyId, diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeConnectionWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeConnectionWrapper.hpp index 6e3df4d..4812bf6 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeConnectionWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeConnectionWrapper.hpp @@ -29,91 +29,32 @@ class NativeConnectionWrapper { friend class NativeEventApiWrapper; friend class NativeKvdbApiWrapper; public: - /** - * Connects to the PrivMX Bridge server. - * - * @param userPrivKey user's private key - * @param solutionId ID of the Solution - * @param platformUrl Platform's Endpoint URL - * - * @return Shared pointer to a Connection object, wrapped in the `ResultWithError` for error handling. - * - */ + static ResultWithError> connect(const std::string& userPrivKey, const std::string& solutionId, const std::string& bridgeUrl, const endpoint::core::PKIVerificationOptions& verificationOptions = endpoint::core::PKIVerificationOptions()); - /** - * Connects to the PrivMX Bridge server. - * - * @param userPrivKey user's private key - * @param solutionId ID of the Solution - * @param platformUrl Platform's Endpoint URL - * - * @return Shared pointer to a Connection object, wrapped in the `ResultWithError` for error handling. - * - */ + [[deprecated]] static ResultWithError> platformConnect(const std::string& userPrivKey, const std::string& solutionId, const std::string& platformUrl); - /** - * Connects to the PrivMX Bridge Server as a guest user. - * - * @param solutionId ID of the Solution - * @param platformUrl Platform's Endpoint URL - * - * @return Shared pointer to a Connection object, wrapped in `ResultWithError` for error handling. - * - */ static ResultWithError> connectPublic(const std::string& solutionId, const std::string& bridgeUrl, const endpoint::core::PKIVerificationOptions& verificationOptions = endpoint::core::PKIVerificationOptions()); - /** - * Connects to the PrivMX Bridge Server as a guest user. - * - * @param solutionId ID of the Solution - * @param platformUrl Platform's Endpoint URL - * - * @return Shared pointer to a Connection object, wrapped in `ResultWithError` for error handling. - * - */ + [[deprecated]] static ResultWithError> platformConnectPublic(const std::string& solutionId, const std::string& platformUrl); - /** - * Sets the path to.pem file with certificates. - * - * @param path : `const std::string&` — path of the certificate on the local filesystem - * - * @return `ResultWithError` object for error handling. - * - */ static ResultWithError setCertsPath(const std::string& path); - /** - * Gets the ID of the current connection. - * - * @return ID of the connection, wrapped in `ResultWithError` object for error handling. - */ ResultWithError getConnectionId(); - /** - * Disconnects from the PrivMX Bridge server. - * - * @return `ResultWithError` object for error handling. - */ ResultWithError disconnect(); - /** - * Gets a list of Contexts available for the user. - * - * @param pagingQuery struct with list query parameters - * - * @return struct containing a list of Contexts wrapped in a `ResultWithError` object for error handling. - */ + ResultWithError listContexts(const endpoint::core::PagingQuery& query); ResultWithError listContextUsers(const std::string& contextId, @@ -142,162 +83,38 @@ class NativeConnectionWrapper { class CoreEventHandlerWrapper{ public: - /** - * Checks whether event held in the 'EventHolder' is an 'LibBreakEvent' - * - * @return true for 'LibBreakEvent', else otherwise, wrapped in a `ResultWithError` object for error handling. - */ + static ResultWithError isLibBreakEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::LibBreakEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::LibBreakEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractLibBreakEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::LibPlatformDisconnectedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isLibPlatformDisconnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::LibPlatformDisconnectedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::LibPlatformDisconnectedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractLibPlatformDisconnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::LibConnectedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isLibConnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::LibConnectedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::LibConnectedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractLibConnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::LibDisconnectedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isLibDisconnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::LibDisconnectedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::LibDisconnectedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractLibDisconnectedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::CollectionChangedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isCollectionChangedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::CollectionChangedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::CollectionChangedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractCollectionChangedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::ContextUserAddedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isContextUserAddedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::ContextUserAddedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::ContextUserAddedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractContextUserAddedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::ContextUserRemovedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError isContextUserRemovedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::ContextUserRemovedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::ContextUserRemovedEvent` wrapped in a `ResultWithError` object for error handling. - * - */ static ResultWithError extractContextUserRemovedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Checks if an EventHolder contains an `privmx::endpoint::core::ContextUsersStatusChangeEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` object for error handling. - * - */ - static ResultWithError isContextUsersStatusChangeEvent(const endpoint::core::EventHolder& eventHolder); + static ResultWithError isContextUsersStatusChangedEvent(const endpoint::core::EventHolder& eventHolder); - /** - * Extracts an `privmx::endpoint::core::ContextUsersStatusChangeEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::core::ContextUsersStatusChangeEvent` wrapped in a `ResultWithError` object for error handling. - * - */ - static ResultWithError extractContextUsersStatusChangeEvent(const endpoint::core::EventHolder& eventHolder); + static ResultWithError extractContextUsersStatusChangedEvent(const endpoint::core::EventHolder& eventHolder); }; } diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeCryptoApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeCryptoApiWrapper.hpp index ad1372b..b38ba0f 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeCryptoApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeCryptoApiWrapper.hpp @@ -23,117 +23,38 @@ namespace privmx { class NativeCryptoApiWrapper{ public: - /** - * Constructor - */ static NativeCryptoApiWrapper create(); - /** - * Generates a new Private Key. - * - * @param baseString : `const OptionalString&` aka `const std::optional&` — Optional base for generating the key - * - * @return WIF Private Key, wrapped in a`ResultWithError` structure for error handling. - * - */ ResultWithError generatePrivateKey(const OptionalString& randomSeed); - /** - * Generates a new Private Key from two strings. - * - * @param password : `const std::string&` - * @param salt : `const std::string&` - * - * @return Private WIF key wrapped in a`ResultWithError` structure for error handling. - * - */ [[deprecated("Use derivePrivateKey2(const std::string& password, const std::string& salt).")]] ResultWithError derivePrivateKey(const std::string& password, const std::string& salt); - /** - * Generates a new Private Key from two strings. - * - * @param password : `const std::string&` - * @param salt : `const std::string&` - * - * @return Private WIF key wrapped in a`ResultWithError` structure for error handling. - * - */ ResultWithError derivePrivateKey2(const std::string& password, const std::string& salt); - /** - * Derives a Public Key from the private one. - * - * @param privKey : `const std::string&` — Private WIF key - * - * @return WIF Public key wrapped in a`ResultWithError` structure for error handling. - * - */ ResultWithError derivePublicKey(const std::string& privKey); - - /** - * Encrypts data using AES. - * - * @param data : `const endpoint::core::Buffer&` — data to be encrypted - * @param key : `const endpoint::core::Buffer&` — 256-bit long binary key - * - * @return Encrypted data wrapped in a`ResultWithError` structure for error handling. - * - */ + ResultWithError encryptDataSymmetric(const endpoint::core::Buffer& data, const endpoint::core::Buffer& key); - /** - * Decrypts data using AES. - * - * @param data : `const endpoint::core::Buffer&` — data to be decrypted - * @param key : `const endpoint::core::Buffer&` — 256-bit long binary key - * - * @return Decrypted data wrapped in a`ResultWithError` structure for error handling. - * - */ + ResultWithError decryptDataSymmetric(const endpoint::core::Buffer& data, const endpoint::core::Buffer& key); - /** - * Creates a signature of given data and key. - * - * @param data : `const endpoint::core::Buffer&` — data to sign - * @param key : `const std::string&` — WIF key - * - * @return Signed data wrapped in a`ResultWithError` structure for error handling. - * - */ ResultWithError signData(const endpoint::core::Buffer& data, const std::string& key); - /** - * Validate a signature of data using given key. - * - * @param data buffer containing the data signature of which is being verified - * @param signature signature to be verified - * @param publicKey public ECC key in BASE58DER format used to validate data - * @return data validation result - */ ResultWithError verifySignature( const endpoint::core::Buffer& data, const endpoint::core::Buffer& signature, const std::string& publicKey ); - /** - * Converts a key from PEM format to WIF. - * - * @param keyPEM : `const std::string&` — kei in PEM format - * - * @return WIF Key wrapped in a`ResultWithError` structure for error handling. - * - */ ResultWithError convertPEMKeyToWIFKey(const std::string& keyPEM); - /// Generates a key for symmetric encryption + ResultWithError generateKeySymmetric(); ResultWithError convertPGPAsn1KeyToBase58DERKey(const std::string& pgpKey); diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeEventApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeEventApiWrapper.hpp index d176ca2..5fb9524 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeEventApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeEventApiWrapper.hpp @@ -25,25 +25,10 @@ class NativeEventApiWrapper { const std::string& channelName, const endpoint::core::Buffer& eventData); - /** - * Subscribe for the Thread events on the given subscription query. - * - * @param subscriptionQueries list of queries - * @return list of subscriptionIds in maching order to subscriptionQueries - */ ResultWithError subscribeFor(const SubscriptionQueryVector& subscriptionQueries); - /** - * Unsubscribe from events for the given subscriptionId. - * @param subscriptionIds list of subscriptionId - */ ResultWithError unsubscribeFrom(const SubscriptionIdVector& subscriptionIds); - /** - * Generate subscription Query for the Thread events. - * @param eventType type of event which you listen for - * @param selectorType scope on which you listen for events - * @param selectorId ID of the selector - */ + ResultWithError buildSubscriptionQuery(const std::string& channelName, endpoint::event::EventSelectorType selectorType, const std::string& selectorId); diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeEventQueueWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeEventQueueWrapper.hpp index e250fee..a9d17fe 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeEventQueueWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeEventQueueWrapper.hpp @@ -24,38 +24,13 @@ namespace privmx { class NativeEventQueueWrapper{ public: - /** - * Returns an instance of `EventQueue`. Note that all instances share the same queue. - * - *@return `privmx::endpoint::core::EventQueue` wrapped in a `ResultWithError` structure for error handling. - */ + static ResultWithError getInstance(); - /** - * Emits a special event that allows for ending of a running `waitEvent()` - * - *@return `ResultWithError` structure for error handling. - */ ResultWithError emitBreakEvent(); - /** - * Waits for an event from Platform Bridge. - * - * If there are no events available, this method wil wait until a new one arrives. - * - * @return `privmx::endpoint::core::EventHolder` wrapped in a `ResultWithError` structure for error handling. - * - */ ResultWithError waitEvent(); - /** - * Returns an event from Platform Bringe, if one is available - * - * This method returns immediately, regardles if there were any events. - * - * @return Optional `privmx::endpoint::core::EventHolder` wrapped in a `ResultWithError` structure for error handling. - * - */ ResultWithError> getEvent(); private: std::shared_ptr api; diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeInboxApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeInboxApiWrapper.hpp index 14832d7..b40db10 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeInboxApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeInboxApiWrapper.hpp @@ -24,19 +24,7 @@ class NativeInboxApiWrapper{ NativeThreadApiWrapper& threadApi, NativeStoreApiWrapper& storeApi); - /** - * Creates a new Inbox. - * - * @param contextId ID of the Context of the new Inbox - * @param users vector of UserWithPubKey structs which indicates who will have access to the created Inbox - * @param managers vector of UserWithPubKey structs which indicates who will have access (and management rights) to - * the created Inbox - * @param publicMeta public (unencrypted) meta data - * @param privateMeta private (encrypted) meta data - * @param filesConfig struct to override default file configuration - * @return string inbox ID - * @param policies Inbox policies - */ + ResultWithError createInbox(const std::string& contextId, const UserWithPubKeyVector& users, const UserWithPubKeyVector& managers, @@ -45,21 +33,7 @@ class NativeInboxApiWrapper{ const OptionalInboxFilesConfig& filesConfig, const OptionalContainerPolicyWithoutItem& policies); - /** - * Updates an existing Inbox. - * - * @param inboxId ID of the Inbox to update - * @param users vector of UserWithPubKey structs which indicates who will have access to the created Inbox - * @param managers vector of UserWithPubKey structs which indicates who will have access (and have manage rights) to - * the created Inbox - * @param publicMeta public (unencrypted) meta data - * @param privateMeta private (encrypted) meta data - * @param filesConfig struct to override default files configuration - * @param version current version of the updated Inbox - * @param force force update (without checking version) - * @param forceGenerateNewKey force to renenerate a key for the Inbox - * @param policies Inbox policies - */ + ResultWithError updateInbox(const std::string& inboxId, const UserWithPubKeyVector& users, const UserWithPubKeyVector& managers, @@ -71,168 +45,68 @@ class NativeInboxApiWrapper{ const bool forceGenerateNewKey, const OptionalContainerPolicyWithoutItem& policies = std::nullopt); - /** - * Gets a single Inbox by given Inbox ID. - * - * @param inboxId ID of the Inbox to get - * @return Inbox struct containing information about the Inbox - */ + ResultWithError getInbox(const std::string& inboxId); - /** - * Gets s list of Inboxes in given Context. - * - * @param contextId ID of the Context to get Inboxes from - * @param pagingQuery sturct with list query parameters - * @return PagingList struct containing list of Inboxes - */ + ResultWithError listInboxes(const std::string& contextId, const endpoint::core::PagingQuery& pagingQuery); - /** - * Gets public data of given Inbox. - * You do not have to be logged in to call this function. - * - * @param inboxId ID of the Inbox to get - * @return InboxPublicView struct containing public accessible information about the Inbox - */ + ResultWithError getInboxPublicView(const std::string& inboxId); - /** - * Deletes an Inbox by given Inbox ID. - * The function also removes the related Thread and Store. - * - * @param inboxId ID of the Inbox to delete - */ + ResultWithError deleteInbox(const std::string& inboxId); - /** - * Prepares a request to send data to an Inbox. - * You do not have to be logged in to call this function. - * - * @param inboxId ID of the Inbox to which the request applies - * @param inboxFileHandles optional list of file handles that will be sent with the request - * @param userPrivKey optional sender's private key which can be used later to encrypt data for that sender - * @return int64_t Inbox handle - */ + ResultWithError prepareEntry(const std::string& inboxId, const endpoint::core::Buffer& data, const InboxFileHandleVector& inboxFileHandles = InboxFileHandleVector(), const OptionalString& userPrivKey = std::nullopt); - /** - * Sends data to an Inbox. - * You do not have to be logged in to call this function. - * - * @param entryHandle ID of the Inbox to which the request applies - */ + ResultWithError sendEntry(const EntryHandle entryHandle); - /** - * Gets an entry from an Inbox. - * - * @param inboxEntryId ID of an entry to read from the Inbox - * @return InboxEntry struct containing data of the selected entry stored in the Inbox - */ + ResultWithError readEntry(const std::string& inboxEntryId); - /** - * Gets list of entries of given Inbox. - * - * @param inboxId ID of the Inbox - * @param pagingQuery sturct with list query parameters - * @return PagingList struct containing list of entries - */ + ResultWithError listEntries(const std::string& inboxId, const endpoint::core::PagingQuery& pagingQuery); - /** - * Delete an entry from an Inbox. - * - * @param inboxEntryId ID of an entry to delete from the Inbox - */ + ResultWithError deleteEntry(const std::string& inboxEntryId); - /** - * Creates a file handle to send a file to an Inbox. - * You do not have to be logged in to call this function. - * - * @param publicMeta public file meta_data - * @param privateMeta private file meta_data - * @param fileSize size of the file to send - * @return int64_t file handle - */ + ResultWithError createFileHandle(const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta, const int64_t& fileSize); - /** - * Sends a file's data chunk to an Inbox. - * :::note To send the entire file - divide it into pieces of the desired size and call the function for each fragment. ::: - * You do not have to be logged in to call this function. - * - * @param entryHandle Handle to the prepared Inbox entry - * @param inboxFileHandle handle to the file where the uploaded chunk belongs - * @param Buffer dataChunk - file chunk to send - */ + ResultWithError writeToFile(const EntryHandle entryHandle, const InboxFileHandle inboxFileHandle, const endpoint::core::Buffer& dataChunk); - /** - * Opens a file to read. - * - * @param fileId ID of the file to read - * @return int64_t handle to read file data - */ + ResultWithError openFile(const std::string& fileId); - /** - * Reads file data. - * - * @param fileHandle handle to the file - * @param length size of data to read - * @return core::Buffer buffer with file data chunk - */ + ResultWithError readFromFile(const InboxFileHandle fileHandle, const int64_t length); - /** - * Moves file's read cursor. - * - * @param handle handle to the file - * @param position sets new cursor position - */ + ResultWithError seekInFile(const InboxFileHandle fileHandle, const int64_t position); - /** - * Closes the file by given handle. - * - * @param handle handle to the file - * @return string ID of closed file - */ + ResultWithError closeFile(const InboxFileHandle fileHandle); - /** - * Subscribe for the Thread events on the given subscription query. - * - * @param subscriptionQueries list of queries - * @return list of subscriptionIds in maching order to subscriptionQueries - */ + ResultWithError subscribeFor(const SubscriptionQueryVector& subscriptionQueries); - /** - * Unsubscribe from events for the given subscriptionId. - * @param subscriptionIds list of subscriptionId - */ + ResultWithError unsubscribeFrom(const SubscriptionIdVector& subscriptionIds); - /** - * Generate subscription Query for the Thread events. - * @param eventType type of event which you listen for - * @param selectorType scope on which you listen for events - * @param selectorId ID of the selector - */ + ResultWithError buildSubscriptionQuery(endpoint::inbox::EventType eventType, endpoint::inbox::EventSelectorType selectorType, const std::string& selectorId); diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeKvdbApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeKvdbApiWrapper.hpp index 7613f7c..4a8a47b 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeKvdbApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeKvdbApiWrapper.hpp @@ -16,13 +16,7 @@ namespace privmx { class NativeKvdbApiWrapper { public: - /** - * Creates an instance of 'KvdbApi'. - * - * @param connection instance of 'Connection' - * - * @return KvdbApi object - */ + static ResultWithError create(NativeConnectionWrapper& connection); ResultWithError createKvdb(const std::string& contextId, @@ -63,18 +57,10 @@ class NativeKvdbApiWrapper { const std::string& key); ResultWithError deleteEntries(const std::string& kvdbId, const StringVector& keys); - /** - * Subscribe for the Thread events on the given subscription query. - * - * @param subscriptionQueries list of queries - * @return list of subscriptionIds in maching order to subscriptionQueries - */ + ResultWithError subscribeFor(const SubscriptionQueryVector& subscriptionQueries); - /** - * Unsubscribe from events for the given subscriptionId. - * @param subscriptionIds list of subscriptionId - */ + ResultWithError unsubscribeFrom(const SubscriptionIdVector& subscriptionIds); ResultWithError buildSubscriptionQuery(endpoint::kvdb::EventType eventType, diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeStoreApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeStoreApiWrapper.hpp index c46a8ed..6080f33 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeStoreApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeStoreApiWrapper.hpp @@ -25,47 +25,14 @@ namespace privmx { class NativeStoreApiWrapper{ friend class NativeInboxApiWrapper; public: - /** - * Creates a new instance of the class. - * - * @param connection: NativeConnectionWrapper& — a reference to an instance of `privmx::NativeConnectionWrapper` - */ + static ResultWithError create(NativeConnectionWrapper& connection); - /** - * Lists Stores the user has access to in the provided Context. - * - * @param contextId : `const std::string&` — from which Context should the Threads be listed - * @param pagingQuery : `privmx::endpoint::core::PagingQuery` — parameters of the query - * - * @return `privmx::StoreList` aka `privmx::endpoint::core::PagingList` instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError listStores(const std::string& contextId, const endpoint::core::PagingQuery& pagingQuery); - /** - * Retrieves information about a Store. - * - * @param storeId : `const std::string&` — which Store is to be retrieved - * - * @return `privmx::endpoint::store::Store`instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError getStore(const std::string& storeId); - /** - * Creates a new Store in the specified Context - * - * Note that managers do not gain acess to the Store without being added as users. - * - * @param contextId : `const std::string&` — in which Context should the Store be created - * @param users : `const UserWithPubKeyVector&` — who can access the Store - * @param managers : `const UserWithPubKeyVector&` — who can manage the Store - * @param publicMeta public (unencrypted) metadata - * @param privateMeta private (encrypted) metadata - * @param policies additional container access policies - * - * @return Id of the newly created Store wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError createStore(const std::string& contextId, const UserWithPubKeyVector& users, const UserWithPubKeyVector& managers, @@ -73,32 +40,8 @@ class NativeStoreApiWrapper{ const endpoint::core::Buffer& privateMeta, const OptionalContainerPolicy& policies = std::nullopt); - /** - * Deletes a Store. - * - * @param storeId : `const std::string&` — which Store is to be deleted - * - * @return A `ResultWithError` structure for error handling. - */ ResultWithError deleteStore(const std::string& storeId); - /** - * Updates an existing Store. - * - * The provided values override preexisting values. - * - * @param storeId : `const std::string&` — which Store is to be updated - * @param users : `const UserWithPubKeyVector&` — who can access the Store - * @param managers : `const UserWithPubKeyVector&` — who can manage the Store - * @param publicMeta public (unencrypted) metadata - * @param privateMeta private (encrypted) metadata - * @param version : `const int64_t` — current version of the Store - * @param force : `const bool` — force the update by disregarding the cersion check - * @param forceGenerateNewKey force to regenerate a key for the Store - * @param policies additional container access policies - * - * @return `ResultWithError` structure for error handling. - */ ResultWithError updateStore(const std::string& storeId, const UserWithPubKeyVector& users, const UserWithPubKeyVector& managers, @@ -109,157 +52,50 @@ class NativeStoreApiWrapper{ const bool forceGenerateNewKey, const OptionalContainerPolicy& = std::nullopt); - /** - * Retrieves information about a File - * - * This does not download the file itself, for that see `openFile()` and `readFromFile()` - * - * @param threadId : `const std::string&` — which Thread is to be updated - * - * @return Information about the specified file wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError getFile(const std::string& fileId); - /** - * Lists information about Files in a Store - * - * This does not download the files themselves, for that see `openFile()` and `readFromFile()` - * - * @param storeId : `const std::string&` — from which Store should the Files be listed - * - * @return `privmx::FileList` wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError listFiles(const std::string& storeId, const endpoint::core::PagingQuery& pagingQuery); - /** - * Creates a new file handle for writing in a Store - * - * This creates a temporary file, use `writeToFile()` to upload data and `closeFile()` to finalise the process. - * - * @param storeId : `const std::string&` — in which Store should the File be created - * @param size : `const int64_t` — the size of the file - * @param mimetype : `const std::string&` — type of the file - * @param name : `const std::string&` — the name of the file - * - * @return `privmx::PMXFileHandle` for writing, wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError createFile(const std::string &storeId, const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta, int64_t size, bool randomWriteSupport = false); - /** - * Creates a new file handle for overwiting a file. - * - * @param fileId : `const std::string&` — which File should be updated - * @param size : `const int64_t` — the size of the file - * @param mimetype : `const std::string&` — type of the file - * @param name : `const std::string&` — the name of the file - * - * @return `privmx::PMXFileHandle` for writing, wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError updateFile(const std::string& fileId, const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta, int64_t size); - /** - * Update metadata of an existing file in a Store. - * - * @param fileId ID of the file to update - * @param publicMeta public file metadata - * @param privateMeta private file metadata - */ ResultWithError updateFileMeta(const std::string& fileId, const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta); - /** - * Creates a new file handle for reading a File. - * - * @param fileId : `const std::string&` — which File should be opened - * - * @return `privmx::PMXFileHandle` for reading, wrapped in a`ResultWithError` structure for error handling. - */ + ResultWithError openFile(const std::string& fileId); - /** - * Writes a chunk of data to an opened file on the Platform. - * - * @param handle : `const PMXFileHandle` aka `const int64_t` — the handle to an opened file - * @param dataChunk : `const privmx::endpoint::core::Buffer&` — the data to be uploaded - * - * @return `ResultWithError` structure for error handling. - */ + ResultWithError writeToFile(const StoreFileHandle handle, const endpoint::core::Buffer& dataChunk, bool truncate=false); - - /** - * Reads from an opened file. - * - * @param handle : `const PMXFileHandle` aka `const int64_t` — the handle to an opened file - * @param length : `const int64_t` — amount of bytes to be read - * - * @return The downloaded data read from a file, wrapped in a`ResultWithError` structure for error handling. - */ + ResultWithError readFromFile(const StoreFileHandle handle, int64_t length); - /** - * Moves read cursor in an open File. - * - * @param handle : `const PMXFileHandle` aka `const int64_t` — the handle to an opened file - * @param pos : `const int64_t` — new position of the cursor - * - * @return `ResultWithError` structure for error handling. - */ ResultWithError seekInFile(const StoreFileHandle handle, int64_t position); - /** - * Closes an open File - * - * @param handle : `const PMXFileHandle` aka `const int64_t` — the handle to an open file - * - * @return The Id of the File, wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError closeFile(const StoreFileHandle handle); - - /** - * Deletes the specified File. - * - * - * @param fileId : `const std::string&` — File to be deleted - * - * - * @return Status of the operation, wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError deleteFile(const std::string& fileId); ResultWithError syncFile(const StoreFileHandle handle); - /** - * Subscribe for the Thread events on the given subscription query. - * - * @param subscriptionQueries list of queries - * @return list of subscriptionIds in maching order to subscriptionQueries - */ + ResultWithError subscribeFor(const SubscriptionQueryVector& subscriptionQueries); - /** - * Unsubscribe from events for the given subscriptionId. - * @param subscriptionIds list of subscriptionId - */ ResultWithError unsubscribeFrom(const SubscriptionIdVector& subscriptionIds); - /** - * Generate subscription Query for the Thread events. - * @param eventType type of event which you listen for - * @param selectorType scope on which you listen for events - * @param selectorId ID of the selector - */ + ResultWithError buildSubscriptionQuery(endpoint::store::EventType eventType, endpoint::store::EventSelectorType selectorType, const std::string& selectorId); diff --git a/Sources/PrivMXEndpointSwiftNative/include/NativeThreadApiWrapper.hpp b/Sources/PrivMXEndpointSwiftNative/include/NativeThreadApiWrapper.hpp index 76e6676..c3c6732 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/NativeThreadApiWrapper.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/NativeThreadApiWrapper.hpp @@ -26,25 +26,9 @@ namespace privmx { class NativeThreadApiWrapper{ friend class NativeInboxApiWrapper; public: - /** - * Constructor - * - * @param connection: NativeConnectionWrapper& — a reference to an instance of `privmx::NativeConnectionWrapper` - */ + static ResultWithError create(NativeConnectionWrapper& connection); - /** - * Creates a new Thread on the Platform. - * - * Note that managers do not gain acess to the thread without being added as users. - * - * @param contextId : `const std::string&` — in which Context should the thread be created - * @param users : `const UserWithPubKeyVector&` — who can access the Thread - * @param managers : `const UserWithPubKeyVector&` — who can manage the thread - * @param title : `const std::string&` — the title of the thread - * @param policies additional container access policies - * @return Id of the newly created Thread wrapped in a`ResultWithError` structure for error handling. - */ ResultWithError createThread(const std::string& contextId, const UserWithPubKeyVector& users, const UserWithPubKeyVector& managers, @@ -52,32 +36,8 @@ class NativeThreadApiWrapper{ const endpoint::core::Buffer& privateMeta, const OptionalContainerPolicy& policies = std::nullopt); - /** - * Retrieves information about a thread. - * - * @param threadId : `const std::string&` — which Thread is to be retrieved - * - * @return `privmx::endpoint::thread::Thread`instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError getThread(const std::string& threadId); - /** - * Updates an existing Thread. - * - * The provided values override preexisting values. - * - * @param threadId : `const std::string&` — which Thread is to be updated - * @param users : `const UserWithPubKeyVector&` — who can access the Thread - * @param managers : `const UserWithPubKeyVector&` — who can manage the thread - * @param title : `const std::string&` — the title of the thread - * @param version : `const int64_t` — current version of the Thread - * @param force : `const bool` — force the update by disregarding the cersion check - * @param generateNewKeyId : `const bool` — force regeneration of new keyId for Thread - * @param accessToOldDataForNewUsers : `const bool` — placeholder parameter (does nothing for now) - * @param policies additional container access policies - * - * @return `ResultWithError` structure for error handling. - */ ResultWithError updateThread(const std::string& threadId, const std::vector& users, const std::vector& managers, @@ -88,103 +48,30 @@ class NativeThreadApiWrapper{ const bool forceGenerateNewKey, const OptionalContainerPolicy& policies = std::nullopt); - /** - * Deletes a Thread. - * - * @param threadId : `const std::string&` — which Thread is to be deleted - * - * @return A `ResultWithError` structure for error handling. - */ ResultWithError deleteThread(const std::string& threadId); - /** - * Lists Threads the user has access to in provided Context. - * - * @param contextId : `const std::string&` — from which Context should the Threads be listed - * @param query : `privmx::endpoint::core::PagingQuery` — parameters of the query - * - * @return `privmx::ThreadList`instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError listThreads(const std::string& contextId, const endpoint::core::PagingQuery& pagingQuery); - /** - * Sends a message in a thread - * - * @param threadId : `const std::string&` — Message to be deleted - * @param publicMeta : `const privmx::endpoint::core::Buffer&` —Meta_data that will not be encrypted on the Platform - * @param privateMeta : `const privmx::endpoint::core::Buffer&` — Meta_data that will be encrypted on the Platform - * @param data : `const privmx::endpoint::core::Buffer&` — Actual message - * - * - * @return Id of the created message, wrappend in a `ResultWithError` structure for error handling. - */ ResultWithError sendMessage(const std::string& threadId, const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta, const endpoint::core::Buffer& data); - /** - * Deletes the specified Message. - * - * @param messageId : `const std::string&` — Message to be deleted - * - * @return `ResultWithError` structure for error handling. - */ ResultWithError deleteMessage(const std::string& messageId); - /** - * Retrieves the message with specified Id. - * - * @param messageId : `const std::string&` — Message to be retrieved - * @param messageId : `const std::string&` — Message to be retrieved - * - * @return `privmx::endpoint::thread::Message`instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError getMessage(const std::string& messageId); - /** - * Lists Messages from a particular Thread - * - * @param threadId : `const std::string&` — from which Thread should the Messages be listed - * @param query : `privmx::endpoint::core::PagingQuery` — parameters of the query - * - * @return `privmx::MessageList`instance wrapped in a `ResultWithError` structure for error handling. - */ ResultWithError listMessages(const std::string& threadId, const endpoint::core::PagingQuery& pagingQuery); - - /** - * Sends message in a Thread. - * - * @param messageId ID of the message to update - * @param publicMeta public message meta_data - * @param privateMeta private message meta_data - * @param data content of the message - */ ResultWithError updateMessage(const std::string& messageId, const endpoint::core::Buffer& publicMeta, const endpoint::core::Buffer& privateMeta, const endpoint::core::Buffer& data); - /** - * Subscribe for the Thread events on the given subscription query. - * - * @param subscriptionQueries list of queries - * @return list of subscriptionIds in maching order to subscriptionQueries - */ ResultWithError subscribeFor(const SubscriptionQueryVector& subscriptionQueries); - /** - * Unsubscribe from events for the given subscriptionId. - * @param subscriptionIds list of subscriptionId - */ ResultWithError unsubscribeFrom(const SubscriptionIdVector& subscriptionIds); - /** - * Generate subscription Query for the Thread events. - * @param eventType type of event which you listen for - * @param selectorType scope on which you listen for events - * @param selectorId ID of the selector - */ + ResultWithError buildSubscriptionQuery(endpoint::thread::EventType eventType, endpoint::thread::EventSelectorType selectorType, const std::string& selectorId); @@ -203,163 +90,38 @@ class NativeThreadApiWrapper{ class ThreadEventHandler{ public: -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadCreatedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadCreatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadCreatedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadCreatedEvent` wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError extractThreadCreatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadUpdatedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadUpdatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadUpdatedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadUpdatedEvent` wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError extractThreadUpdatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadDeletedEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadDeletedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadDeletedEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadDeletedEvent` wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError extractThreadDeletedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadNewMessageEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadNewMessageEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadNewMessageEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadNewMessageEvent` wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError extractThreadNewMessageEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadDeletedMessageEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ [[deprecated("Has been renamed, use isThreadDeletedMessageEvent")]] static ResultWithError isThreadDeletedMessageEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadDeletedMessageEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadMessageDeletedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadDeletedMessageEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadMessageUpdatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadDeletedMessageEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadDeletedMessageEvent` wrapped in a `ResultWithError` structure for error handling. - */ [[deprecated("Has been renamed, use extractThreadMessageDeletedEvent")]] static ResultWithError extractThreadDeletedMessageEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadDeletedMessageEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadDeletedMessageEvent` wrapped in a `ResultWithError` structure for error handling. - */ static ResultWithError extractThreadMessageDeletedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadDeletedMessageEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadDeletedMessageEvent` wrapped in a `ResultWithError` structure for error handling. - */ static ResultWithError extractThreadMessageUpdatedEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Checks if an EventHolder contains an `privmx::endpoint::thread::ThreadStatsEvent` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Boolean value wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError isThreadStatsEvent(const endpoint::core::EventHolder& eventHolder); -/** - * Extracts an `privmx::endpoint::thread::ThreadStatsEvent` from the `privmx::endpoint::core::EventHolder` - * - * @param eventHolder : `const endpoint::core::EventHolder&` - * - * @return Extracted `privmx::endpoint::thread::ThreadStatsEvent` wrapped in a `ResultWithError` structure for error handling. - * - */ static ResultWithError extractThreadStatsEvent(const endpoint::core::EventHolder& eventHolder); }; diff --git a/Sources/PrivMXEndpointSwiftNative/include/PrivMXUtils.hpp b/Sources/PrivMXEndpointSwiftNative/include/PrivMXUtils.hpp index 3672bfb..2ea0b4f 100644 --- a/Sources/PrivMXEndpointSwiftNative/include/PrivMXUtils.hpp +++ b/Sources/PrivMXEndpointSwiftNative/include/PrivMXUtils.hpp @@ -721,7 +721,7 @@ static privmx::SubscriptionIdVector _get_subIds_from(const privmx::endpoint::cor static privmx::SubscriptionIdVector _get_subIds_from(const privmx::endpoint::core::ContextUserRemovedEvent& event){ return _get_subIds_from_event(event); } -static privmx::SubscriptionIdVector _get_subIds_from(const privmx::endpoint::core::ContextUsersStatusChangeEvent& event){ +static privmx::SubscriptionIdVector _get_subIds_from(const privmx::endpoint::core::ContextUsersStatusChangedEvent& event){ return _get_subIds_from_event(event); } static privmx::SubscriptionIdVector _get_subIds_from(const privmx::endpoint::core::CollectionChangedEvent& event){