/*
* 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>
OF_ASSUME_NONNULL_BEGIN
/**
* @brief A response to a request.
*
* This is a typedef for `OFDictionary<OFString *, id> *`.
*/
typedef OFDictionary<OFString *, id> *MTXResponse;
/**
* @brief A block called with the response for an MTXRequest.
*
* @param response The response to the request, as a dictionary parsed from JSON
* @param statusCode The HTTP status code returned for the request
* @param exception The first exception that occurred during the request,
* or `nil` on success
*/
typedef void (^MTXRequestBlock)(MTXResponse _Nullable response, int statusCode,
id _Nullable exception);
/**
* @brief An internal class for performing a request on the Matrix server.
*/
@interface MTXRequest: OFObject <OFHTTPClientDelegate>
/**
* @brief The access token to use.
*
* Some requests are unauthenticated - for those, the access token is `nil`.
*/
@property (readonly, nonatomic, nullable) OFString *accessToken;
/**
* @brief The IRI of the homeserver to send the request to.
*/
@property (readonly, nonatomic) OFIRI *homeserver;
/**
* @brief The HTTP request method.
*
* Defaults to `OF_HTTP_REQUEST_METHOD_GET`.
*/
@property (nonatomic) OFHTTPRequestMethod method;
/**
* @brief The path of the request.
*/
@property (copy, nonatomic) OFString *path;
/**
* @brief The query items for the request.
*/
@property (copy, nullable, nonatomic)
OFArray<OFPair<OFString *, OFString *> *> *queryItems;
/**
* @brief An optional body to send along with the request.
*
* This is a dictionary that gets serialized to JSON when the request is sent.
*/
@property (copy, nullable, nonatomic) OFDictionary<OFString *, id> *body;
/**
* @brief Creates a new request with the specified access token and homeserver.
*
* @param accessToken An (optional) access token to use
* @param homeserver The homeserver the request will be sent to
* @return An autoreleased MTXRequest
*/
+ (instancetype)requestWithPath: (OFString *)path
accessToken: (nullable OFString *)accessToken
homeserver: (OFIRI *)homeserver;
/**
* @brief Initializes an already allocated request with the specified access
* token and homeserver.
*
* @param accessToken An (optional) access token to use
* @param homeserver The homeserver the request will be sent to
* @return An initialized MTXRequest
*/
- (instancetype)initWithPath: (OFString *)path
accessToken: (nullable OFString *)accessToken
homeserver: (OFIRI *)homeserver;
/**
* @brief Performs the request and calls the specified block once the request
* succeeded or failed.
*
* @param block The block to call once the request succeeded or failed
*/
- (void)performWithBlock: (MTXRequestBlock)block;
@end
OF_ASSUME_NONNULL_END