Skip to content

Commit 8b68122

Browse files
marinofaggianamarinofaggiana
committed
async
Signed-off-by: Marino Faggiana <marino@marinofaggiana.com>
1 parent dced9a8 commit 8b68122

9 files changed

Lines changed: 797 additions & 290 deletions

‎Sources/NextcloudKit/NextcloudKit+API.swift‎

Lines changed: 95 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,14 @@ public class NKNotifications: NSObject {
3131
}
3232

3333
public extension NextcloudKit {
34+
// Checks if the specified server URL is reachable and returns the raw HTTP response.
35+
// Used to verify the availability and responsiveness of a Nextcloud server.
36+
//
37+
// Parameters:
38+
// - serverUrl: Full URL of the Nextcloud server to check.
39+
// - options: Optional request options (e.g. custom headers, queue).
40+
// - taskHandler: Closure to access the URLSessionTask (default is no-op).
41+
// - completion: Completion handler with the raw HTTP response and any NKError.
3442
func checkServer(serverUrl: String,
3543
options: NKRequestOptions = NKRequestOptions(),
3644
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in },
@@ -50,24 +58,43 @@ public extension NextcloudKit {
5058
}
5159
}
5260

53-
/// Asynchronously checks the server status using the provided URL and request options.
61+
/// Asynchronously checks the specified server URL and returns the HTTP response and error.
5462
/// - Parameters:
5563
/// - serverUrl: The URL of the server to check.
56-
/// - options: Optional request options (default: `NKRequestOptions()`).
57-
/// - taskHandler: Optional closure to receive the `URLSessionTask` (default: no-op).
58-
/// - Returns: A tuple containing the optional `AFDataResponse<Data>` and an `NKError`.
64+
/// - options: Optional request options.
65+
/// - taskHandler: Optional closure to access the session task.
66+
/// - Returns: A tuple containing the raw response and NKError, with named values.
5967
func checkServerAsync(serverUrl: String,
6068
options: NKRequestOptions = NKRequestOptions(),
61-
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }) async -> (AFDataResponse<Data>?, NKError) {
69+
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }
70+
) async -> (
71+
responseData: AFDataResponse<Data>?,
72+
error: NKError
73+
) {
6274
await withCheckedContinuation { continuation in
63-
checkServer(serverUrl: serverUrl, options: options, taskHandler: taskHandler) { responseData, error in
64-
continuation.resume(returning: (responseData, error))
75+
checkServer(serverUrl: serverUrl,
76+
options: options,
77+
taskHandler: taskHandler) { responseData, error in
78+
continuation.resume(returning: (
79+
responseData: responseData,
80+
error: error
81+
))
6582
}
6683
}
6784
}
6885

6986
// MARK: -
7087

88+
// Executes a generic HTTP request using the given relative endpoint path and HTTP method.
89+
// Commonly used for flexible OCS or WebDAV API calls without dedicated wrappers.
90+
//
91+
// Parameters:
92+
// - endpoint: The relative API path (e.g. "ocs/v2.php/apps/...") to be appended to the base server URL.
93+
// - account: The Nextcloud account initiating the request.
94+
// - method: The HTTP method as a string ("GET", "POST", "DELETE", etc).
95+
// - options: Optional request options such as custom headers, versioning, queue.
96+
// - taskHandler: Optional closure to access the underlying URLSessionTask.
97+
// - completion: Completion handler returning the account, raw response, and any NKError.
7198
func generalWithEndpoint(_ endpoint: String,
7299
account: String,
73100
method: String,
@@ -92,32 +119,49 @@ public extension NextcloudKit {
92119
}
93120
}
94121

95-
/// Asynchronously executes a general network request with the specified endpoint and method.
122+
/// Asynchronously performs a generic request using the specified endpoint and method.
96123
/// - Parameters:
97-
/// - endpoint: The endpoint to call (e.g., "/ocs/v2.php/apps/...").
98-
/// - account: The identifier for the user/account associated with the request.
99-
/// - method: The HTTP method (e.g., "GET", "POST").
100-
/// - options: Optional request options (default: `NKRequestOptions()`).
101-
/// - taskHandler: Optional closure to access the `URLSessionTask`.
102-
/// - Returns: A tuple containing the account, the optional response, and the `NKError`.
124+
/// - endpoint: Relative path to the server API.
125+
/// - account: The account initiating the request.
126+
/// - method: HTTP method string.
127+
/// - options: Optional request configuration.
128+
/// - taskHandler: Closure to access the URLSessionTask.
129+
/// - Returns: A tuple with named values: account, raw response, and error.
103130
func generalWithEndpointAsync(_ endpoint: String,
104131
account: String,
105132
method: String,
106133
options: NKRequestOptions = NKRequestOptions(),
107-
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }) async -> (String, AFDataResponse<Data>?, NKError) {
134+
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }
135+
) async -> (
136+
account: String,
137+
responseData: AFDataResponse<Data>?,
138+
error: NKError
139+
) {
108140
await withCheckedContinuation { continuation in
109141
generalWithEndpoint(endpoint,
110142
account: account,
111143
method: method,
112144
options: options,
113145
taskHandler: taskHandler) { account, responseData, error in
114-
continuation.resume(returning: (account, responseData, error))
146+
continuation.resume(returning: (
147+
account: account,
148+
responseData: responseData,
149+
error: error
150+
))
115151
}
116152
}
117153
}
118154

