ruby-jss 0.7.0 → 0.8.1

data/lib/jss/api_object/self_servable/icon.rb

@@ -0,0 +1,179 @@
+### Copyright 2017 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+###
+module JSS
+
+    # 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 {JSS::DBConnection}.
+    #
+    class Icon
+
+      #  Class Methods
+      #####################################
+
+      # 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.
+      #
+      # @param refresh[Boolean] re-read the data from the server?
+      #
+      # @return [Array<Hash>] The names and ids of all icons known to the JSS
+      #
+      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
+
+      # An Array of all icon ids known to the JSS.
+      # See {Icon.all}.
+      #
+      # @param refresh[Boolean] re-read the data from the server?
+      #
+      # @return [Array<Integer>] The ids of all icons known to the JSS
+      #
+      def self.all_ids(refresh = false)
+        all(refresh).map { |i| i[:id] }
+      end
+
+      # An Array of all icon names known to the JSS.
+      # See {Icon.all}.
+      # NOTE: Icon names are not unique
+      #
+      # @param refresh[Boolean] re-read the data from the server?
+      #
+      # @return [Array<Integer>] The names of all icons known to the JSS
+      #
+      def self.all_names(refresh = false)
+        all(refresh).map { |i| i[:name] }
+      end
+
+      #  Attributes
+      #####################################
+
+      # @return [Integer] the icon's id in the JSS
+      attr_reader :id
+
+      # @return [String] the icon's name in the JSS
+      #   NOTE: these are not unique
+      attr_reader :name
+      alias filename name
+
+      # @return [String] The URI for downloading or previewing the icon from the JSS
+      attr_reader :uri
+
+      # @return [String] The raw icon file.
+      attr_reader :data
+
+
+      #  Constructor
+      #####################################
+
+      # Set up a new JSS::Icon instance
+      #
+      # @param icon_data[Hash] The :self_service_icon Hash from the :self_service
+      #   Hash of an object's API @init_data
+      #
+      # @return [JSS::Icon] The new object
+      #
+      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 Methods
+      #####################################
+
+      # Open the icon's URL in the current user's browser
+      #
+      # @return [void]
+      #
+      def show_in_browser
+        return nil unless @uri
+        system "/usr/bin/open '#{@uri}'"
+      end
+
+      # Save the icon to a file.
+      #
+      # @param path[Pathname, String] The path to which the file should be saved.
+      # If the path given is an existing directory, the icon's current filename will
+      # be used, if known.
+      #
+      # @param overwrite[Boolean] Overwrite the file if it exists? Defaults to false
+      #
+      # @return [void]
+      #
+      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
+
+    end # class icon
+
+end # module

data/lib/jss/api_object/updatable.rb

@@ -26,54 +26,54 @@
 ### A mix-in module providing object-updating via the JSS API.
 module JSS
 
-  ### Module Variables
+  # Module Variables
   #####################################
 
-  ### Module Methods
+  # Module Methods
   #####################################
 
-  ### Sub-Modules
+  # Sub-Modules
   #####################################
 
-  ### A mix-in module that allows objects to be updated in the JSS via the API.
-  ###
-  ### When a JSS::APIObject subclass includes this module, instances of that
-  ### subclass can be modified in the JSS using the {#update} or {APIObject#save} methods.
-  ###
-  ### Such classes should define setter methods for any values that they wish to
-  ### modify, such as the {#name=} method defined here. Those setter methods must:
-  ### - ensure the correctness of the data they accept.
-  ### - set @need_to_update to true, indicating that the local object no longer
-  ###   matches the JSS, and the changes should be pushed to the server with {#update}
-  ###
-  ### Classes mixing this module *must* provide a #rest_xml instance method that returns the XML
-  ### String to be submitted to the API for object updating.
-  ###
-  ### @see APIObject#save
-  ###
+  # A mix-in module that allows objects to be updated in the JSS via the API.
+  #
+  # When a JSS::APIObject subclass includes this module, instances of that
+  # subclass can be modified in the JSS using the {#update} or {APIObject#save} methods.
+  #
+  # Such classes should define setter methods for any values that they wish to
+  # modify, such as the {#name=} method defined here. Those setter methods must:
+  # - ensure the validity of the data they accept.
+  # - set @need_to_update to true, indicating that the local object no longer
+  #   matches the JSS, and the changes should be pushed to the server with {#update}
+  #
+  # Classes mixing this module *must* provide a #rest_xml instance method that returns the XML
+  # String to be submitted to the API for object updating.
+  #
+  # @see_also APIObject#save
+  #
   module Updatable
 
