Class: Jamf::Icon

Inherits:
Object show all
Defined in:
lib/jamf/api/classic/api_objects/icon.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 Jamf::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) ⇒ Jamf::Icon

Set up a new Jamf::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
 
# File 'lib/jamf/api/classic/api_objects/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
  @id = Regexp.last_match(1).to_i if @uri && !@id && @uri =~ (/(\d+)$/)

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



116
117
118
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 116

def data
  @data
end

#id ⇒ Integer (readonly)

Returns the icon’s id in the JSS.

Returns:

  • (Integer) —

    the icon’s id in the JSS



105
106
107
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 105

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



109
110
111
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 109

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



113
114
115
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 113

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
76
 
# File 'lib/jamf/api/classic/api_objects/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 = Jamf::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



85
86
87
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 85

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



97
98
99
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 97

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/jamf/api/classic/api_objects/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:



176
177
178
179
180
181
182
183
184
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 176

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

  raise Jamf::AlreadyExistsError, "The file #{path} already exists" if !overwrite && path.exist?

  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



160
161
162
163
164
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 160

def show_in_browser
  return nil unless @uri

  system "/usr/bin/open '#{@uri}'"
end