Class: Vnstat::Interface

Inherits:
Document show all
Defined in:
lib/vnstat/interface.rb

Overview

A class encapsulating traffic information for a specific network interface.

Instance Attribute Summary collapse

Attributes inherited from Document

#data

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Document

open, #version, #xml_version

Constructor Details

#initialize(id, data) ⇒ Interface

Initializes the Vnstat::Interface.

Parameters:

  • id (String) —

    The network interface identifier.

  • data (String) —

    The raw XML data.



17
18
19
20
 
# File 'lib/vnstat/interface.rb', line 17

def initialize(id, data)
  super(data)
  @id = id
end

Instance Attribute Details

#id ⇒ String (readonly)

Returns The network interface identifier.

Returns:

  • (String) —

    The network interface identifier.



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/vnstat/interface.rb', line 9

class Interface < Document
  attr_reader :id

  ##
  # Initializes the {Interface}.
  #
  # @param [String] id The network interface identifier.
  # @param [String] data The raw XML data.
  def initialize(id, data)
    super(data)
    @id = id
  end

  ##
  # Retrieves the raw XML data for the given interface identifier.
  #
  # @param [String] id The network interface identifier.
  # @return [String]
  def self.load_data(id)
    Utils.call_executable('-i', id, '--xml')
  end

  ##
  # Determines whether the interface is the same as another.
  #
  # @param [Interface] other The compared object.
  # @return [true, false]
  def ==(other)
    return false unless other.respond_to?(:id)

    id == other.id
  end

  ##
  # Refreshes data cached in the current instance.
  #
  # @return [Interface]
  def reload
    self.data = self.class.load_data(id)
    @nick = nil
    self
  end

  ##
  # Deletes the traffic database for the interface.
  #
  # @return [true, false]
  def delete
    Utils.call_executable_returning_status('--delete', '-i', id)
  end

  ##
  # Reset the internal counters in the database for the selected interface.
  # Use this if the interface goes down and back up, otherwise that interface
  # will get some extra traffic to its database. Not needed when the daemon is
  # used.
  #
  # @return [Interface]
  def reset
    reload if Utils.call_executable_returning_status('--reset', '-i', id)
    self
  end

  ##
  # Returns the alias name for the interface.
  #
  # @return [String]
  def nick
    @nick ||= interface_data.xpath('nick').text
  end

  #
  # Sets the alias name for the interface.
  #
  # @raise [Error] Raised when a new nickname could not be set.
  # @param [String] nick The alias name for the interface.
  def nick=(nick)
    success = Utils.call_executable_returning_status(
      '-i', id, '--nick', nick, '--update'
    )
    unless success
      raise Error, "Unable to set nickname for interface (#{id}). " \
                  'Please make sure the vnstat daemon is not running while ' \
                  'performing this operation.'
    end
    @nick = nick
  end

  alias name nick
  alias name= nick=

  ##
  # The date on which tracking of the interface began.
  # @return [Date]
  #
  def created_on
    Parser.extract_date_from_xml_element(interface_data.xpath('created'))
  end

  ##
  # The date and time on which the tracking information for the interface
  # were updated.
  #
  # @return [DateTime]
  def updated_at
    Parser.extract_datetime_from_xml_element(interface_data.xpath('updated'))
  end

  ##
  # Returns information about the total traffic.
  #
  # @return [Result]
  def total
    Result.extract_from_xml_element(interface_data.xpath('traffic/total'))
  end

  ##
  # Returns information about the hourly traffic.
  #
  # @return [Traffic::Hourly]
  def hours
    @hours ||= Traffic::Hourly.new(self)
  end

  ##
  # Returns information about the daily traffic.
  #
  # @return [Traffic::Daily]
  def days
    @days ||= Traffic::Daily.new(self)
  end

  ##
  # Returns information about the monthly traffic.
  #
  # @return [Traffic::Monthly]
  def months
    @months ||= Traffic::Monthly.new(self)
  end

  ##
  # Returns information about the traffic tops.
  #
  # @return [Traffic::Tops]
  def tops
    @tops ||= Traffic::Tops.new(self)
  end

  ##
  # A human readable representation of the {Interface}.
  #
  # @return [String]
  def inspect
    "#<#{self.class.name} id: #{id.inspect}>"
  end

  private

  def interface_data
    data.xpath("//interface[@id='#{id}']")
  end
end

Class Method Details

