/* * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * The contents of this file constitute Original Code as defined in and * are subject to the Apple Public Source License Version 1.1 (the * "License"). You may not use this file except in compliance with the * License. Please obtain a copy of the License at * http://www.apple.com/publicsource and read it before using this file. * * This Original Code and all software distributed under the License are * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the * License for the specific language governing rights and limitations * under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef _SCPREFERENCES_H #define _SCPREFERENCES_H #include <sys/cdefs.h> #include <CoreFoundation/CoreFoundation.h> #include <SystemConfiguration/SCDynamicStore.h> /*! @header SCPreferences The SCPreferencesXXX() APIs allow 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 stored XML configuration data is accessed using a prefsID. A NULL value indicates that the default system preferences are to be accessed. A string which starts with a leading "/" character specifies the path to the file containing te preferences to be accessed. A string which does not start with a leading "/" character specifies a file relative to the default system preferences directory. The APIs provided by this framework communicate with the "configd" daemon for any tasks requiring synchronization and/or notification. */ /*! @typedef SCPreferencesRef @discussion This is the handle to an open "session" for accessing system configuration preferences. */ typedef const struct __SCPreferences * SCPreferencesRef; __BEGIN_DECLS /*! @function SCPreferencesGetTypeID Returns the type identifier of all SCPreferences instances. */ CFTypeID SCPreferencesGetTypeID (void); /*! @function SCPreferencesCreate @discussion Initiates access to the per-system set of configuration preferences. @param allocator ... @param name A string that describes the name of the calling process. @param prefsID A string that identifies the name of the group of preferences to be accessed/updated. @result prefs A pointer to memory that will be filled with an SCPreferencesRef handle to be used for all subsequent requests. If a session cannot be established, the contents of memory pointed to by this parameter are undefined. */ SCPreferencesRef SCPreferencesCreate ( CFAllocatorRef allocator, CFStringRef name, CFStringRef prefsID ); /*! @function SCPreferencesLock @discussion Locks access to the configuration preferences. This function obtains exclusive access to the configuration preferences associated with this prefsID. Clients attempting to obtain exclusive access to the preferences will either receive an kSCStatusPrefsBusy error or block waiting for the lock to be released. @param session An SCPreferencesRef handle that should be used for all API calls. @param wait A boolean flag indicating whether the calling process should block waiting for another process to complete its update operation and release its lock. @result TRUE if the lock was obtained; FALSE if an error occurred. XXXXX: old API error codes included kSCStatusPrefsBusy, kSCStatusAccessError, and kSCStatusStale */ Boolean SCPreferencesLock ( SCPreferencesRef session, Boolean wait ); /*! @function SCPreferencesCommitChanges @discussion Commits changes made to the configuration preferences to persitent storage. This function commits any changes to permanent storage. An implicit call to SCPreferencesLock/SCPreferencesUnlock will be made if exclusive access has not already been established. @param session An SCPreferencesRef handle that should be used for all API calls. @result TRUE if the lock was obtained; FALSE if an error occurred. XXXXX: old API error codes included kSCStatusAccessError, kSCStatusStale */ Boolean SCPreferencesCommitChanges ( SCPreferencesRef session ); /*! @function SCPreferencesApplyChanges @discussion Requests that the currently stored configuration preferences be applied to the active configuration. @param session An SCPreferencesRef handle that should be used for all API calls. @result TRUE if the lock was obtained; FALSE if an error occurred. */ Boolean SCPreferencesApplyChanges ( SCPreferencesRef session ); /*! @function SCPreferencesUnlock @discussion Releases exclusive access to the configuration preferences. This function releases the exclusive access "lock" for this prefsID. Other clients will be now be able to establish exclusive access to the preferences. @param session An SCPreferencesRef handle that should be used for all API calls. @result TRUE if the lock was obtained; FALSE if an error occurred. */ Boolean SCPreferencesUnlock ( SCPreferencesRef session ); /*! @function SCPreferencesGetSignature @discussion Returns a sequence of bytes that can be used to determine if the saved configuration preferences have changed. @param session An SCPreferencesRef handle that should be used for all API calls. @param signature A pointer to a CFDataRef that will reflect the signature of the configuration preferences at the time of the call to SCPreferencesCreate(). @result A CFDataRef that reflects the signature of the configuration preferences at the time of the call to SCPreferencesCreate(). */ CFDataRef SCPreferencesGetSignature ( SCPreferencesRef session ); /*! @function SCPreferencesCopyKeyList @discussion Returns an array of currently defined preference keys. @param session An SCPreferencesRef handle that should be used for all API calls. @result The list of keys. You must release the returned value. */ CFArrayRef SCPreferencesCopyKeyList ( SCPreferencesRef session ); /*! @function SCPreferencesGetValue @discussion Returns the data associated with a preference key. This function retrieves data associated with a key for the prefsID. Note: You could read stale data and not know it, unless you first call SCPreferencesLock(). @param session An SCPreferencesRef handle that should be used for all API calls. @param key The preference key to be returned. @result The value associated with the specified preference key; If no value was located, NULL is returned. */ CFPropertyListRef SCPreferencesGetValue ( SCPreferencesRef session, CFStringRef key ); /*! @function SCPreferencesAddValue @discussion Adds data for a preference key. This function associates new data with the specified key. In order to commit these changes to permanent storage a call must be made to SCPreferencesCommitChanges(). @param session The SCPreferencesRef handle that should be used to communicate with the APIs. @param key The preference key to be updated. @param value The CFPropertyListRef object containing the value to be associated with the specified preference key. @result TRUE if the value was added; FALSE if the key already exists or if an error occurred. */ Boolean SCPreferencesAddValue ( SCPreferencesRef session, CFStringRef key, CFPropertyListRef value ); /*! @function SCPreferencesSetValue @discussion Updates the data associated with a preference key. This function adds or replaces the value associated with the specified key. In order to commit these changes to permanent storage a call must be made to SCPreferencesCommitChanges(). @param session The SCPreferencesRef handle that should be used to communicate with the APIs. @param key The preference key to be updated. @param value The CFPropertyListRef object containing the data to be associated with the specified preference key. @result TRUE if the value was set; FALSE if an error occurred. */ Boolean SCPreferencesSetValue ( SCPreferencesRef session, CFStringRef key, CFPropertyListRef value ); /*! @function SCPreferencesRemoveValue @discussion Removes the data associated with a preference key. This function removes the data associated with the specified key. In order to commit these changes to permanent storage a call must be made to SCPreferencesCommitChanges(). @param session The SCPreferencesRef handle that should be used to communicate with the APIs. @param key The preference key to be removed. @result TRUE if the value was removed; FALSE if the key did not exist or if an error occurred. */ Boolean SCPreferencesRemoveValue ( SCPreferencesRef session, CFStringRef key ); __END_DECLS #endif /* _SCPREFERENCES_H */