API.md (2835B)
1 ## SFSClient 2 3 To start using the SFSClient library, use `SFSClient::Make()` to create an `SFSClient` instance, which allows you to use the SFS APIs. 4 The first argument to the factory is a `ClientConfig` struct. Configuring this struct allows you to customize the behavior of the client. 5 Refer to the documentation of the `ClientConfig` struct in [ClientConfig.h](client/include/sfsclient/ClientConfig.h) to see the available options. 6 7 ## Logging Callback 8 9 To retrieve logging information from the API, set a logging callback in `ClientConfig::logCallbackFn` when constructing an SFSClient instance with `SFSClient::Make()`. 10 11 The logging callback function has the signature: 12 13 ```cpp 14 void callback(const SFS::LogData&); 15 ``` 16 17 An example to log the data directly to the standard output using `std::cout`: 18 19 ```cpp 20 void LoggingCallback(const SFS::LogData& logData) 21 { 22 std::cout << "Log: [" << ToString(logData.severity) << "]" << " " << logData.file << ":" 23 << logData.line << " " << logData.message << std::endl; 24 } 25 ``` 26 27 Notes: 28 - The callback itself is processed in the main thread. Do not use a blocking callback. If heavy processing has to be done, consider capturing the data and processing another thread. 29 - The LogData contents only exist within the callback call. If the processing will be done later, you should copy the data elsewhere. 30 - The callback should not do any re-entrant calls (e.g. call `SFSClient` methods). 31 32 ## Class instances 33 34 It is recommended to only create a single `SFSClient` instance, even if multiple threads will be used. 35 Each `GetLatestDownloadInfo()` call will create its own connection and should not interfere with other calls. 36 37 ### Thread safety 38 39 All API calls are thread-safe. 40 41 If a logging callback is set in a multi-threaded environment, and the same `SFSClient()` is reused across different threads, the same callback will be called by all usages of the class. So, make sure the callback itself is also thread-safe. 42 43 ## Content types 44 45 A few data types are provided which abstract contents that can be sent by the SFS Service, such as `Content`, `ContentId`, `File`. 46 These data types provide `noexcept` methods to interact with member data. 47 48 ## Retry Behavior 49 50 The API follows a certain set of rules to retry upon reaching specific HTTP Status Codes. The behavior is configurable through the `retryOnError` member of `RequestParams`. 51 52 By default, the client will retry up to 3 times when reaching the following HTTP Status Codes: 53 - 429: Too Many Requests 54 - 500: Internal Server Error 55 - 502: Bad Gateway 56 - 503: Server Busy 57 - 504: Gateway Timeout 58 59 Between each retry the Client will wait an interval that follows either the `Retry-After` response header, or an exponential backoff calculation with a factor of 2 starting from 15s.