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 a 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.

This also means, if you use multiple API connections, you'll have to make sure to connect to the correct MySQL server for the APIConnection you care about.

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



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
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 128

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
  begin
    @data ||= URI.parse(@uri).read if @uri
  rescue
    @data = nil
  end

end

Instance Attribute Details

#data ⇒ String (readonly)

Returns The raw icon file.

Returns:

  • (String) —

    The raw icon file.



115
116
117
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 115

def data
  @data
end

#id ⇒ Integer (readonly)

Returns the icon's id in the JSS.

Returns:

  • (Integer) —

    the icon's id in the JSS



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

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



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

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



112
113
114
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 112

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



67
68
69
70
71
72
73
74
75
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 67

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



84
85
86
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 84

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



96
97
98
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 96

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

Instance Method Details

#pretty_print_instance_variables ⇒ Array

Remove the data object from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables



192
193
194
195
196
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 192

def pretty_print_instance_variables
  vars = instance_variables.sort
  vars.delete :@data
  vars
end

#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:



177
178
179
180
181
182
183
184
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 177

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



162
163
164
165
 
# File 'lib/jss/api_object/self_servable/icon.rb', line 162

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