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



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 110

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.



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

def data
  @data
end

#id ⇒ Integer (readonly)

Returns the icon’s id in the JSS.

Returns:

  • (Integer) —

    the icon’s id in the JSS



87
88
89
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 87

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



91
92
93
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 91

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



95
96
97
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 95

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



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 49

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



67
68
69
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 67

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



79
80
81
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 79

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



174
175
176
177
178
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 174

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:



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

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



142
143
144
145
146
 
# File 'lib/jamf/api/classic/api_objects/icon.rb', line 142

def show_in_browser
  return nil unless @uri

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