diff --git a/src/uvw/fs_event.hpp b/src/uvw/fs_event.hpp index 3c908cdf..16903388 100644 --- a/src/uvw/fs_event.hpp +++ b/src/uvw/fs_event.hpp @@ -32,12 +32,36 @@ enum class UVFsEvent: std::underlying_type_t { } +/** + * @brief FsEventEvent event. + * + * It will be emitted by the FsEventHandle according with its functionalities. + */ struct FsEventEvent: Event { FsEventEvent(std::string fPath, Flags f) : flgs{std::move(f)}, relPath{std::move(fPath)} { } + /** + * @brief Gets the path to the file being monitored. + * + * If the handle was started with a directory, the filename parameter will + * be a relative path to a file contained in the directory. + * + * @return The path to the file being monitored. + */ const char * filename() const noexcept { return relPath.data(); } + + /** + * @brief Gets the detected events. + * + * Available flags are: + * + * * FsEventHandle::Watch::RENAME + * * FsEventHandle::Watch::CHANGE + * + * @return Detected events all in one. + */ Flags flags() const noexcept { return flgs; } private: @@ -46,6 +70,17 @@ private: }; +/** + * @brief The FsEventHandle handle. + * + * These handles allow the user to monitor a given path for changes, for + * example, if the file was renamed or there was a generic change in it. The + * best backend for the job on each platform is chosen by the handle. + * + * See the official + * [documentation](http://docs.libuv.org/en/v1.x/fs_event.html) + * for further details. + */ class FsEventHandle final: public Handle { static void startCallback(uv_fs_event_t *handle, const char *filename, int events, int status) { FsEventHandle &fsEvent = *(static_cast(handle->data)); @@ -59,23 +94,77 @@ public: using Watch = details::UVFsEvent; using Event = details::UVFsEventFlags; + /** + * @brief Creates a new fs event handle. + * @param args A pointer to the loop from which the handle generated. + * @return A pointer to the newly created handle. + */ template static std::shared_ptr create(Args&&... args) { return std::shared_ptr{new FsEventHandle{std::forward(args)...}}; } + /** + * @brief Initializes the handle. + * @return True in case of success, false otherwise. + */ bool init() { return initialize(&uv_fs_event_init); } + /** + * @brief Starts watching the specified path. + * + * It will watch the specified path for changes.
+ * As soon as a change is observed, a FsEventEvent is emitted by the + * handle.
+ * It could happen that ErrorEvent events are emitted while running. + * + * Available flags are: + * + * * FsEventHandle::Event::WATCH_ENTRY + * * FsEventHandle::Event::STAT + * * FsEventHandle::Event::RECURSIVE + * + * @param path The file or directory to be monitored. + * @param flags Additional flags to control the behavior. + */ void start(std::string path, Flags flags = Flags{}) { invoke(&uv_fs_event_start, get(), &startCallback, path.data(), flags); } + /** + * @brief Starts watching the specified path. + * + * It will watch the specified path for changes.
+ * As soon as a change is observed, a FsEventEvent is emitted by the + * handle.
+ * It could happen that ErrorEvent events are emitted while running. + * + * Available flags are: + * + * * FsEventHandle::Event::WATCH_ENTRY + * * FsEventHandle::Event::STAT + * * FsEventHandle::Event::RECURSIVE + * + * @param path The file or directory to be monitored. + * @param watch Additional flag to control the behavior. + */ + void start(std::string path, Watch watch) { + start(std::move(path), Flags{watch}); + } + + /** + * @brief Stops polling the file descriptor. + */ void stop() { invoke(&uv_fs_event_stop, get()); } + /** + * @brief Gets the path being monitored. + * @return The path being monitored. + */ std::string path() noexcept { return details::path(&uv_fs_event_getpath, get()); }