Class: JSS::Icon

Inherits:
Object show all
Defined in:
lib/jss/api_object/self_servable/icon.rb,
lib/jss.rb

Overview

An Icon in the JSS, used in Self Service.

At the moment, icons are not API objects, they are collections of data stored in the JSS that might be included in some API object’s Self Service data.

The data available for an icon are:

  • id: the icon’s id in the JSS

  • name: the icon’s non-unique name in the JSS

  • uri: the uri to download or preview the icon

  • data: the icon file itself, base-64 encoded.

Icon instances are read-only. To change the icon for an self-servable object, see SelfServable#icon=.

NOTE: Since icons are not APIObjects, there’s no way to see a list of them via the API. The JSS::Icon class methods .all, .all_ids, and .all_names require MySQL database access. See DBConnection.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(icon_data) ⇒ JSS::Icon

Set up a new JSS::Icon instance

Parameters:

  • icon_data (Hash) —

    The :self_service_icon Hash from the :self_service Hash of an object’s API @init_data



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 123

def initialize(icon_data)
  return unless icon_data.is_a? Hash
  @id = icon_data[:id]
  @name = icon_data[:filename]
  @uri = icon_data[:uri]
  @data = icon_data[:data]

  # if no :filename, its called :name
  @name ||= icon_data[:name]

  # if there's no id, as with MobileDeviceConfigurationProfile
  # get it from the end of the uri if possible
  if @uri && !@id
    @id = Regexp.last_match(1).to_i if @uri =~ /(\d+)$/
  end

  # decode the icon data, or grab from
  # the URI if needed
  @data = Base64.decode64(@data) if @data
  @data ||= open(@uri).read if @uri

end

Instance Attribute Details

#data ⇒ String (readonly)

Returns The raw icon file.

Returns:

  • (String) —

    The raw icon file.



110
111
112
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 110

def data
  @data
end

#id ⇒ Integer (readonly)

Returns the icon’s id in the JSS.

Returns:

  • (Integer) —

    the icon’s id in the JSS



99
100
101
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 99

def id
  @id
end

#name ⇒ String (readonly) Also known as: filename

Returns the icon’s name in the JSS NOTE: these are not unique.

Returns:

  • (String) —

    the icon’s name in the JSS NOTE: these are not unique



103
104
105
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 103

def name
  @name
end

#uri ⇒ String (readonly)

Returns The URI for downloading or previewing the icon from the JSS.

Returns:

  • (String) —

    The URI for downloading or previewing the icon from the JSS



107
108
109
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 107

def uri
  @uri
end

Class Method Details

.all(refresh = false) ⇒ Array<Hash>

Return an Array of { id:, name: } Hashes for all icons known to the JSS Since Icon lists aren’t accessible via the API, this method must query the SQL database directly, and will raise an exception if you aren’t connected to the database.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    re-read the data from the server?

Returns:

  • (Array<Hash>) —

    The names and ids of all icons known to the JSS



62
63
64
65
66
67
68
69
70
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 62

def self.all(refresh = false)
  @all_icons = nil if refresh
  return @all_icons if @all_icons
  @all_icons = []
  qry = 'SELECT icon_id, filename FROM icons'
  res = JSS::DB_CNX.db.query qry
  res.each_hash { |icon| @all_icons << { id: icon['icon_id'].to_i, name: icon['filename'] } }
  @all_icons
end

.all_ids(refresh = false) ⇒ Array<Integer>

An Array of all icon ids known to the JSS. See all.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    re-read the data from the server?

Returns:

  • (Array<Integer>) —

    The ids of all icons known to the JSS



79
80
81
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 79

def self.all_ids(refresh = false)
  all(refresh).map { |i| i[:id] }
end

.all_names(refresh = false) ⇒ Array<Integer>

An Array of all icon names known to the JSS. See all. NOTE: Icon names are not unique

Parameters:

  • refresh (Boolean) (defaults to: false) —

    re-read the data from the server?

Returns:

  • (Array<Integer>) —

    The names of all icons known to the JSS



91
92
93
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 91

def self.all_names(refresh = false)
  all(refresh).map { |i| i[:name] }
end

Instance Method Details

#save(path, overwrite = false) ⇒ void

This method returns an undefined value.

Save the icon to a file.

If the path given is an existing directory, the icon’s current filename will be used, if known.

Parameters:

  • path (Pathname, String) —

    The path to which the file should be saved.

  • overwrite (Boolean) (defaults to: false) —

    Overwrite the file if it exists? Defaults to false

Raises:



168
169
170
171
172
173
174
175
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 168

def save(path, overwrite = false)
  path = Pathname.new path
  path = path + @name if path.directory? && @name

  raise JSS::AlreadyExistsError, "The file #{path} already exists" if path.exist? unless overwrite
  path.delete if path.exist?
  path.jss_save @data
end

#show_in_browser ⇒ void

This method returns an undefined value.

Open the icon’s URL in the current user’s browser



153
154
155
156
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 153

def show_in_browser
  return nil unless @uri
  system "/usr/bin/open '#{@uri}'"
end