libfswatch  1.9.3
Classes | Typedefs | Enumerations | Functions
cevent.h File Reference

Event type manipulation. More...

#include <time.h>
#include <limits.h>
#include "libfswatch_types.h"

Go to the source code of this file.

Classes

struct  fsw_cevent
 

Typedefs

typedef struct fsw_cevent fsw_cevent
 
typedef void(* FSW_CEVENT_CALLBACK) (fsw_cevent const *const events, const unsigned int event_num, void *data)
 

Enumerations

enum  fsw_event_flag {
  NoOp = 0, PlatformSpecific = (1 << 0), Created = (1 << 1), Updated = (1 << 2),
  Removed = (1 << 3), Renamed = (1 << 4), OwnerModified = (1 << 5), AttributeModified = (1 << 6),
  MovedFrom = (1 << 7), MovedTo = (1 << 8), IsFile = (1 << 9), IsDir = (1 << 10),
  IsSymLink = (1 << 11), Link = (1 << 12), Overflow = (1 << 13)
}
 Backend-agnostic change flags. More...
 

Functions

FSW_STATUS fsw_get_event_flag_by_name (const char *name, enum fsw_event_flag *flag)
 Get event flag by name. More...
 
char * fsw_get_event_flag_name (const enum fsw_event_flag flag)
 Get the name of an event flag. More...
 

Detailed Description

Event type manipulation.

This header file defines the event types of the libfswatch API.

License:
GNU General Public License v. 3.0
Author
Enrico M. Crisostomo
Version
1.8.0

Typedef Documentation

typedef struct fsw_cevent fsw_cevent

A file change event is represented as an instance of this struct where:

  • path is the path where the event was triggered.
  • evt_time the time when the event was triggered.
  • flags is an array of fsw_event_flag of size flags_num.
  • flags_num is the size of the flags array.
typedef void(* FSW_CEVENT_CALLBACK) (fsw_cevent const *const events, const unsigned int event_num, void *data)

A function pointer of type FSW_CEVENT_CALLBACK is used by the API as a callback to provide information about received events. The callback is passed the following arguments:

  • events, a const pointer to an array of events of type const fsw_cevent.
  • event_num, the size of the *events array.
  • data, optional persisted data for a callback.

The memory used by the fsw_cevent objects will be freed at the end of the callback invocation. A callback should copy such data instead of storing a pointer to it.

Enumeration Type Documentation

Backend-agnostic change flags.

Each element of this enum represents a backend-agnostic change flag. No direct mapping to backend-specific change types is guaranteed to exist: a change type may be mapped to multiple fsw_event_flag instances included the PlatformSpecific flag.

The values of event flags are all powers of 2, that is numbers $f=2^n$ where $n$ is an integer. This representation makes it easy to combine flags into a bit mask and encode multiple events flags into a single integer.

A monitor implementation is required to map implementation-specific flags into API flags. Sometimes, though, a perfect match is not possible and the following situation may arise:

  • One platform-specific flag must be mapped into multiple API flags.
  • Multiple platform-specific flags must be mapped into a single API flag.
  • A mapping is not possible for some flags, in which case they should be mapped to fsw_event_flag::PlatformSpecific. The API currently offers no way to retain a platform-specific event flag value in this case.
Enumerator
NoOp 

No event has occurred.

PlatformSpecific 

Platform-specific placeholder for event type that cannot currently be mapped.

Created 

An object was created.

Updated 

An object was updated.

Removed 

An object was removed.

Renamed 

An object was renamed.

OwnerModified 

The owner of an object was modified.

AttributeModified 

The attributes of an object were modified.

MovedFrom 

An object was moved from this location.

MovedTo 

An object was moved to this location.

IsFile 

The object is a file.

IsDir 

The object is a directory.

IsSymLink 

The object is a symbolic link.

Link 

The link count of an object has changed.

Overflow 

The event queue has overflowed.

Function Documentation

FSW_STATUS fsw_get_event_flag_by_name ( const char *  name,
enum fsw_event_flag flag 
)

Get event flag by name.

This function looks for an event flag called name and, if it exists, it writes its value onto flag and FSW_OK, otherwise flag is not modified and FSW_ERR_UNKNOWN_VALUE is returned.

Parameters
[in]nameThe name of the event flag to look for.
[out]flagThe output variable where the event flag is returned.
Returns
FSW_OK if the functions succeeds, FSW_ERR_UNKNOWN_VALUE otherwise.
char* fsw_get_event_flag_name ( const enum fsw_event_flag  flag)

Get the name of an event flag.

This function looks for the name of the specified event flag. If it exists, it returns its name, otherwise nullptr is returned.

Parameters
[in]flagThe event flag to look for.
Returns
The name of flag, or nullptr if it does not exist.