Subversion Repositories public

/// inotify C++ interface header

/**

 * \file inotify-cxx.h

 *

 * inotify C++ interface

 *

 * Copyright (C) 2006 Lukas Jelinek, <lukas@aiken.cz>

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of one of the following licenses:

 *

 * \li 1. X11-style license (see LICENSE-X11)

 * \li 2. GNU Lesser General Public License, version 2.1 (see LICENSE-LGPL)

 * \li 3. GNU General Public License, version 2  (see LICENSE-GPL)

 *

 * If you want to help with choosing the best license for you,

 * please visit http://www.gnu.org/licenses/license-list.html.

 *

 */

#ifndef _INOTIFYCXX_H_

#define _INOTIFYCXX_H_

#include <string>

#include <deque>

#include <map>

// Please ensure that the following headers take the right place.

#include <sys/inotify.h>

#include <sys/inotify-syscalls.h>

/// Event struct size

#define INOTIFY_EVENT_SIZE (sizeof(struct inotify_event))

/// Event buffer length

#define INOTIFY_BUFLEN (1024 * (INOTIFY_EVENT_SIZE + 16))

// forward declaration

class InotifyWatch;

class Inotify;

/// inotify event class

/**

 * It holds all information about inotify event and provides

 * access to its particular values.

 */

class InotifyEvent

{

public:

  /// Constructor.

  /**

   * Creates a plain event.

   */

  InotifyEvent()

  {

    memset(&m_evt, 0, sizeof(m_evt));

    m_evt.wd = (int32_t) -1;

    m_pWatch = NULL;

  }

  /// Constructor.

  /**

   * Creates an event based on inotify event data.

   * For NULL pointers it works the same way as InotifyEvent().

   *

   * \param[in] pEvt event data

   * \param[in] pWatch inotify watch

   */

  InotifyEvent(const struct inotify_event* pEvt, InotifyWatch* pWatch)

  {

    if (pEvt != NULL) {

      memcpy(&m_evt, pEvt, sizeof(m_evt));

      if (pEvt->name != NULL)

        m_name = pEvt->name;

      m_pWatch = pWatch;

    }

    else {

      memset(&m_evt, 0, sizeof(m_evt));

      m_evt.wd = (int32_t) -1;

      m_pWatch = NULL;

    }

  }

  /// Destructor.

  ~InotifyEvent() {}

  /// Returns the event watch descriptor.

  /**

   * \return watch descriptor

   *

   * \sa InotifyWatch::GetDescriptor()

   */

  inline int32_t GetDescriptor() const

  {

    return (int32_t) m_evt.wd;

  }

  /// Returns the event mask.

  /**

   * \return event mask

   *

   * \sa InotifyWatch::GetMask()

   */

  inline uint32_t GetMask() const

  {

    return (uint32_t) m_evt.mask;

  }

  /// Checks a value for the event type.

  /**

   * \param[in] uValue checked value

   * \param[in] uType type which is checked for

   * \return true = the value contains the given type, false = otherwise

   */

  inline static bool IsType(uint32_t uValue, uint32_t uType)

  {

    return ((uValue & uType) != 0) && ((~uValue & uType) == 0);

  }

  /// Checks for the event type.

  /**

   * \param[in] uType type which is checked for

   * \return true = event mask contains the given type, false = otherwise

   */

  inline bool IsType(uint32_t uType) const

  {

    return IsType((uint32_t) m_evt.mask, uType);

  }

  /// Returns the event cookie.

  /**

   * \return event cookie

   */

  inline uint32_t GetCookie() const

  {

    return (uint32_t) m_evt.cookie;

  }

  /// Returns the event name length.

  /**

   * \return event name length

   */

  inline uint32_t GetLength() const

  {

    return (uint32_t) m_evt.len;

  }

  /// Returns the event name.

  /**

   * \return event name

   */

  inline const std::string& GetName() const

  {

    return m_name;

  }

  /// Extracts the event name.

  /**

   * \param[out] rName event name

   */

  inline void GetName(std::string& rName) const

  {

    rName = GetName();

  }

  /// Returns the source watch.

  /**

   * \return source watch

   */

  inline InotifyWatch* GetWatch()

  {

    return m_pWatch;

  }

  /// Returns the event raw data.

  /**

   * For NULL pointer it does nothing.

   *

   * \param[in,out] pEvt event data

   */

  inline void GetData(struct inotify_event* pEvt)

  {

    if (pEvt != NULL)

      memcpy(pEvt, &m_evt, sizeof(m_evt));

  }

  /// Returns the event raw data.

  /**

   * \param[in,out] rEvt event data

   */

  inline void GetData(struct inotify_event& rEvt)

  {

    memcpy(&rEvt, &m_evt, sizeof(m_evt));

  }

  /// Finds the appropriate mask for a name.

  /**

   * \param[in] rName mask name

   * \return mask for name; 0 on failure

   */

  static uint32_t GetMaskByName(const std::string& rName);

  /// Fills the string with all types contained in an event mask value.

  /**

   * \param[in] uValue event mask value

   * \param[out] rStr dumped event types

   */

  static void DumpTypes(uint32_t uValue, std::string& rStr);

  /// Fills the string with all types contained in the event mask.

  /**

   * \param[out] rStr dumped event types

   */

  void DumpTypes(std::string& rStr) const;

private:

  struct inotify_event m_evt; ///< event structure

  std::string m_name;         ///< event name

