watch_database.h

Go to the documentation of this file.

#ifndef WATCH_DATABASE_H
#define WATCH_DATABASE_H

/*****************************************************************************/
/******************************** Documentation ******************************/
/*****************************************************************************/

/**
 * \file
 * Public interface for using the watch database persistent store.
 */

/*****************************************************************************/
/******************************* Include Files *******************************/
/*****************************************************************************/

/*****************************************************************************/
/*********************************** Defines *********************************/
/*****************************************************************************/

/**
 * Base error code (minimum value) for watch database errors
 */
#define WATCH_DATABASE_ERROR_BASE -3500
/**
 * Maximum error code for watch database errors
 */
#define WATCH_DATABASE_ERROR_LIMIT (WATCH_DATABASE_ERROR_BASE + 50)
/**
 * Return true if error code is within the range for watch database errors.
 *
 * \param[in] error The error code to test if it's a watch database error code.
 * \return    True if error code is a watch database error.
 */
#define IS_WATCH_DATABASE_ERROR(error)  (((error) >= WATCH_DATABASE_ERROR_BASE) && ((error) < WATCH_DATABASE_ERROR_LIMIT))

#define WATCH_DATABASE_ERROR_CANNOT_OPEN          (WATCH_DATABASE_ERROR_BASE + 1) /**< could not open database */
#define WATCH_DATABASE_ERROR_CANNOT_CLOSE         (WATCH_DATABASE_ERROR_BASE + 2) /**< could not close database */
#define WATCH_DATABASE_ERROR_CANNOT_QUERY         (WATCH_DATABASE_ERROR_BASE + 3) /**< database query failed */
#define WATCH_DATABASE_ERROR_CANNOT_CREATE_TABLE  (WATCH_DATABASE_ERROR_BASE + 4) /**< cannot create table */
#define WATCH_DATABASE_ERROR_CANNOT_INSERT        (WATCH_DATABASE_ERROR_BASE + 5) /**< cannot insert record into table */
#define WATCH_DATABASE_ERROR_NOT_FOUND            (WATCH_DATABASE_ERROR_BASE + 6) /**< entry not found */
#define WATCH_DATABASE_ERROR_FOUND_MULTIPLE       (WATCH_DATABASE_ERROR_BASE + 7) /**< found multiple entries, expecting single entry */

/**
 * The path name of the SQLite database used for lwatch.
 */
#define WATCH_DATABASE_PATHNAME DATABASEDIR "/" PACKAGE_NAME ".db"
/**
 * The name of the table where we persistently store lwatch_path_info_t data.
 */
#define LWATCH_TABLE_NAME "lwatch"

/**
 * Update the flags to indicate this path is a watch target.
 */
#define PATH_INFO_FLAG_SET_TARGET(path_info)    \
{                                               \
    (path_info)->flags |=  TARGET_FLAG;         \
    (path_info)->flags &= ~BACKUP_FLAG;         \
}

/**
 * Update the flags to indicate this path is a backup of a watch target.
 */
#define PATH_INFO_FLAG_SET_BACKUP(path_info)                    \
{                                                               \
    (path_info)->flags |=  BACKUP_FLAG;                         \
    (path_info)->flags &= ~(TARGET_FLAG | INC_VERSION_FLAG);    \
}

/**
 * Update the flags to indicate this path needs to have it's version number
 * incremented the next time. This occurs when we detect a file has had it's
 * contents replaced and is now a new file, hence it will have a higher
 * version number.
 */
#define PATH_INFO_FLAG_SET_INC_VERSION(path_info)       \
{                                                       \
    if (!((path_info)->flags & BACKUP_FLAG))            \
        (path_info)->flags |= INC_VERSION_FLAG;         \
}

/**
 * Update the flags to indicate this file has been lost and from this point
 * forward we need to consider any reference to this file will represent new
 * contents for the file.
 */
#define PATH_INFO_FLAG_SET_NEW_FILE(path_info)                          \
{                                                                       \
    PATH_INFO_FLAG_SET_INC_VERSION(path_info);                          \
    (path_info)->flags &= ~(STAT_DATA_VALID_FLAG | NEEDS_REAPING_FLAG); \
}

