/* * 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 _SCD_H #define _SCD_H #include <CoreFoundation/CoreFoundation.h> #include <CoreFoundation/CFRunLoop.h> #include <mach/message.h> #include <sys/cdefs.h> #include <sys/syslog.h> /*! @header SCD.h The SystemConfiguration framework provides access to the data used to configure a running system. The APIs provided by this framework communicate with the "configd" daemon. The "configd" daemon manages a "cache" reflecting the desired configuration settings as well as the current state of the system. The daemon provides a notification mechanism for user-level processes which need to be aware of changes made to the "cache" data. Lastly, the daemon loads a number of bundles(or plug-ins) which monitor low-level kernel events and, via a set of policy modules, keep this cached data up to date. The "configd" daemon also provides an address space/task/process which can be used by other CFRunLoop based functions which would otherwise require their own process/daemon for execution. */ /*! @enum SCDStatus @discussion Returned status codes. @constant SCD_OK Success @constant SCD_NOSESSION Configuration daemon session not active @constant SCD_NOSERVER Configuration daemon not (no longer) available @constant SCD_LOCKED Lock already held @constant SCD_NEEDLOCK Lock required for this operation @constant SCD_EACCESS Permission denied (must be root to obtain lock) @constant SCD_NOKEY No such key @constant SCD_EXISTS Data associated with key already defined @constant SCD_STALE Write attempted on stale version of object @constant SCD_INVALIDARGUMENT Invalid argument @constant SCD_NOTIFIERACTIVE Notifier is currently active @constant SCD_FAILED Generic error */ typedef enum { SCD_OK = 0, /* Success */ SCD_NOSESSION = 1, /* Configuration daemon session not active */ SCD_NOSERVER = 2, /* Configuration daemon not (no longer) available */ SCD_LOCKED = 3, /* Lock already held */ SCD_NEEDLOCK = 4, /* Lock required for this operation */ SCD_EACCESS = 5, /* Permission denied (must be root to obtain lock) */ SCD_NOKEY = 6, /* No such key */ SCD_EXISTS = 7, /* Data associated with key already defined */ SCD_STALE = 8, /* Write attempted on stale version of object */ SCD_INVALIDARGUMENT = 9, /* Invalid argument */ SCD_NOTIFIERACTIVE = 10, /* Notifier is currently active */ SCD_FAILED = 9999 /* Generic error */ } SCDStatus; /*! @typedef SCDSessionRef @discussion This is the type of a handle to an open "session" with the system configuration daemon. */ typedef const struct __SCDSession * SCDSessionRef; /*! @typedef SCDHandleRef @discussion This is the type of a handle to data being retrieved from or to be stored by the system configuration daemon. */ typedef const struct __SCDHandle * SCDHandleRef; /*! @typedef SCDCallbackRoutine_t @discussion Type of the callback function used by the SCDNotifierInformViaCallback() function. @param session The session handle. @param callback_argument The user-defined argument to be passed to the callback function. */ typedef boolean_t (*SCDCallbackRoutine_t) (SCDSessionRef session, void *callback_argument); /*! @enum SCDKeyOption @discussion Used with the SCDList() and SCDNotifierAdd() functions to describe the CFStringRef argument. @constant kSCDRegexKey Specifies that the key consists of a regular expression. */ typedef enum { kSCDRegexKey = 0100000, /* pattern string is a regular expression */ } SCDKeyOption; /*! @enum SCDOption @discussion Options which determine the run-time processing of the system configuration framework functions. @constant kSCDOptionDebug Enable debugging @constant kSCDOptionVerbose Enable verbose logging @constant kSCDOptionUseSyslog Use syslog(3) for log messages @constant kSCDOptionUseCFRunLoop Calling application is CFRunLoop() based */ typedef enum { kSCDOptionDebug = 0, /* Enable debugging */ kSCDOptionVerbose = 1, /* Enable verbose logging */ kSCDOptionUseSyslog = 2, /* Use syslog(3) for log messages */ kSCDOptionUseCFRunLoop = 3, /* Calling application is CFRunLoop() based */ } SCDOption; /* * "configd" loadable bundle / plug-in options */ /*! @typedef SCDBundleStartRoutine_t @discussion Type of the start() initializatioin function which will be called after all plug-ins have been loaded. This function should initialize any variables, open any sessions with "configd", and register any needed notifications. @param bundlePath The path name associated with the plug-in / bundle. @param bundleName The name of the plug-in / bundle. */ typedef void (*SCDBundleStartRoutine_t) (const char *bundlePath, const char *bundleName); /*! @typedef SCDBundlePrimeRoutine_t @discussion Type of the prime() initializatioin function which will be called after all plug-ins have executed their start() function but before the main plug-in run loop is started. This function should be used to initialize any configuration information and/or state in the cache. */ typedef void (*SCDBundlePrimeRoutine_t) (); #define BUNDLE_DIRECTORY "/SystemConfiguration" /* [/System/Library]/... */ #define BUNDLE_OLD_SUBDIR "/" #define BUNDLE_NEW_SUBDIR "/Contents/MacOS/" #define BUNDLE_DIR_EXTENSION ".bundle" #define BUNDLE_DEBUG_EXTENSION "_debug" #define BUNDLE_ENTRY_POINT "_start" #define BUNDLE_ENTRY_POINT2 "_prime" __BEGIN_DECLS /*! @function SCDHandleInit @discussion Creates a new handle used to access the cached configuration dictionary data. @result A new "cache" data handle. */ SCDHandleRef SCDHandleInit (); /*! @function SCDHandleRelease @discussion Releases the specified configuration data handle. The dictionary (or other CFType) associated with this handle will also be released unless a call was previously made to CFRetain(). @param handle The cache data handle to be released. */ void SCDHandleRelease (SCDHandleRef handle); /*! @function SCDHandleGetInstance @discussion Returns the instance number associated with the specified configuration handle. @param handle The cache data handle. @result The instance number associated with the specified handle. */ int SCDHandleGetInstance (SCDHandleRef handle); /*! @function SCDHandleGetData @discussion Returns a reference to the data associated with the specified configuration handle. @param handle The cache data handle. @result The CFType data associated with the specified handle. */ CFPropertyListRef SCDHandleGetData (SCDHandleRef handle); /*! @function SCDHandleSetData @discussion Returns a reference to the data associated with the specified configuration handle. @param handle The cache data handle. @param data The CFType data to be associated with the handle. */ void SCDHandleSetData (SCDHandleRef handle, CFPropertyListRef data); /*! @function SCDOpen @discussion Initiates a connection with the configuration daemon. @param session A pointer to memory which will be filled with an SCDSessionRef handle to be used for all subsequent requests to the server. If a session cannot be established with the server, the contents of memory pointed to by this parameter are undefined. @param name Pass a string which describes the name of the calling process or plug-in name of the caller. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDOpen (SCDSessionRef *session, CFStringRef name); /*! @function SCDClose @discussion Closes the specified session to the configuration daemon. All outstanding notification requests will be cancelled. @param session Pass a pointer to an SCDSessionRef handle which should be closed. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDClose (SCDSessionRef *session); /*! @function SCDLock @discussion Locks access to the configuration "cache". All other clients attempting to access the "cache" will block. All change notifications will be deferred until the lock is released. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDLock (SCDSessionRef session); /*! @function SCDUnlock @discussion Unlocks access to the configuration "cache". Other clients will be able to access the "cache". Any change notifications will be delivered. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDUnlock (SCDSessionRef session); /*! @function SCDList @discussion Returns an array of CFStringRefs representing the configuration "cache" entries which match the specified pattern key. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key The string which must prefix those keys in the configuration "cache" (if regexOptions is zero) or a regex(3) regular expression string which will be used to match configuration "cache" (if regexOptions is kSCDRegexKey). @param regexOptions Pass a bitfield of type SCDKeyOption containing one or more flags describing the pattern key. @param subKeys Pass a pointer to a CFArrayRef which will be set to a new array of CFStringRefs's matching the provided key. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDList (SCDSessionRef session, CFStringRef key, int regexOptions, CFArrayRef *subKeys); /*! @function SCDAdd @discussion Creates a new entry in the configuration "cache" using the specified key and data. An error is returned if the key is already defined in the dictionary. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be created. @param handle Pass a reference to the SCDHandle object containing the data to be associated with the specified key. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDAdd (SCDSessionRef session, CFStringRef key, SCDHandleRef handle); /*! @function SCDAddSession @discussion Creates a new entry in the configuration "cache" using the specified key and data. This entry will, unless updated by another session, automatically be removed when the session is closed. An error is returned if the key is already defined in the dictionary. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be created. @param handle Pass a reference to the SCDHandle object containing the data to be associated with the specified key. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDAddSession (SCDSessionRef session, CFStringRef key, SCDHandleRef handle); /*! @function SCDGet @discussion Returns a handle to the configuration "cache" data that corresponds to the specified key. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be returned. @param handle Pass a pointer to a SCDHandleRef which will be set to a new object containing the data associated with the specified key. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDGet (SCDSessionRef session, CFStringRef key, SCDHandleRef *handle); /*! @function SCDSet @discussion Updates the entry in the configuration "cache" that corresponds to the specified key with the provided data. An error will be returned if the data in the "cache" has been updated since the data handle was last updated. @param session Pass the SCDSessionRef handle which should be used to communicate with the server. @param key Pass a reference to the CFStringRef object to be updated. @param handle Pass a reference to the SCDHandle object containing the data to be associated with the specified key. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDSet (SCDSessionRef session, CFStringRef key, SCDHandleRef handle); /*! @function SCDRemove @discussion Removes the data from the configuration "cache" data which corresponds to the specified key. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be removed. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDRemove (SCDSessionRef session, CFStringRef key); /*! @function SCDTouch @discussion Updates the instance number for the data in the configuration "cache" associated with the specified key. If the specified key does not exist then a CFDate object will be associated with the key. If the associated data is already a CFDate object then the value will be updated. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be updated. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDTouch (SCDSessionRef session, CFStringRef key); /* @function SCDSnapshot @discussion Records the current state of configd's cache dictionary into the /var/tmp/configd-cache file and configd's session dictionary into the /var/tmp/configd-session file. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDSnapshot (SCDSessionRef session); /*! @function SCDNotifierList @discussion Returns an array of CFStringRefs representing the system configuration data entries being monitored for changes. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether the specific configuration cache key patterns are to be returned or those based on regex(3) pattern strings. @param notifierKeys Pass a pointer to a CFArrayRef which will be set to a new array of CFStringRef's being monitored. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierList (SCDSessionRef session, int regexOptions, CFArrayRef *notifierKeys); /*! @function SCDNotifierAdd @discussion Adds the specified key to the list of system configuration data entries which are being monitored for changes. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object to be monitored. @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether the key is for a specific configuration cache key or if it consists of a regex(3) pattern string. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierAdd (SCDSessionRef session, CFStringRef key, int regexOptions); /*! @function SCDNotifierRemove @discussion Removes the specified key from the list of system configuration data entries which are being monitored for changes. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param key Pass a reference to the CFStringRef object which should not be monitored. @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether the key is for a specific configuration cache key or if it consists of a regex(3) pattern string. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierRemove (SCDSessionRef session, CFStringRef key, int regexOptions); /*! @function SCDNotifierGetChanges @discussion Returns an array of CFStringRefs representing the monitored system configuration data entries which have changed since this function was last called. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param notifierKeys Pass a pointer to a CFArrayRef which will be set to a new array of CFStringRef's being monitored. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierGetChanges (SCDSessionRef session, CFArrayRef *notifierKeys); /*! @function SCDNotifierWait @discussion Waits for a change to be made to a system configuration data entry associated with the current sessions notifier keys. Note: this function is not valid for "configd" plug-ins. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierWait (SCDSessionRef session); /*! @function SCDNotifierInformViaCallback @discussion Requests that the specified function be called whenever a change has been detected to one of the system configuration data entries associated with the current sessions notifier keys. The callback function will be called with two arguments, session and arg, which correspond to the current session and the provided argument. The function should return a boolean value indicating whether an error occurred during execution of the callback. Note: if the calling application is based on the CFRunLoop() then an additional run loop source will be added for the notification. Applications which are not based on the CFRunLoop() will have a separate thread started to wait for changes. In either case, the additional run loop source and/or thread will terminate if the notification is cancelled or if the callback indicates that an error was detected. Note: this function is not valid for "configd" plug-ins. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param func Pass a pointer to the callback applier function to call when a monitored cache entry is changed. If this parameter is not a pointer to a function of the correct prototype (SCDCallbackRoutine_t), the behavior is undefined. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierInformViaCallback (SCDSessionRef session, SCDCallbackRoutine_t func, void *arg); /*! @function SCDNotifierInformViaMachPort @discussion Allocates a mach port which can be used to detect changes to one of the system configuration data entries associated with the current sessions notifier keys. When a change is detected, an empty (no data) mach message with the specified identifier will be delivered to the calling application via the allocated port. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param msgid Pass a mach message ID to be included with any notifications. @param port Pass a pointer to a mach port. Upon return, port will be filled with the mach port which will be used for any notifications. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierInformViaMachPort (SCDSessionRef session, mach_msg_id_t msgid, mach_port_t *port); /*! @function SCDNotifierInformViaFD @discussion Allocates a file descriptor which can be used to detect changes to one of the system configuration data entries associated with the current sessions notifier keys. When a change is detected, the specified identifier (4 bytes) will be delivered to the calling application via the allocated file descriptor. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param identifier Pass an (4 byte) integer identifer which be used for any notifications. @param fd Pass a pointer to a file descriptor. Upon return, fd will be filled with the file descriptor which will be used for any notifications. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierInformViaFD (SCDSessionRef session, int32_t identifier, int *fd); /*! @function SCDNotifierInformViaSignal @discussion Requests that the specified BSD signal be sent to the process with the indicated process id whenever a change has been detected to one of the system configuration data entries associated with the current sessions notifier keys. Note: this function is not valid for "configd" plug-ins. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @param pid Pass a UNIX proces ID which should be signalled for any notifications. @param sig Pass a signal number to be used. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierInformViaSignal (SCDSessionRef session, pid_t pid, int sig); /*! @function SCDNotifierCancel @discussion Cancels all outstanding notification delivery request for this session. @param session Pass a SCDSessionRef handle which should be used for communication with the server. @result A constant of type SCDStatus indicating the success (or failure) of the call. */ SCDStatus SCDNotifierCancel (SCDSessionRef session); /*! @function SCDOptionGet @discussion Returns the value associated with the specified option. @param session Pass a SCDSessionRef handle of the option of interest (or NULL for the global option setting). @param option Pass the SCDOption of interest. @result The current value of the specified option. */ int SCDOptionGet (SCDSessionRef session, int option); /*! @function SCDOptionSet @discussion Sets the value associated with the specified option. @param session Pass a SCDSessionRef handle for the option to be set (or NULL for the global option settings). @param option Pass the SCDOption to be updated. @param value Pass the new value for the option. @result The current value of the specified option. */ void SCDOptionSet (SCDSessionRef session, int option, int value); /*! @function SCDSessionLog @discussion Issues a log and/or debug message. @param session Pass a SCDSessionRef handle for the current session.. @param level Pass a syslog(3) logging priority. Note: LOG_DEBUG messages will not be issued if the verbose option has not been enabled. @param formatString Pass the CF format string @result The specified message will be logged. */ void SCDSessionLog (SCDSessionRef session, int level, CFStringRef formatString, ...); /*! @function SCDLog @discussion Issues a log and/or debug message. @param level Pass a syslog(3) logging priority. @param formatString Pass the CF format string @result The specified message will be logged. */ void SCDLog (int level, CFStringRef formatString, ...); const char * SCDError (SCDStatus status); __END_DECLS #endif /* _SCD_H */