-    ###  Constants
+    #  Constants
     #####################################
 
     UPDATABLE = true
 
-    ###  Attributes
+    #  Attributes
     #####################################
 
-    ### @return [Boolean] do we have unsaved changes?
+    # @return [Boolean] do we have unsaved changes?
     attr_reader :need_to_update
 
-    ###  Mixed-in Instance Methods
+    #  Mixed-in Instance Methods
     #####################################
 
-    ### Change the name of this item
-    ### Remember to #update to push changes to the server.
-    ###
-    ### @param newname[String] the new name
-    ###
-    ### @return [void]
-    ###
+    # Change the name of this item
+    # Remember to #update to push changes to the server.
+    #
+    # @param newname[String] the new name
+    #
+    # @return [void]
+    #
     def name=(newname)
       return nil if @name == newname
       raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
@@ -85,16 +85,17 @@ module JSS
       @need_to_update = true
     end #  name=(newname)
 
-    ### Save changes to the JSS
-    ###
-    ### @return [Boolean] success
-    ###
+    # Save changes to the JSS
+    #
+    # @return [Boolean] success
+    #
     def update
       return nil unless @need_to_update
       raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
       raise JSS::NoSuchItemError, "Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY} in the JSS before updating it." unless @in_jss
       JSS::API.put_rsrc @rest_rsrc, rest_xml
       @need_to_update = false
+      refresh_icon if self_servable?
       @id
     end # update
 

data/lib/jss/api_object/uploadable.rb

@@ -27,107 +27,109 @@
 module JSS
 
   #####################################
-  ### Module Variables
+  # Module Variables
   #####################################
 
   #####################################
-  ### Module Methods
+  # Module Methods
   #####################################
 
   #####################################
-  ### Sub-Modules
+  # Sub-Modules
   #####################################
 
-  ###
-  ### A mixin module providing file-upload capabilities to JSSAPIObject subclasses.
-  ###
-  ### Classes mixing in this module are required to define a constant UPLOAD_TYPES
-  ### which is a Hash of :type => :resource pairs, like this:
-  ###
-  ###  UPLOAD_TYPES = {
-  ###     :icon => :mobiledeviceapplicationsicon
-  ###     :app => mobiledeviceapplicationsipa
-  ###     :attachment => mobiledeviceapplications
-  ###   }
-  ###
-  ### with one pair for each type of upload that the class can handle.
-  ### (most of them only handle one, usually :attachment)
-  ###
-  ### When the #upload method is called, one of the keys from that Hash must be specified
-  ###
-  ### Classes with only one upload type may want to redefine #upload to always call super with
-  ### that one type.
-  ###
-  ### ----
-  ###
-  ### Implementation Notes from
-  ### https://casperserver:8443/api/index.htm#!/fileuploads/uploadFiles_post
-  ###
-  ###   POST ...JSSResource/fileuploads/<resource>/<idType>/<id>
-  ###
-  ### You can POST different types of files by entering parameters for <resource>, <idType>, and <id>.
-  ### For example /JSSResource/fileuploads/computers/id/2.
-  ###
-  ### Attachments can be uploaded by specifying computers, mobiledevices, enrollmentprofiles, or
-  ### peripherals as the resource.
-  ###
-  ### Icons can be uploaded by specifying policies, ebooks, or mobiledeviceapplicationsicon as the resource.
-  ###
-  ### A mobile device application can be uploaded by using mobiledeviceapplicationsipa as the resource.
-  ###
-  ### A disk encryption can be uploaded by specifying diskencryptionconfigurations as the resource.
-  ###
-  ### idTypes supported are "id" and "name", although peripheral names are not supported.
-  ###
-  ### A sample command is:
-  ###   curl -k -u user:password https://my.jss:8443/JSSResource/fileuploads/computers/id/2 -F name=@/Users/admin/Documents/Sample.doc -X POST
-  ###
-  ###
-  ###
-  ###
+  #
+  # A mixin module providing file-upload capabilities to JSSAPIObject subclasses.
+  #
+  # Classes mixing in this module are required to define a constant UPLOAD_TYPES
+  # which is a Hash of :type => :resource pairs, like this:
+  #
+  #  UPLOAD_TYPES = {
+  #     :icon => :mobiledeviceapplicationsicon
+  #     :app => mobiledeviceapplicationsipa
+  #     :attachment => mobiledeviceapplications
+  #   }
+  #
+  # with one pair for each type of upload that the class can handle.
+  # (most of them only handle one, usually :attachment)
+  #
+  # When the #upload method is called, one of the keys from that Hash must be specified
+  #
+  # Classes with only one upload type may want to redefine #upload to always call super with
+  # that one type.
+  #
+  # ----
+  #
+  # Implementation Notes from
+  # https://casperserver:8443/api/index.htm#!/fileuploads/uploadFiles_post
+  #
+  #   POST ...JSSResource/fileuploads/<resource>/<idType>/<id>
+  #
+  # You can POST different types of files by entering parameters for <resource>, <idType>, and <id>.
+  # For example /JSSResource/fileuploads/computers/id/2.
+  #
+  # Attachments can be uploaded by specifying computers, mobiledevices, enrollmentprofiles, or
+  # peripherals as the resource.
+  #
+  # Icons can be uploaded by specifying policies, ebooks, or mobiledeviceapplicationsicon as the resource.
+  #
+  # A mobile device application can be uploaded by using mobiledeviceapplicationsipa as the resource.
+  #
+  # A disk encryption can be uploaded by specifying diskencryptionconfigurations as the resource.
+  #
+  # idTypes supported are "id" and "name", although peripheral names are not supported.
+  #
+  # A sample command is:
+  #   curl -k -u user:password https://my.jss:8443/JSSResource/fileuploads/computers/id/2 -F name=@/Users/admin/Documents/Sample.doc -X POST
+  #
+  #
+  #
+  #
   module Uploadable
 
     #####################################
