ObjMatrix  Documentation

/*
 * Copyright (c) 2020, 2021, 2024 Jonathan Schleifer <js@nil.im>
 *
 * https://fl.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 appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

#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