Main libfswatch source file. More...

#include "gettext_defs.h"
#include <iostream>
#include <mutex>
#include <atomic>
#include <ctime>
#include <cstdlib>
#include <cstring>
#include <memory>
#include <vector>
#include <map>
#include "libfswatch.h"
#include "../c++/libfswatch_map.hpp"
#include "../c++/filter.hpp"
#include "../c++/monitor.hpp"
#include "../c++/libfswatch_exception.hpp"

Classes
struct	FSW_SESSION

struct	fsw_callback_context

class	monitor_start_guard< T >

Macros
#define	SESSION_GUARD std::lock_guard<std::mutex> session_lock(session_mutex);

Typedefs
typedef struct FSW_SESSION	FSW_SESSION

typedef struct fsw_callback_context	fsw_callback_context

Functions
static FSW_SESSION *	get_session (const FSW_HANDLE handle)

static int	create_monitor (FSW_HANDLE handle, const fsw_monitor_type type)

static FSW_STATUS	fsw_set_last_error (const int error)

FSW_STATUS	fsw_init_library ()

void	libfsw_cpp_callback_proxy (const std::vector< event > &events, void *context_ptr)

FSW_HANDLE	fsw_init_session (const fsw_monitor_type type)

FSW_STATUS	fsw_add_path (const FSW_HANDLE handle, const char *path)

FSW_STATUS	fsw_add_property (const FSW_HANDLE handle, const char name, const char value)

FSW_STATUS	fsw_set_callback (const FSW_HANDLE handle, const FSW_CEVENT_CALLBACK callback, void *data)

FSW_STATUS	fsw_set_allow_overflow (const FSW_HANDLE handle, const bool allow_overflow)

FSW_STATUS	fsw_set_latency (const FSW_HANDLE handle, const double latency)

FSW_STATUS	fsw_set_recursive (const FSW_HANDLE handle, const bool recursive)

FSW_STATUS	fsw_set_directory_only (const FSW_HANDLE handle, const bool directory_only)

FSW_STATUS	fsw_set_follow_symlinks (const FSW_HANDLE handle, const bool follow_symlinks)

FSW_STATUS	fsw_add_event_type_filter (const FSW_HANDLE handle, const fsw_event_type_filter event_type)

FSW_STATUS	fsw_add_filter (const FSW_HANDLE handle, const fsw_cmonitor_filter filter)

FSW_STATUS	fsw_start_monitor (const FSW_HANDLE handle)

FSW_STATUS	fsw_destroy_session (const FSW_HANDLE handle)

FSW_STATUS	fsw_last_error ()

bool	fsw_is_verbose ()

void	fsw_set_verbose (bool verbose)

Variables
static bool	srand_initialized = false

static bool	fsw_libfswatch_verbose = false

static fsw_hash_map< FSW_HANDLE, FSW_SESSION * >	sessions

static fsw_hash_map< FSW_HANDLE, mutex * >	session_mutexes

static std::mutex	session_mutex

static FSW_THREAD_LOCAL FSW_STATUS	last_error

static FSW_EVENT_CALLBACK	libfsw_cpp_callback_proxy

Detailed Description

Main libfswatch source file.

Copyright: Copyright (c) 2014-2015 Enrico M. Crisostomo

License:: GNU General Public License v. 3.0

Author: Enrico M. Crisostomo

Version: 1.8.0

Function Documentation

FSW_STATUS fsw_add_event_type_filter	(	const FSW_HANDLE	handle,
		const fsw_event_type_filter	event_type
	)

Adds an event type filter to the current session.

See cfilter.h for the definition of fsw_event_type_filter.

FSW_STATUS fsw_add_filter	(	const FSW_HANDLE	handle,
		const fsw_cmonitor_filter	filter
	)

Adds a filter to the current session. A filter is a regular expression that, depending on whether the filter type is exclusion or not, must or must not be matched for an event path for the event to be accepted.

See cfilter.h for the definition of fsw_cmonitor_filter.

FSW_STATUS fsw_add_path	(	const FSW_HANDLE	handle,
		const char *	path
	)

