SCPreferencesPath Reference

Framework
Declared in
SCPreferencesPath.h

Overview

The SCPreferencesPath programming interface allows an application to load and store XML configuration data in a controlled manner and provide the necessary notifications to other applications that need to be aware of configuration changes.

The functions in this programming interface view the data as a collection of dictionaries of key-value pairs and an associated path name. The root path ("/") identifies the top-level dictionary. Additional path components specify the keys for subdictionaries.

For example, the following dictionary can be accessed via two paths. The root path ("/") returns a dictionary with all keys and values. The path "/path1" returns only the dictionary with the "key3" and "key4" properties.

<dict>
   <key>key1</key>
   <string>val1</string>
   <key>key2</key>
   <string>val2</string>
   <key>path1</key>
   <dict>
      <key>key3</key>
      <string>val3</string>
      <key>key4</key>
      <string>val4</string>
   </dict>
</dict>

Each dictionary can also include the kSCResvLink ("__LINK__") key. The value associated with this key is interpreted as a link to another path. If this key is present, a call to the SCPreferencesPathGetValue function returns the dictionary specified by the link.

Functions by Task

Creating a New Path

Associating Information with a Path

Getting or Removing Information Associated with a Path

Functions

SCPreferencesPathCreateUniqueChild

Creates a new path component rooted at the specified path in the dictionary hierarchy.

CFStringRef SCPreferencesPathCreateUniqueChild (
   SCPreferencesRef prefs,
   CFStringRef prefix
);
Parameters
prefs

The preferences session.

prefix

The parent path.

Return Value

A string representing the new (unique) child path, or NULL if the specified path does not exist.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h

SCPreferencesPathGetLink

Returns the link associated with the specified path.

CFStringRef SCPreferencesPathGetLink (
   SCPreferencesRef prefs,
   CFStringRef path
);
Parameters
prefs

The preferences session.

path

The path.

Return Value

The link associated with the specified path, or NULL if the path is not a link or does not exist.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h

SCPreferencesPathGetValue

Returns the dictionary associated with the specified path.

CFDictionaryRef SCPreferencesPathGetValue (
   SCPreferencesRef prefs,
   CFStringRef path
);
Parameters
prefs

The preferences session.

path

The path.

Return Value

The dictionary associated with the specified path, or NULL if the path does not exist.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h

SCPreferencesPathRemoveValue

Removes the data associated with the specified path.

Boolean SCPreferencesPathRemoveValue (
   SCPreferencesRef prefs,
   CFStringRef path
);
Parameters
prefs

The preferences session.

path

The path.

Return Value

TRUE if successful; otherwise, FALSE.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h

SCPreferencesPathSetLink

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

Boolean SCPreferencesPathSetLink (
   SCPreferencesRef prefs,
   CFStringRef path,
   CFStringRef link
);
Parameters
prefs

The preferences session.

path

The path.

link

The link to be stored at the path.

Return Value

TRUE if successful; otherwise, FALSE.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h

SCPreferencesPathSetValue

Associates the specified dictionary with the specified path.

Boolean SCPreferencesPathSetValue (
   SCPreferencesRef prefs,
   CFStringRef path,
   CFDictionaryRef value
);
Parameters
prefs

The preferences session.

path

The path.

value

The dictionary of data to be stored at the path.

Return Value

TRUE if successful; otherwise, FALSE.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferencesPath.h