Struct SCPreferences 

pub struct SCPreferences { /* private fields */ }

Available on crate feature SCPreferences only.

This is the handle to an open preferences session for accessing system configuration preferences.

See also Apple’s documentation

Implementations

impl SCPreferences

pub fn new( allocator: Option<&CFAllocator>, name: &CFString, prefs_id: Option<&CFString>, ) -> Option<CFRetained<SCPreferences>>

Initiates access to the per-system set of configuration preferences.

Parameter allocator: The CFAllocator that should be used to allocate memory for this preferences session. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter name: A string that describes the name of the calling process.

Parameter prefsID: A string that identifies the name of the group of preferences to be accessed or updated.

Returns: Returns a reference to the new SCPreferences. You must release the returned value.

pub unsafe fn with_authorization( allocator: Option<&CFAllocator>, name: &CFString, prefs_id: Option<&CFString>, authorization: AuthorizationRef, ) -> Option<CFRetained<SCPreferences>>

Available on crate feature objc2-security only.

Initiates access to the per-system set of configuration preferences.

Parameter allocator: The CFAllocator that should be used to allocate memory for this preferences session. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter name: A string that describes the name of the calling process.

Parameter prefsID: A string that identifies the name of the group of preferences to be accessed or updated.

Parameter authorization: An authorization reference that is used to authorize any access to the enhanced privileges needed to manage the preferences session.

Returns: Returns a reference to the new SCPreferences. You must release the returned value.

Safety

authorization must be a valid pointer or null.

pub fn lock(&self, wait: bool) -> bool

Locks access to the configuration preferences.

This function obtains exclusive access to the configuration preferences. Clients attempting to obtain exclusive access to the preferences will either receive a kSCStatusPrefsBusy error or block waiting for the lock to be released.

Parameter prefs: The preferences session.

Parameter wait: A boolean flag indicating whether the calling process should block waiting for another process to complete its update operation and release its lock.

Returns: Returns TRUE if the lock was obtained; FALSE if an error occurred.

pub fn commit_changes(&self) -> bool

Commits changes made to the configuration preferences to persistent storage.

This function commits any changes to permanent storage. Implicit calls to the SCPreferencesLock and SCPreferencesUnlock functions will be made if exclusive access has not already been established.

Note: This routine commits changes to persistent storage. Call the SCPreferencesApplyChanges function to apply the changes to the running system.

Parameter prefs: The preferences session.

Returns: Returns TRUE if the lock was obtained; FALSE if an error occurred.

pub fn apply_changes(&self) -> bool

Requests that the currently stored configuration preferences be applied to the active configuration.

Parameter prefs: The preferences session.

Returns: Returns TRUE if the lock was obtained; FALSE if an error occurred.

pub fn unlock(&self) -> bool

Releases exclusive access to the configuration preferences.

This function releases the exclusive access lock to the preferences. Other clients will be now be able to establish exclusive access to the preferences.

Parameter prefs: The preferences session.

Returns: Returns TRUE if the lock was obtained; FALSE if an error occurred.

pub fn signature(&self) -> Option<CFRetained<CFData>>

Returns a sequence of bytes that can be used to determine if the saved configuration preferences have changed.

Parameter prefs: The preferences session.

Returns: Returns a CFDataRef that reflects the signature of the configuration preferences at the time of the call to the SCPreferencesCreate function.

pub fn key_list(&self) -> Option<CFRetained<CFArray>>

Returns an array of currently defined preference keys.

Parameter prefs: The preferences session.

Returns: Returns the list of keys. You must release the returned value.

pub fn value(&self, key: &CFString) -> Option<CFRetained<CFPropertyList>>

Returns the data associated with a preference key.

This function retrieves data associated with the specified key.

Note: To avoid inadvertantly reading stale data, first call the SCPreferencesLock function.

Parameter prefs: The preferences session.

Parameter key: The preference key to be returned.

Returns: Returns the value associated with the specified preference key; NULL if no value was located.

