Class: CF::Preferences

Inherits:
Object
  • Object
show all
Defined in:
lib/corefoundation/preferences.rb

Overview

Interface to the preference utilities from Corefoundation.framework. Documentation at developer.apple.com/documentation/corefoundation/preferences_utilities

Constant Summary collapse

CURRENT_USER = 
CF.kCFPreferencesCurrentUser
ALL_USERS = 
CF.kCFPreferencesAnyUser
CURRENT_HOST = 
CF.kCFPreferencesCurrentHost
ALL_HOSTS = 
CF.kCFPreferencesAnyHost

Class Method Summary collapse

Class Method Details

.get(key, application_id, username = nil, hostname = nil) ⇒ VALUE

Returns the output from ‘CFPreferencesCopyValue` call after converting it to ruby type.

Parameters:

  • key (String) —

    Preference key to read

  • application_id (String) —

    Preference domain for the key

  • username (String, Symbol) (defaults to: nil) —

    Domain user (current, any or a specific user)

  • hostname (String, Symbol) (defaults to: nil) —

    Hostname (current, all hosts or a specific host)

Returns:

  • (VALUE) —

    Preference value returned from the ‘CFPreferencesCopyValue` call.



43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/corefoundation/preferences.rb', line 43

def get(key, application_id, username = nil, hostname = nil)
  plist_ref = if username && hostname
                CF.CFPreferencesCopyValue(
                  key.to_cf,
                  application_id.to_cf,
                  arg_to_cf(username),
                  arg_to_cf(hostname)
                )
              else
                CF.CFPreferencesCopyAppValue(key.to_cf, application_id.to_cf)
              end
  CF::Base.typecast(plist_ref).to_ruby unless plist_ref.null?
end

.get!(key, application_id, username = nil, hostname = nil) ⇒ VALUE

Calls the CF::Preferences#self#self.get method and raise a ‘PreferenceDoesNotExist` error if `nil` is returned.

Parameters:

  • key (String) —

    Preference key to read

  • application_id (String) —

    Preference domain for the key

  • username (String, Symbol) (defaults to: nil) —

    Domain user (current, any or a specific user)

  • hostname (String, Symbol) (defaults to: nil) —

    Hostname (current, all hosts or a specific host)

Returns:

  • (VALUE) —

    Preference value returned from the CF::Preferences#self#self.get method call.

Raises:

  • (PreferenceDoesNotExist) —

    If returned value is nil.



68
69
70
71
72
73
74
75
 
# File 'lib/corefoundation/preferences.rb', line 68

def get!(key, application_id, username = nil, hostname = nil)
  value = get(key, application_id, username, hostname)
  if value.nil?
    raise(CF::Exceptions::PreferenceDoesNotExist.new(key, application_id, hostname))
  else
    value
  end
end

.set(key, value, application_id, username = nil, hostname = nil) ⇒ TrueClass, FalseClass

Set the value for preference domain using ‘CFPreferencesSetValue`.

Parameters:

  • key (String) —

    Preference key

  • value (Integer, Float, String, TrueClass, FalseClass, Hash, Array) —

    Preference value

  • application_id (String) —

    Preference domain

  • username (String, Symbol) (defaults to: nil) —

    Domain user (current, any or a specific user)

  • hostname (String, Symbol) (defaults to: nil) —

    Hostname (current, all hosts or a specific host)

Returns:

  • (TrueClass, FalseClass) —

    Returns true if preference was successfully written to storage, otherwise false.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/corefoundation/preferences.rb', line 87

def set(key, value, application_id, username = nil, hostname = nil)
  if username && hostname
    CF.CFPreferencesSetValue(
      key.to_cf,
      arg_to_cf(value),
      application_id.to_cf,
      arg_to_cf(username),
      arg_to_cf(hostname)
    )
  else
    CF.CFPreferencesSetAppValue(
      key.to_cf,
      arg_to_cf(value),
      application_id.to_cf
    )
  end
  CF.CFPreferencesAppSynchronize(application_id.to_cf)
end

.set!(key, value, application_id, username = nil, hostname = nil) ⇒ VALUE

Calls the CF::Preferences#self#self.set method and raise a ‘PreferenceSyncFailed` error if `false` is returned.

Parameters:

  • key (String) —

    Preference key to write

  • application_id (String) —

    Preference domain for the key

  • username (String, Symbol) (defaults to: nil) —

    Domain user (current, any or a specific user)

  • hostname (String, Symbol) (defaults to: nil) —

    Hostname (current, all hosts or a specific host)

Returns:

  • (VALUE) —

    Returns nil if preference value is successfully written.

Raises:

  • (PreferenceSyncFailed) —

    If CF::Preferences#self#self.set call returned false.



117
118
119
 
# File 'lib/corefoundation/preferences.rb', line 117

def set!(key, value, application_id, username = nil, hostname = nil)
  raise(CF::Exceptions::PreferenceSyncFailed.new(key, application_id, hostname)) unless set(key, value, application_id, username, hostname)
end