/*
* Copyright (c) 2020, 2021, 2024, Jonathan Schleifer <js@nil.im>
*
* https://fossil.nil.im/objmatrix
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice is present in all copies.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
#import <ObjFW/ObjFW.h>
#import "MTXStorage.h"
OF_ASSUME_NONNULL_BEGIN
@class MTXClient;
/**
* @brief A block called when a new login succeeded or failed.
*
* @param client If the login succeeded, the newly created client
* @param exception If the login failed, an exception
*/
typedef void (^MTXClientLoginBlock)(MTXClient *_Nullable client,
id _Nullable exception);
/**
* @brief A block called when the response for an operation was received.
*
* @param exception `nil` on success, otherwise an exception
*/
typedef void (^MTXClientResponseBlock)(id _Nullable exception);
/**
* @brief A block called when an exception occurred during sync.
*
* @param exception The exception which occurred during sync
*/
typedef void (^MTXSyncExceptionHandlerBlock)(id exception);
/**
* @brief A block called when the room list was fetched.
*
* @param rooms An array of joined rooms, or nil on error
* @param exception An exception if fetching the room list failed
*/
typedef void (^MTXClientRoomListBlock)(OFArray<OFString *> *_Nullable rooms,
id _Nullable exception);
/**
* @brief A block called when a room was joined.
*
* @param roomID The room ID that was joined, or nil on error. This can be used
* to get the room ID if a room alias was joined.
* @param exception An exception if joining the room failed
*/
typedef void (^MTXClientRoomJoinBlock)(OFString *_Nullable roomID,
id _Nullable exception);
/**
* @brief A class that represents a client.
*/
@interface MTXClient: OFObject
/**
* @brief The user ID used by the client.
*/
@property (readonly, nonatomic) OFString *userID;
/**
* @brief The device ID used by the client.
*/
@property (readonly, nonatomic) OFString *deviceID;
/**
* @brief The access token used by the client.
*/
@property (readonly, nonatomic) OFString *accessToken;
/**
* @brief The homeserver used by the client.
*/
@property (readonly, nonatomic) OFIRI *homeserver;
/**
* @brief The storage used by the client.
*/
@property (readonly, nonatomic) id <MTXStorage> storage;
/**
* @brief The timeout for sync requests.
*
* Defaults to 5 minutes.
*/
@property (nonatomic) OFTimeInterval syncTimeout;
/**
* @brief A block to handle exceptions that occurred during sync.
*/
@property (copy, nonatomic) MTXSyncExceptionHandlerBlock syncExceptionHandler;
/**
* @brief Creates a new client with the specified access token on the specified
* homeserver.
*
* @param userID The user ID for the client
* @param deviceID The device ID for the client
* @param accessToken The access token for the client
* @param homeserver The IRI of the homeserver
* @param storage The storage the client should use
* @return An autoreleased MTXClient
*/
+ (instancetype)clientWithUserID: (OFString *)userID
deviceID: (OFString *)deviceID
accessToken: (OFString *)accessToken
homeserver: (OFIRI *)homeserver
storage: (id <MTXStorage>)storage;
/**
* @brief Logs into the homeserver and creates a new client.
*
* @param user The user to log into
* @param password The password to log in with
* @param homeserver The homeserver to log into
* @param storage The storage the client should use
* @param block A block to call once login succeeded or failed
*/
+ (void)logInWithUser: (OFString *)user
password: (OFString *)password
homeserver: (OFIRI *)homeserver
storage: (id <MTXStorage>)storage
block: (MTXClientLoginBlock)block;
/**
* @brief Initializes an already allocated client with the specified access
* token on the specified homeserver.
*
* @param userID The user ID for the client
* @param deviceID The device ID for the client
* @param accessToken The access token for the client
* @param homeserver The IRI of the homeserver
* @param storage The storage the client should use
* @return An initialized MTXClient
*/
- (instancetype)initWithUserID: (OFString *)userID
deviceID: (OFString *)deviceID
accessToken: (OFString *)accessToken
homeserver: (OFIRI *)homeserver
storage: (id <MTXStorage>)storage
OF_DESIGNATED_INITIALIZER;
/**
* @brief Starts the sync loop.
*/
- (void)startSyncLoop;
/**
* @brief Stops the sync loop.
*
* The currently waiting sync is not aborted, but after it returns, no new sync
* will be started.
*/
- (void)stopSyncLoop;
/**
* @brief Logs out the device and invalidates the access token.
*
* @warning The client can no longer be used after this succeeded!
*
* @param block A block to call when logging out succeeded or failed
*/
- (void)logOutWithBlock: (MTXClientResponseBlock)block;
/**
* @brief Fetches the list of joined rooms.
*
* @param block A block to call with the list of joined room
*/
- (void)fetchRoomListWithBlock: (MTXClientRoomListBlock)block;
/**
* @brief Joins the specified room.
*
* @param room The room to join. Either a room ID or a room alias.
* @param block A block to call when the room was joined
*/
- (void)joinRoom: (OFString *)room block: (MTXClientRoomJoinBlock)block;
/**
* @brief Leaves the specified room.
*
* @param roomID The room ID to leave
* @param block A block to call when the room was left
*/
- (void)leaveRoom: (OFString *)roomID block: (MTXClientResponseBlock)block;
/**
* @brief Sends the specified message to the specified room ID.
*
* @param message The message to send
* @param roomID The room ID to which to send the message
* @param block A block to call when the message was sent
*/
- (void)sendMessage: (OFString *)message
roomID: (OFString *)roomID
block: (MTXClientResponseBlock)block;
@end
OF_ASSUME_NONNULL_END