pub unsafe fn add_value(&self, key: &CFString, value: &CFPropertyList) -> bool

Adds data for a preference key.

This function associates new data with the specified key. To commit these changes to permanent storage, a call must be made to the SCPreferencesCommitChanges function.

Parameter prefs: The preferences session.

Parameter key: The preference key to be updated.

Parameter value: The CFPropertyListRef object containing the value to be associated with the specified preference key.

Returns: Returns TRUE if the value was added; FALSE if the key already exists or if an error occurred.

Safety

value should be of the correct type.

pub unsafe fn set_value(&self, key: &CFString, value: &CFPropertyList) -> bool

Updates the data associated with a preference key.

This function adds or replaces the value associated with the specified key. To commit these changes to permanent storage a call must be made to the SCPreferencesCommitChanges function.

Parameter prefs: The preferences session.

Parameter key: The preference key to be updated.

Parameter value: The CFPropertyListRef object containing the data to be associated with the specified preference key.

Returns: Returns TRUE if the value was set; FALSE if an error occurred.

Safety

value should be of the correct type.

pub fn remove_value(&self, key: &CFString) -> bool

Removes the data associated with a preference key.

This function removes the data associated with the specified key. To commit these changes to permanent storage a call must be made to the SCPreferencesCommitChanges function.

Parameter prefs: The preferences session.

Parameter key: The preference key to be removed.

Returns: Returns TRUE if the value was removed; FALSE if the key did not exist or if an error occurred.

pub unsafe fn set_callback( &self, callout: SCPreferencesCallBack, context: *mut SCPreferencesContext, ) -> bool

Assigns a callback to a preferences session. The function is called when the changes to the preferences have been committed or applied.

Parameter prefs: The preferences session.

Parameter callout: The function to be called when the preferences have been changed or applied. If NULL, the current callback is removed.

Parameter context: The SCPreferencesContext associated with the callout.

Returns: Returns TRUE if the notification client was successfully set.

Safety

• callout must be implemented correctly.
• context must be a valid pointer or null.

pub fn schedule_with_run_loop( &self, run_loop: &CFRunLoop, run_loop_mode: &CFString, ) -> bool

Schedule commit and apply notifications for the specified preferences session using the specified run loop and mode.

Parameter prefs: The preferences session.

Parameter runLoop: A reference to a run loop on which the notification should be scheduled. Must be non-NULL.

Parameter runLoopMode: The mode on which to schedule the notification. Must be non-NULL.

Returns: Returns TRUE if the notifications are successfully scheduled; FALSE otherwise.

pub fn unschedule_from_run_loop( &self, run_loop: &CFRunLoop, run_loop_mode: &CFString, ) -> bool

Unschedule commit and apply notifications for the specified preferences session from the specified run loop and mode.

Parameter prefs: The preferences session.

Parameter runLoop: A reference to a run loop from which the notification should be unscheduled. Must be non-NULL.

Parameter runLoopMode: The mode on which to unschedule the notification. Must be non-NULL.

Returns: Returns TRUE if the notifications are successfully unscheduled; FALSE otherwise.

pub unsafe fn set_dispatch_queue(&self, queue: Option<&DispatchQueue>) -> bool

Available on crate feature dispatch2 only.

Schedule commit and apply notifications for the specified preferences session.

Parameter prefs: The preferences session.

Parameter queue: The dispatch queue to run the callback function on.

Returns: Returns TRUE if the notifications are successfully scheduled; FALSE otherwise.

Safety

queue possibly has additional threading requirements.

pub fn synchronize(&self)

Synchronizes accessed preferences with committed changes.

Any references to preference values returned by calls to the SCPreferencesGetValue function are no longer valid unless they were explicitly retained or copied. Any preference values that were updated (add, set, remove) but not committed will be discarded.

Parameter prefs: The preferences session.

impl SCPreferences

pub fn path_create_unique_child( &self, prefix: &CFString, ) -> Option<CFRetained<CFString>>