119155
// MARK: -
120156

157+
// Retrieves the list of external sites configured in the Nextcloud instance.
158+
// These are typically links to external services or resources displayed in the web UI.
159+
//
160+
// Parameters:
161+
// - account: The Nextcloud account making the request.
162+
// - options: Optional request options for custom headers, versioning, queue, etc.
163+
// - taskHandler: Closure to access the URLSessionTask (default is no-op).
164+
// - completion: Completion handler returning the account, list of external sites, response, and any NKError.
121165
func getExternalSite(account: String,
122166
options: NKRequestOptions = NKRequestOptions(),
123167
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in },
@@ -156,20 +200,31 @@ public extension NextcloudKit {
156200
}
157201
}
158202

159-
/// Asynchronously retrieves external sites for the given account.
203+
/// Asynchronously retrieves the list of external sites for the specified account.
160204
/// - Parameters:
161-
/// - account: The identifier for the account.
162-
/// - options: Optional request options (default: `NKRequestOptions()`).
163-
/// - taskHandler: Optional closure to access the `URLSessionTask`.
164-
/// - Returns: A tuple with account identifier, external sites list, response data, and NKError.
205+
/// - account: The Nextcloud account making the request.
206+
/// - options: Optional request configuration.
207+
/// - taskHandler: Closure to access the URLSessionTask.
208+
/// - Returns: A tuple containing account, external sites array, raw response, and error.
165209
func getExternalSiteAsync(account: String,
166210
options: NKRequestOptions = NKRequestOptions(),
167-
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }) async -> (String, [NKExternalSite], AFDataResponse<Data>?, NKError) {
211+
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }
212+
) async -> (
213+
account: String,
214+
externalSite: [NKExternalSite],
215+
responseData: AFDataResponse<Data>?,
216+
error: NKError
217+
) {
168218
await withCheckedContinuation { continuation in
169219
getExternalSite(account: account,
170220
options: options,
171221
taskHandler: taskHandler) { account, externalSite, responseData, error in
172-
continuation.resume(returning: (account, externalSite, responseData, error))
222+
continuation.resume(returning: (
223+
account: account,
224+
externalSite: externalSite,
225+
responseData: responseData,
226+
error: error
227+
))
173228
}
174229
}
175230
}
@@ -381,7 +436,15 @@ public extension NextcloudKit {
381436
mimeFallback: Int = 0,
382437
account: String,
383438
options: NKRequestOptions = NKRequestOptions(),
384-
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }) async -> (String, Int, Int, String?, AFDataResponse<Data>?, NKError) {
439+
taskHandler: @escaping (_ task: URLSessionTask) -> Void = { _ in }
440+
) async -> (
441+
account: String,
442+
width: Int,
443+
height: Int,
444+
etag: String?,
445+
responseData: AFDataResponse<Data>?,
446+
error: NKError
447+
) {
385448
await withCheckedContinuation { continuation in
386449
downloadPreview(fileId: fileId,
387450
width: width,
@@ -394,11 +457,17 @@ public extension NextcloudKit {
394457
account: account,
395458
options: options,
396459
taskHandler: taskHandler) { account, w, h, tag, responseData, error in
397-
continuation.resume(returning: (account, w, h, tag, responseData, error))
460+
continuation.resume(returning: (
461+
account: account,
462+
width: w,
463+
height: h,
464+
etag: tag,
465+
responseData: responseData,
466+
error: error
467+
))
398468
}
399469
}
400470
}
401-
402471
func downloadTrashPreview(fileId: String,
403472
width: Int = 512,
404473
height: Int = 512,

0 commit comments

Comments
 (0)