  InotifyWatch* m_pWatch;     ///< source watch

};

/// inotify watch class

class InotifyWatch

{

public:

  /// Constructor.

  /**

   * Creates an inotify watch. Because this watch is

   * inactive it has an invalid descriptor (-1).

   *

   * \param[in] rPath watched file path

   * \param[in] uMask mask for events

   */

  InotifyWatch(const std::string& rPath, int32_t uMask)

  {

    m_path = rPath;

    m_uMask = uMask;

    m_wd = (int32_t) -1;

  }

  /// Destructor.

  ~InotifyWatch() {}

  /// Returns the watch descriptor.

  /**

   * \return watch descriptor; -1 for inactive watch

   */

  inline int32_t GetDescriptor() const

  {

    return m_wd;

  }

  /// Returns the watched file path.

  /**

   * \return file path

   */

  inline const std::string& GetPath() const

  {

    return m_path;

  }

  /// Returns the watch event mask.

  /**

   * \return event mask

   */

  inline uint32_t GetMask() const

  {

    return (uint32_t) m_uMask;

  }

  /// Returns the appropriate inotify class instance.

  /**

   * \return inotify instance

   */

  inline Inotify* GetInotify()

  {

    return m_pInotify;

  }

private:

  friend class Inotify;

  std::string m_path;   ///< watched file path

  uint32_t m_uMask;     ///< event mask

  int32_t m_wd;         ///< watch descriptor

  Inotify* m_pInotify;  ///< inotify object

};

/// Mapping from watch descriptors to watch objects.

typedef std::map<int32_t, InotifyWatch*> IN_WATCH_MAP;

/// inotify class

class Inotify

{

public:

  /// Constructor.

  /**

   * Creates and initializes an instance of inotify communication

   * object (opens the inotify device).

   */

  Inotify();

  /// Destructor.

  /**

   * Calls Close() due for clean-up.

   */

  ~Inotify();

  /// Removes all watches and closes the inotify device.

  void Close();

  /// Checks whether the inotify is ready.

  /**

   * \return true = initialized properly, false = something failed

   */

  inline bool IsReady() const

  {

    return m_fd != -1;

  }

  /// Adds a new watch.

  /**

   * \param[in] pWatch inotify watch

   * \return true = success, false = failure

   */

  bool Add(InotifyWatch* pWatch);

  /// Adds a new watch.

  /**

   * \param[in] rWatch inotify watch

   * \return true = success, false = failure

   */

  inline bool Add(InotifyWatch& rWatch)

  {

    return Add(&rWatch);

  }

  /// Removes a watch.

  /**

   * If the given watch is not present it does nothing.

   *

   * \param[in] pWatch inotify watch

   */

  void Remove(InotifyWatch* pWatch);

  /// Removes a watch.

  /**

   * If the given watch is not present it does nothing.

   *

   * \param[in] rWatch inotify watch

   */

  inline void Remove(InotifyWatch& rWatch)

  {

    Remove(&rWatch);

  }

  /// Removes all watches.

  void RemoveAll();

  /// Returns the count of watches.

  /**

   * \return count of watches

   */

  inline size_t GetWatchCount() const

  {

    return (size_t) m_watches.size();

  }

  /// Waits for inotify events.

  /**

   * It waits until one or more events occur.

   *

   * \param[in] fNoIntr if true it re-calls the system call after a handled signal

   * \return true = event(s) occurred, false = failure

   */

  bool WaitForEvents(bool fNoIntr = false);

  /// Returns the count of received and queued events.

  /**

   * This number is related to the events in the queue inside

   * this object, not to the events pending in the kernel.

   *

   * \return count of events

   */

  int GetEventCount();

  /// Extracts a queued inotify event.

  /**

   * The extracted event is removed from the queue.

   * If the pointer is NULL it does nothing.

   *

   * \param[in,out] pEvt event object

   * \return true = success, false = failure

   */

  bool GetEvent(InotifyEvent* pEvt);

  /// Extracts a queued inotify event.

  /**

   * The extracted event is removed from the queue.

   *

   * \param[in,out] rEvt event object

   * \return true = success, false = failure

   */

  bool GetEvent(InotifyEvent& rEvt)

  {

    return GetEvent(&rEvt);

  }

  /// Extracts a queued inotify event (without removing).

  /**

   * The extracted event stays in the queue.

   * If the pointer is NULL it does nothing.

   *

   * \param[in,out] pEvt event object

   * \return true = success, false = failure

   */

  bool PeekEvent(InotifyEvent* pEvt);

  /// Extracts a queued inotify event (without removing).

  /**

   * The extracted event stays in the queue.

   *

   * \param[in,out] rEvt event object

   * \return true = success, false = failure

   */

  bool PeekEvent(InotifyEvent& rEvt)

  {

    return PeekEvent(&rEvt);

  }

  /// Searches for a watch.

  /**

   * It tries to find a watch by the given descriptor.

   *

   * \param[in] iDescriptor watch descriptor

   * \return found descriptor; NULL if no such watch exists

   */

  InotifyWatch* FindWatch(int iDescriptor);  

private:

  int m_fd;                             ///< file descriptor

  IN_WATCH_MAP m_watches;               ///< watches

  unsigned char m_buf[INOTIFY_BUFLEN];  ///< buffer for events

  std::deque<InotifyEvent> m_events;    ///< event queue

};

#endif //_INOTIFYCXX_H_