Available on crate feature SCPreferencesPath only.

Creates a new path component within the dictionary hierarchy.

Parameter prefs: The preferences session.

Parameter prefix: A string that represents the parent path.

Returns: Returns a string representing the new (unique) child path; NULL if the specified path does not exist.

pub fn path_get_value( &self, path: &CFString, ) -> Option<CFRetained<CFDictionary>>

Available on crate feature SCPreferencesPath only.

Returns the dictionary associated with the specified path.

Parameter prefs: The preferences session.

Parameter path: A string that represents the path to be returned.

Returns: Returns the dictionary associated with the specified path; NULL if the path does not exist.

pub fn path_get_link(&self, path: &CFString) -> Option<CFRetained<CFString>>

Available on crate feature SCPreferencesPath only.

Returns the link (if one exists) associated with the specified path.

Parameter prefs: The preferences session.

Parameter path: A string that represents the path to be returned.

Returns: Returns the dictionary associated with the specified path; NULL if the path is not a link or does not exist.

pub unsafe fn path_set_value( &self, path: &CFString, value: &CFDictionary, ) -> bool

Available on crate feature SCPreferencesPath only.

Associates a dictionary with the specified path.

Parameter prefs: The preferences session.

Parameter path: A string that represents the path to be updated.

Parameter value: A dictionary that represents the data to be stored at the specified path.

Returns: Returns TRUE if successful; FALSE otherwise.

Safety

value generics must be of the correct type.

pub fn path_set_link(&self, path: &CFString, link: &CFString) -> bool

Available on crate feature SCPreferencesPath only.

Associates a link to a second dictionary at the specified path.

Parameter prefs: The preferences session.

Parameter path: A string that represents the path to be updated.

Parameter link: A string that represents the link to be stored at the specified path.

Returns: Returns TRUE if successful; FALSE otherwise.

pub fn path_remove_value(&self, path: &CFString) -> bool

Available on crate feature SCPreferencesPath only.

Removes the data associated with the specified path.

Parameter prefs: The preferences session.

Parameter path: A string that represents the path to be returned.

Returns: Returns TRUE if successful; FALSE otherwise.

impl SCPreferences

pub fn set_computer_name( &self, name: Option<&CFString>, name_encoding: CFStringEncoding, ) -> bool

Available on crate feature SCPreferencesSetSpecific only.

Updates the computer name preference.

Note: To commit these changes to permanent storage you must call the SCPreferencesCommitChanges function. In addition, you must call the SCPreferencesApplyChanges function for the new name to become active.

Parameter prefs: The preferences session.

Parameter name: The computer name to be set.

Parameter nameEncoding: The encoding associated with the computer name.

Returns: Returns TRUE if successful; FALSE otherwise.

pub fn set_local_host_name(&self, name: Option<&CFString>) -> bool

Available on crate feature SCPreferencesSetSpecific only.

Updates the local host name.

Note: To commit these changes to permanent storage you must call the SCPreferencesCommitChanges function. In addition, you must call the SCPreferencesApplyChanges function for the new name to become active.

Parameter prefs: The preferences session.

Parameter name: The local host name to be set.

Note: this string must conform to the naming conventions of a DNS host name as specified in RFC 1034 (section 3.5).

Returns: Returns TRUE if successful; FALSE otherwise.

Methods from Deref<Target = CFType>

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: ConcreteType,

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl AsRef<AnyObject> for SCPreferences

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFType> for SCPreferences

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SCPreferences> for SCPreferences

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for SCPreferences

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for SCPreferences

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for SCPreferences

fn type_id() -> CFTypeID

Returns the type identifier of all SCPreferences instances.

impl Debug for SCPreferences

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for SCPreferences

type Target = CFType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for SCPreferences

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for SCPreferences

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for SCPreferences

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for SCPreferences

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Type for SCPreferences

fn retain(&self) -> CFRetained<Self>

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl Eq for SCPreferences