/*****************************************************************************/
/******************************* Type Definitions ****************************/
/*****************************************************************************/

/**
 * Boolean flags used to indicate path_info state.
 */
typedef enum {
    TARGET_FLAG             = 0x0001, /**< true if this path is a primary watch target */
    BACKUP_FLAG             = 0x0002, /**< true if this path is backup of a primary watch target */
    NEEDS_REAPING_FLAG      = 0x0004, /**< true if contents of this file needs to be collected (e.g. reaped) */
    STAT_DATA_VALID_FLAG    = 0x0008, /**< true if stat information is valid */
    INC_VERSION_FLAG        = 0x0010, /**< true if we need to increment the version number on the primary watch
                                           target because the file was replaced */
} path_info_flags_t;

/**
 * struct which mirrors one row from the watch database.
 */
struct lwatch_path_info_t {
    char   path[PATH_MAX];          /**< path name */
    char   original_path[PATH_MAX]; /**< if this is a backup (rotated) file this is
                                         the path name it was derived from */
    unsigned long flags;            /**< path_info_flags_t boolean flags used to indicate state */
    unsigned long version;          /**< each time file is recreated this number incremented */
    time_t reap_time;               /**< time when file contents last reaped (collected) */
    off_t  reap_position;           /**< file position where next reap should begin */
    dev_t  dev;                     /**< device number */
    ino_t  inode;                   /**< inode number */
    mode_t mode;                    /**< file mode bit set */
    uid_t  uid;                     /**< user ID of owner */
    gid_t  gid;                     /**< group ID of owner */
    off_t  size;                    /**< total size, in bytes */
    time_t access_time;             /**< time of last access (e.g.: read) */
    time_t modification_time;       /**< time of last modification (file contents modified) */
    time_t change_time;             /**< time of last change (file contents modified) */
};

struct database_iter_context_t;
 /**
  * Pointer to function returning pointer to lwatch_path_info_t
  */
typedef struct lwatch_path_info_t *(*database_iter_next_t)(struct database_iter_context_t *iter);
/**
 * Iteration context used to iterate over a set of lwatch_path_info_t structs
 * returned by a watch database query.
 *
 * Example:
 * \code
 * struct database_iter_context_t *path_iter;
 * struct lwatch_path_info_t *path_info;
 *
 * if ((error = database_query_all_paths_iter(&path_iter, NULL)) != SUCCESS) {
 *     // handle error
 *  }
 *
 * while ((path_info = path_iter->next(path_iter))) {
 *     // use path_info
 * }
 * \endcode
 */
struct database_iter_context_t {
    database_iter_next_t next; /**< pointer to function returning pointer to lwatch_path_info_t */
    int error;                 /**< error code from query */
};

/*****************************************************************************/
/*************************  External Global Variables  ***********************/
/*****************************************************************************/

/*****************************************************************************/
/****************************  Exported Functions  ***************************/
/*****************************************************************************/

int init_path_info(struct lwatch_path_info_t *path_info, const char *path);
int new_path_info(const char *path, struct lwatch_path_info_t **path_info_arg);
char *path_info_flags_string(unsigned long flag, const char *separator);
char *path_info_string(struct lwatch_path_info_t *path_info, const char *prefix);
int watch_database_init(void);
int watch_database_fini(void);
const char *watch_database_error_string(int error);
int database_lookup_path_info(const char *path, struct lwatch_path_info_t *path_info);
int database_write_path_info(struct lwatch_path_info_t *path_info);
int database_query_all_paths_iter(struct database_iter_context_t **iter_arg, const char *path_filter_arg);
int database_query_backups_iter(struct database_iter_context_t **iter_arg);
int database_query_backups_of_target_iter(struct database_iter_context_t **iter_arg, const char *path);
int database_query_pending_reaps_iter(struct database_iter_context_t **iter_arg);
int database_query_targets_iter(struct database_iter_context_t **iter_arg);

#endif

---