.load_data(id) ⇒ String

Retrieves the raw XML data for the given interface identifier.

Parameters:

  • id (String) —

    The network interface identifier.

Returns:

  • (String) 


27
28
29
 
# File 'lib/vnstat/interface.rb', line 27

def self.load_data(id)
  Utils.call_executable('-i', id, '--xml')
end

Instance Method Details

#==(other) ⇒ true, false

Determines whether the interface is the same as another.

Parameters:

Returns:

  • (true, false) 


36
37
38
39
40
 
# File 'lib/vnstat/interface.rb', line 36

def ==(other)
  return false unless other.respond_to?(:id)

  id == other.id
end

#created_on ⇒ Date

The date on which tracking of the interface began.

Returns:

  • (Date) 


104
105
106
 
# File 'lib/vnstat/interface.rb', line 104

def created_on
  Parser.extract_date_from_xml_element(interface_data.xpath('created'))
end

#days ⇒ Traffic::Daily

Returns information about the daily traffic.

Returns:



137
138
139
 
# File 'lib/vnstat/interface.rb', line 137

def days
  @days ||= Traffic::Daily.new(self)
end

#delete ⇒ true, false

Deletes the traffic database for the interface.

Returns:

  • (true, false) 


56
57
58
 
# File 'lib/vnstat/interface.rb', line 56

def delete
  Utils.call_executable_returning_status('--delete', '-i', id)
end

#hours ⇒ Traffic::Hourly

Returns information about the hourly traffic.

Returns:



129
130
131
 
# File 'lib/vnstat/interface.rb', line 129

def hours
  @hours ||= Traffic::Hourly.new(self)
end

#inspect ⇒ String

A human readable representation of the Vnstat::Interface.

Returns:

  • (String) 


161
162
163
 
# File 'lib/vnstat/interface.rb', line 161

def inspect
  "#<#{self.class.name} id: #{id.inspect}>"
end

#months ⇒ Traffic::Monthly

Returns information about the monthly traffic.

Returns:



145
146
147
 
# File 'lib/vnstat/interface.rb', line 145

def months
  @months ||= Traffic::Monthly.new(self)
end

#nick ⇒ String Also known as: name

Returns the alias name for the interface.

Returns:

  • (String) 


76
77
78
 
# File 'lib/vnstat/interface.rb', line 76

def nick
  @nick ||= interface_data.xpath('nick').text
end

#nick=(nick) ⇒ Object Also known as: name=

Sets the alias name for the interface.

Parameters:

  • nick (String) —

    The alias name for the interface.

Raises:

  • (Error) —

    Raised when a new nickname could not be set.



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/vnstat/interface.rb', line 85

def nick=(nick)
  success = Utils.call_executable_returning_status(
    '-i', id, '--nick', nick, '--update'
  )
  unless success
    raise Error, "Unable to set nickname for interface (#{id}). " \
                'Please make sure the vnstat daemon is not running while ' \
                'performing this operation.'
  end
  @nick = nick
end

#reload ⇒ Interface

Refreshes data cached in the current instance.

Returns:



46
47
48
49
50
 
# File 'lib/vnstat/interface.rb', line 46

def reload
  self.data = self.class.load_data(id)
  @nick = nil
  self
end

#reset ⇒ Interface

Reset the internal counters in the database for the selected interface. Use this if the interface goes down and back up, otherwise that interface will get some extra traffic to its database. Not needed when the daemon is used.

Returns:



67
68
69
70
 
# File 'lib/vnstat/interface.rb', line 67

def reset
  reload if Utils.call_executable_returning_status('--reset', '-i', id)
  self
end

#tops ⇒ Traffic::Tops

Returns information about the traffic tops.

Returns:



153
154
155
 
# File 'lib/vnstat/interface.rb', line 153

def tops
  @tops ||= Traffic::Tops.new(self)
end

#total ⇒ Result

Returns information about the total traffic.

Returns:



121
122
123
 
# File 'lib/vnstat/interface.rb', line 121

def total
  Result.extract_from_xml_element(interface_data.xpath('traffic/total'))
end

#updated_at ⇒ DateTime

The date and time on which the tracking information for the interface were updated.

Returns:

  • (DateTime) 


113
114
115
 
# File 'lib/vnstat/interface.rb', line 113

def updated_at
  Parser.extract_datetime_from_xml_element(interface_data.xpath('updated'))
end