Adds a path to watch to the specified session. At least one path must be added to the current session in order for it to be valid.

FSW_STATUS fsw_add_property	(	const FSW_HANDLE	handle,
		const char *	name,
		const char *	value
	)

Adds the specified monitor property.

FSW_STATUS fsw_destroy_session ( const FSW_HANDLE handle )

Destroys an existing session and invalidates its handle.

FSW_STATUS fsw_init_library ( )

The libfswatch C API let users create monitor sessions and receive file system events matching the specified criteria. Most API functions return a status code of type FSW_STATUS which can take any value specified in the error.h header. A successful API call returns FSW_OK and the last error can be obtained calling the fsw_last_error() function.

If the compiler and the C++ library used to build libfswatch support the thread_local storage specified then this API is thread safe and a different state is maintained on a per-thread basis.

Session-modifying API calls (such as fsw_add_path) will take effect the next time a monitor is started with fsw_start_monitor.

Currently not all monitors supports being stopped, in which case fsw_start_monitor is a non-returning API call.

A basic session needs at least:

A path to watch.
A callback to process the events sent by the monitor.

as shown in the next example (error checking code was omitted).

// Use the default monitor.
const FSW_HANDLE handle = fsw_init_session(system_default_monitor_type);

fsw_add_path(handle, "my/path");
fsw_set_callback(handle, my_callback);

fsw_start_monitor(handle);

A suitable callback function is a function pointer of type FSW_CEVENT_CALLBACK, that is it is a function conforming with the following signature:

void c_process_events(fsw_cevent const * const events,
                      const unsigned int event_num,
                      void * data);

When a monitor receives change events satisfying all the session criteria, the callback is invoked and passed a copy of the events. This function initializes the libfswatch library and must be invoked before any other calls to the C or C++ API. If the function succeeds, it returns FSW_OK, otherwise the initialization routine failed and the library should not be usable.

FSW_HANDLE fsw_init_session ( const enum fsw_monitor_type type )

This function creates a new monitor session using the specified monitor and returns an handle to it. This function is the libfswatch API entry point.

See also: cmonitor.h for a list of all the available monitors.

bool fsw_is_verbose ( )

Check whether the verbose mode is active.

FSW_STATUS fsw_last_error ( )

Gets the last error code.

FSW_STATUS fsw_set_allow_overflow	(	const FSW_HANDLE	handle,
		const bool	allow_overflow
	)

Sets the allow overflow flag of the monitor. When this flag is set, a monitor is allowed to overflow and report it as a change event.

FSW_STATUS fsw_set_callback	(	const FSW_HANDLE	handle,
		const FSW_CEVENT_CALLBACK	callback,
		void *	data
	)

Sets the callback the monitor invokes when some events are received. The callback must be set in the current session in order for it to be valid.

See cevent.h for the definition of FSW_CEVENT_CALLBACK.

FSW_STATUS fsw_set_directory_only	(	const FSW_HANDLE	handle,
		const bool	directory_only
	)

Determines whether the monitor only watches a directory when performing a recursive scan. By default, a monitor accepts all kinds of files.

FSW_STATUS fsw_set_follow_symlinks	(	const FSW_HANDLE	handle,
		const bool	follow_symlinks
	)

Determines whether a symbolic link is followed or not. By default, a symbolic link are not followed.

FSW_STATUS fsw_set_latency	(	const FSW_HANDLE	handle,
		const double	latency
	)

Sets the latency of the monitor. By default, the latency is set to 1 s.

FSW_STATUS fsw_set_recursive	(	const FSW_HANDLE	handle,
		const bool	recursive
	)

Determines whether the monitor recursively scans each watched path or not. Recursive scanning is an optional feature which could not be implemented by all the monitors. By default, recursive scanning is disabled.

void fsw_set_verbose ( bool verbose )

Set the verbose mode.

FSW_STATUS fsw_start_monitor ( const FSW_HANDLE handle )

Starts the monitor if it is properly configured. Depending on the type of monitor this call might return when a monitor is stopped or not.

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Function Documentation