SystemConfiguration.fproj/SCP.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 #ifndef _SCP_H
  24 #define _SCP_H
  25
  26 #include <CoreFoundation/CoreFoundation.h>
  27 #include <sys/cdefs.h>
  28
  29 /*!
  30         @header SCP.h
  31         The SystemConfiguration framework provides access to the data used
  32                 to configure a running system.
  33
  34         Specifically, the SCPxxx() API's allow an application to load and
  35                 store XML configuration data in a controlled manner
  36                 and provides the necessary notifications to other
  37                 applications which need to be aware of configuration
  38                 changes.
  39
  40         The APIs provided by this framework communicate with the "configd"
  41                 daemon for any tasks requiring synchronization and/or
  42                 notification.
  43  */
  44
  45
  46 /*!
  47         @enum SCPStatus
  48         @discussion Returned status codes.
  49         @constant SCP_OK                Success
  50         @constant SCP_NOSESSION         Preference session not active
  51         @constant SCP_BUSY              Configuration daemon busy
  52         @constant SCD_NEEDLOCK          Lock required for this operation
  53         @constant SCP_EACCESS           Permission denied (must be root to obtain lock)
  54         @constant SCP_ENOENT            Configuration file not found
  55         @constant SCP_BADCF             Configuration file corrupt
  56         @constant SCD_NOKEY             No such key
  57         @constant SCD_NOLINK            No such link
  58         @constant SCP_EXISTS            Key already defined
  59         @constant SCP_STALE             Write attempted on stale version of object
  60         @constant SCP_INVALIDARGUMENT   Invalid argument
  61         @constant SCP_FAILED            Generic error
  62  */
  63 typedef enum {
  64         SCP_OK                  = 0,    /* Success */
  65         SCP_NOSESSION           = 1024, /* Preference session not active */
  66         SCP_BUSY                = 1025, /* Preferences update currently in progress */
  67         SCP_NEEDLOCK            = 1026, /* Lock required for this operation */
  68         SCP_EACCESS             = 1027, /* Permission denied */
  69         SCP_ENOENT              = 1028, /* Configuration file not found */
  70         SCP_BADCF               = 1029, /* Configuration file corrupt */
  71         SCP_NOKEY               = 1030, /* No such key */
  72         SCP_NOLINK              = 1031, /* No such link */
  73         SCP_EXISTS              = 1032, /* No such key */
  74         SCP_STALE               = 1033, /* Write attempted on stale version of object */
  75         SCP_INVALIDARGUMENT     = 1034, /* Invalid argument */
  76         SCP_FAILED              = 9999  /* Generic error */
  77 } SCPStatus;
  78
  79
  80 /*!
  81         @enum SCPOption
  82         @discussion Used with the SCP[User]Open() and SCP[User]NotificationKeyCreate()
  83                 to describe the prefsID CFStringRef argument.
  84         @constant kSCPOptionCreatePrefs Specifies that the preferences file should
  85                 be created if it does not exist.
  86  */
  87 typedef enum {
  88         kSCPOpenCreatePrefs     = 1,    /* create preferences file if not found */
  89 } SCPOption;
  90
  91
  92 /*!
  93         @enum SCPKeyType
  94         @discussion Used with the SCDList() and SCDNotifierAdd() functions to describe
  95                 the CFStringRef argument.
  96         @constant kSCDKeyLock   key used when exclusive access to the stored preferences
  97                 is obtained or released.
  98         @constant kSCDKeyCommit key used when new preferences are committed to the store
  99         @constant kSCDKeyApply  key used when new preferences are to be applied to the
 100                 active system configuration.
 101  */
 102 typedef enum {
 103         kSCPKeyLock     = 1,
 104         kSCPKeyCommit   = 2,
 105         kSCPKeyApply    = 3,
 106 } SCPKeyType;
 107
 108
 109 /*!
 110         @typedef SCPSessionRef
 111         @discussion This is the type of a handle to an open "session" for
 112                 accessing system configuration preferences.
 113  */
 114 typedef void *          SCPSessionRef;
 115
 116
 117 __BEGIN_DECLS
 118
 119 /*!
 120         @function SCPOpen
 121         @discussion Initiates access to the per-system set of configuration
 122                 preferences.
 123
 124         This function will ensure that the current state of the prefsID is
 125         retrieved (by reading the whole thing into memory, or at least,
 126         open()'ing the file and keeping it open)
 127         @param session A pointer to memory which will be filled with an
 128                 SCPSessionRef handle to be used for all subsequent requests.
 129                 If a session cannot be established, the contents of
 130                 memory pointed to by this parameter are undefined.
 131         @param name Pass a string which describes the name of the calling
 132                 process.
 133         @param prefsID Pass a string which identifies the name of the
 134                 group of preferences to be accessed/updated. A NULL value
 135                 specifies the default system configuration preferences.
 136         @param options Pass a bitfield of type SCPOpenOption containing
 137                 one or more flags describing how the preferences should
 138                 be accessed.
 139
 140         @result A constant of type SCPStatus indicating the success (or
 141                 failure) of the call.
 142  */
 143 SCPStatus       SCPOpen                         (SCPSessionRef          *session,
 144                                                  CFStringRef            name,
 145                                                  CFStringRef            prefsID,
 146                                                  int                    options);
 147
 148 /*!
 149         @function SCPUserOpen
 150         @discussion Initiates access to the per-user set of configuration
 151                 preferences.
 152
 153         This function will ensure that the current state of the prefsID is
 154         retrieved (by reading the whole thing into memory, or at least,
 155         open()'ing the file and keeping it open)
 156         @param session A pointer to memory which will be filled with an
 157                 SCPSessionRef handle to be used for all subsequent requests.
 158                 If a session cannot be established, the contents of
 159                 memory pointed to by this parameter are undefined.
 160         @param name Pass a string which describes the name of the calling
 161                 process.
 162         @param prefsID Pass a string which identifies the name of the
 163                 group of preferences to be accessed/updated.
 164         @param user Pass a string which identifies the user/login who's
 165                 preferences should be accessed.  A NULL value specifies
 166                 the current console user.
 167         @param options Pass a bitfield of type SCPOpenOption containing
 168                 one or more flags describing how the preferences should
 169                 be accessed.
 170
 171         @result A constant of type SCPStatus indicating the success (or
 172                 failure) of the call.
 173  */
 174 SCPStatus       SCPUserOpen                     (SCPSessionRef          *session,
 175                                                  CFStringRef            name,
 176                                                  CFStringRef            prefsID,
 177                                                  CFStringRef            user,
 178                                                  int                    options);
 179
 180 /*!
 181         @function SCPClose
 182         @discussion Terminates access to a set of configuration preferences.
 183
 184         This function frees/closes all allocated/opened resources. Any
 185         uncommitted changes are NOT written.
 186         @param session Pass a pointer to the SCPSessionRef handle which should
 187                 be closed.
 188         @result A constant of type SCPStatus indicating the success (or
 189                 failure) of the call.
 190  */
 191 SCPStatus       SCPClose                        (SCPSessionRef          *session);
 192
 193 /*!
 194         @function SCPLock
 195         @discussion Locks access to the configuration preferences.
 196
 197         This function obtains exclusive access to the configuration
 198         preferences associated with this prefsID. Clients attempting
 199         to obtain exclusive access the preferences will either receive
 200         an SCP_BUSY error or block waiting for the lock to be released.
 201         @param session Pass an SCPSessionRef handle which should be used for
 202                 all API calls.
 203         @param wait Pass a boolean flag indicating whether the calling process
 204                 should block waiting for another process to complete its update
 205                 operation and release its lock.
 206         @result A constant of type SCPStatus indicating the success (or
 207                 failure) of the call. Possible return values include: SCP_OK,
 208                 SCP_BUSY, SCP_EACCESS, SCP_STALE.
 209  */
 210 SCPStatus       SCPLock                         (SCPSessionRef          session,
 211                                                  boolean_t              wait);
 212
 213 /*!
 214         @function SCPCommit
 215         @discussion Commits changes made to the configuration preferences to
 216                 persitent storage.
 217
 218         This function commits the any changes to permanent storage. An
 219         implicit call to SCPLock/SCPUnlock will be made if exclusive
 220         access had not been established.
 221         @param session Pass an SCPSessionRef handle which should be used for
 222                 all API calls.
 223         @result A constant of type SCPStatus indicating the success (or
 224                 failure) of the call. Possible return values include: SCP_OK,
 225                 SCP_BUSY, SCP_EACCESS, SCP_STALE.
 226  */
 227 SCPStatus       SCPCommit                       (SCPSessionRef          session);
 228
 229 /*!
 230         @function SCPApply
 231         @discussion Requests that the currently stored configuration
 232                 preferences be applied to the active configuration.
 233         @param session Pass an SCPSessionRef handle which should be used for
 234                 all API calls.
 235         @result A constant of type SCPStatus indicating the success (or
 236                 failure) of the call. Possible return values include: SCP_OK,
 237                 SCP_EACCESS.
 238  */
 239 SCPStatus       SCPApply                        (SCPSessionRef          session);
 240
 241 /*!
 242         @function SCPUnlock
 243         @discussion Releases exclusive access to the configuration preferences.
 244
 245         This function releases the exclusive access "lock" fr this prefsID.
 246         Other clients will be now be able to establish exclusive access to
 247         the preferences.
 248         @param session Pass an SCPSessionRef handle which should be used for
 249                 all API calls.
 250         @result A constant of type SCPStatus indicating the success (or
 251                 failure) of the call.
 252  */
 253 SCPStatus       SCPUnlock                       (SCPSessionRef          session);
 254
 255 /*!
 256         @function SCPGetSignature
 257         @discussion Returns an sequence of bytes which can be used to determine
 258                 if the saved configuration preferences have changed.
 259         @param session Pass an SCPSessionRef handle which should be used for
 260                 all API calls.
 261         @param signature Pass a pointer to a CFDataRef which will be reflect
 262                 the signature of the configuration preferences at the time
 263                 of the call to SCPOpen().
 264         @result A constant of type SCPStatus indicating the success (or
 265                 failure) of the call.
 266  */
 267 SCPStatus       SCPGetSignature                 (SCPSessionRef          session,
 268                                                  CFDataRef              *signature);
 269
 270 /*!
 271         @function SCPList
 272         @discussion Returns an array of currently defined preference keys.
 273         @param session Pass an SCPSessionRef handle which should be used for
 274                 all API calls.
 275         @param keys Pass a pointer to a CFArrayRef which will be set to a new
 276                 array of currently defined preference keys.
 277         @result A constant of type SCPStatus indicating the success (or
 278                 failure) of the call.
 279  */
 280 SCPStatus       SCPList                         (SCPSessionRef          session,
 281                                                  CFArrayRef             *keys);
 282
 283 /*!
 284         @function SCPGet
 285         @discussion Returns the data associated with a preference key.
 286
 287         This function retrieves data associated with a key for the prefsID.
 288         You "could" read stale data and not know it, unless you first call
 289         SCPLock().
 290         @param session Pass an SCPSessionRef handle which should be used for
 291                 all API calls.
 292         @param key Pass a reference to the preference key to be returned.
 293         @param data Pass a pointer to a CFPropertyListRef which will be set to a
 294                 new object containing the data associated with the
 295                 configuration preference.
 296         @result A constant of type SCPStatus indicating the success (or
 297                 failure) of the call. Possible return values include: SCP_OK,
 298                 SCP_NOKEY.
 299  */
 300 SCPStatus       SCPGet                          (SCPSessionRef          session,
 301                                                  CFStringRef            key,
 302                                                  CFPropertyListRef      *data);
 303
 304 /*!
 305         @function SCPAdd
 306         @discussion Adds data for a preference key.
 307
 308         This function associates new data with the specified key. In order
 309         to commit these changes to permanent storage a call must be made to
 310         SCDPCommit().
 311         @param session Pass the SCPSessionRef handle which should be used to
 312                 communicate with the APIs.
 313         @param key Pass a reference to the preference key to be updated.
 314         @param data Pass a reference to the CFPropertyListRef object containing the
 315                 data to be associated with the configuration preference.
 316         @result A constant of type SCPStatus indicating the success (or
 317                 failure) of the call. Possible return values include: SCP_OK,
 318                 SCP_EXISTS.
 319  */
 320 SCPStatus       SCPAdd                          (SCPSessionRef          session,
 321                                                  CFStringRef            key,
 322                                                  CFPropertyListRef      data);
 323
 324 /*!
 325         @function SCPSet
 326         @discussion Updates the data associated with a preference key.
 327
 328         This function creates (or updates) the data associated with the
 329         specified key. In order to commit these changes to permanent
 330         storage a call must be made to SCDPCommit().
 331         @param session Pass the SCPSessionRef handle which should be used to
 332                 communicate with the APIs.
 333         @param key Pass a reference to the preference key to be updated.
 334         @param data Pass a reference to the CFPropertyListRef object containing the
 335                 data to be associated with the configuration preference.
 336         @result A constant of type SCPStatus indicating the success (or
 337                 failure) of the call. Possible return values include: SCP_OK.
 338  */
 339 SCPStatus       SCPSet                          (SCPSessionRef          session,
 340                                                  CFStringRef            key,
 341                                                  CFPropertyListRef      data);
 342
 343 /*!
 344         @function SCPRemove
 345         @discussion Removes the data associated with a preference key.
 346
 347         This function removes the data associated with the specified
 348         key. In order to commit these changes to permanent storage a
 349         call must be made to SCDPCommit().
 350         @param session Pass the SCPSessionRef handle which should be used to
 351                 communicate with the APIs.
 352         @param key Pass a reference to the preference key to be removed.
 353         @result A constant of type SCPStatus indicating the success (or
 354                 failure) of the call. Possible return values include: SCP_OK,
 355                 SCP_NOKEY.
 356  */
 357 SCPStatus       SCPRemove                       (SCPSessionRef          session,
 358                                                  CFStringRef            key);
 359
 360 /*!
 361         @function SCPNotificationKeyCreate
 362         @discussion Creates a key which can be used by the SCDNotifierAdd()
 363                 function to receive notifications of changes to the saved
 364                 preferences.
 365         @param prefsID Pass a string which identifies the name of the
 366                 preferences to be accessed/updated. A NULL value specifies
 367                 the default system configuration preferences.
 368         @param keyType Pass a kSCPKeyType indicating the type a notification
 369                 key to be returned.
 370         @result A notification string for the specified preference identifier.
 371  */
 372 CFStringRef     SCPNotificationKeyCreate        (CFStringRef            prefsID,
 373                                                  int                    keyType);
 374
 375 /*!
 376         @function SCPUserNotificationKeyCreate
 377         @discussion Creates a key which can be used by the SCDNotifierAdd()
 378                 function to receive notifications of changes to the saved
 379                 preferences.
 380         @param prefsID Pass a string which identifies the name of the
 381                 preferences to be accessed/updated. A NULL value specifies
 382                 the default system configuration preferences.
 383         @param user Pass a string which identifies the user/login who's
 384                 preferences should be accessed.  A NULL value specifies
 385                 the current console user.
 386         @param keyType Pass a kSCPKeyType indicating the type a notification
 387                 key to be returned.
 388         @result A notification string for the specified preference identifier.
 389  */
 390 CFStringRef     SCPUserNotificationKeyCreate    (CFStringRef            prefsID,
 391                                                  CFStringRef            user,
 392                                                  int                    keyType);
 393
 394 /*!
 395         @function SCPError
 396         @discussion
 397         @param status
 398         @result
 399  */
 400 const char *    SCPError                        (SCPStatus              status);
 401
 402 __END_DECLS
 403
 404 #endif /* _SCP_H */