2929#include < olp/core/http/NetworkTypes.h>
3030
3131namespace olp {
32- // / The HTTP namespace provides a platform specific network abstraction layer.
32+ // / Provides a platform specific network abstraction layer.
3333namespace http {
3434
3535/* *
36- * @brief The Network class represents HTTP client abstraction.
36+ * @brief An HTTP client abstraction.
3737 */
3838class CORE_API Network {
3939 public:
40- // / Callback to be called when the request has been processed or cancelled .
40+ // / The callback that is called when the request is processed or canceled .
4141 using Callback = std::function<void (NetworkResponse response)>;
4242
43- // / Callback to be called when a header has been received.
43+ // / The callback that is called when a header is received.
4444 using HeaderCallback =
4545 std::function<void (std::string key, std::string value)>;
4646
47- // / Callback to be called when a chunk of data has been received.
47+ // / The callback that is called when a chunk of data is received.
4848 using DataCallback = std::function<void (
4949 const std::uint8_t * data, std::uint64_t offset, std::size_t length)>;
5050
51- // / Represents the request and response payload type
51+ // / The request and response payload type.
5252 using Payload = std::shared_ptr<std::ostream>;
5353
5454 /* *
55- * @brief The Statistics structure represents the network statistics for a
56- * specific bucket.
55+ * @brief Network statistics for a specific bucket.
5756 */
5857 struct Statistics {
59- // / The total bytes downloaded including size of headers and payload.
58+ // / The total bytes downloaded, including the size of headers and payload.
6059 uint64_t bytes_downloaded{0ull };
61- // / The total bytes uploaded including size of headers and payload.
60+ // / The total bytes uploaded, including the size of headers and payload.
6261 uint64_t bytes_uploaded{0ull };
6362 // / The total number of requests made by network.
6463 uint32_t total_requests{0u };
65- // / The total number of requests failed.
64+ // / The total number of requests that failed.
6665 uint32_t total_failed{0u };
6766 };
6867
6968 virtual ~Network () = default ;
7069
7170 /* *
72- * @brief Send network request.
73- * @param[in] request Request to be sent.
74- * @param[in] payload Stream to store response payload data.
75- * @param[in] callback Callback to be called when request is fully processed
76- * or cancelled. After this call there will be no more callbacks triggered and
77- * users can consider the request as done.
78- * @param[in] header_callback Callback to be called when a HTTP header has
79- * been received. Each HTTP header entry will result in a callback.
80- * @param[in] data_callback Callback to be called when a chunk of data is
81- * received. This callback can be triggered multiple times all prior to the
82- * final Callback call.
83- * @return SendOutcome which represent either a valid \c RequestId as the
84- * unique request identifier or a \c ErrorCode in case of failure. In case of
85- * failure no callbacks will be triggered.
71+ * @brief Sends the network request.
72+ *
73+ * @param[in] request The request that is sent.
74+ * @param[in] payload The stream used to store the response payload data.
75+ * @param[in] callback The callback that is called when the request is fully
76+ * processed or canceled. After this call, no more callbacks are triggered,
77+ * and you can consider the request as done.
78+ * @param[in] header_callback The callback that is called when an HTTP header
79+ * is received. Each HTTP header entry results in a callback.
80+ * @param[in] data_callback The callback that is called when a chunk of data
81+ * is received. You can trigger triggered multiple times before the final
82+ * `Callback` call.
83+ *
84+ * @return `SendOutcome` that represent either a valid `RequestId` as
85+ * the unique request identifier or an `ErrorCode` in case of failure.
86+ * In case of failure, no callbacks are triggered.
8687 */
8788 virtual SendOutcome Send (NetworkRequest request, Payload payload,
8889 Callback callback,
8990 HeaderCallback header_callback = nullptr ,
9091 DataCallback data_callback = nullptr ) = 0;
9192
9293 /* *
93- * @brief Cancel request by RequestId.
94- * Once the request was cancelled the user will receive a final Callback with
95- * an appropriate NetworkResponse marked as cancelled.
96- * @param[in] id The unique RequestId of the request to be cancelled.
94+ * @brief Cancels the request using `RequestId`.
95+ *
96+ * When the request is canceled, the user receives a final `Callback` with
97+ * an appropriate `NetworkResponse` marked as canceled.
98+ *
99+ * @param[in] id The unique ID of the request that you want to cancel.
97100 */
98101 virtual void Cancel (RequestId id) = 0;
99102
100103 /* *
101- * @brief Sets default network headers.
104+ * @brief Sets the default network headers.
102105 *
103106 * Default headers are applied to each request passed to the `Send` method.
104107 * User agents are concatenated.
@@ -108,26 +111,27 @@ class CORE_API Network {
108111 virtual void SetDefaultHeaders (Headers headers);
109112
110113 /* *
111- * @brief Set the current statistics bucket.
114+ * @brief Sets the current bucket statistics .
112115 *
113116 * @param[in] bucked_id The bucket ID.
114117 */
115118 virtual void SetCurrentBucket (uint8_t bucket_id);
116119
117120 /* *
118- * @brief Get the statistics for a bucket.
121+ * @brief Gets the statistics for a bucket.
119122 *
120- * By default, this returns the statistics for the default bucket, with the ID 0.
123+ * By default, it returns the statistics for the default bucket and the ID
124+ * that equals 0.
121125 *
122126 * @param[in] bucked_id The bucket ID.
123127 *
124- * @return Statistics which contains the statistic for the requested bucket.
128+ * @return The statistic for the requested bucket.
125129 */
126130 virtual Statistics GetStatistics (uint8_t bucket_id = 0 );
127131};
128132
129133/* *
130- * @brief Create default Network implementation.
134+ * @brief Creates a default ` Network` implementation.
131135 */
132136CORE_API std::shared_ptr<Network> CreateDefaultNetwork (
133137 size_t max_requests_count);
0 commit comments