-    ###  Constants
+    #  Constants
     #####################################
 
+    UPLOADABLE = true
+
     UPLOAD_RSRC_PREFIX = 'fileuploads'.freeze
 
     #####################################
-    ###  Variables
+    #  Variables
     #####################################
 
     #####################################
-    ###  Methods
+    #  Methods
     #####################################
 
-    ###
-    ### Upload a file to the JSS via the REST Resource of the
-    ### object to which this module is mixed in.
-    ###
-    ### @param type[Symbol] the type of upload happening.
-    ###   Must be one of the keys defined in the class's UPLOAD_TYPES Hash.
-    ###
-    ### @param local_file[String, Pathname] String or Pathname pointing to the
-    ###   locally-readable file to be uploaded.
-    ###
-    ### @return [String] The xml response from the server.
-    ###
+    #
+    # Upload a file to the JSS via the REST Resource of the
+    # object to which this module is mixed in.
+    #
+    # @param type[Symbol] the type of upload happening.
+    #   Must be one of the keys defined in the class's UPLOAD_TYPES Hash.
+    #
+    # @param local_file[String, Pathname] String or Pathname pointing to the
+    #   locally-readable file to be uploaded.
+    #
+    # @return [String] The xml response from the server.
+    #
     def upload(type, local_file)
-      ### the thing's gotta be in the JSS, and have an @id
+      # the thing's gotta be in the JSS, and have an @id
       raise JSS::NoSuchItemError, 'Create this #{self.class::RSRC_OBJECT_KEY} in the JSS before uploading files to it.' unless @id && @in_jss
 
-      ### the type has to be defined in the class of self.
+      # the type has to be defined in the class of self.
       raise JSS::InvalidDataError, "#{self.class::RSRC_LIST_KEY} only take uploads of type: :#{self.class::UPLOAD_TYPES.keys.join(', :')}." \
         unless self.class::UPLOAD_TYPES.keys.include? type
 
-      ### figure out the resource after the UPLOAD_RSRC_PREFIX
+      # figure out the resource after the UPLOAD_RSRC_PREFIX
       upload_rsrc = "#{UPLOAD_RSRC_PREFIX}/#{self.class::UPLOAD_TYPES[type]}/id/#{@id}"
 
-      ### make a File object to hand to REST. 'rb' = read,binary
+      # make a File object to hand to REST. 'rb' = read,binary
       file = File.new local_file.to_s, 'rb'
 
-      ### upload it!
+      # upload it!
       JSS::API.cnx[upload_rsrc].post name: file
     end # def upload file