SystemConfiguration.fproj/SCD.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 _SCD_H
  24 #define _SCD_H
  25
  26 #include <CoreFoundation/CoreFoundation.h>
  27 #include <CoreFoundation/CFRunLoop.h>
  28 #include <mach/message.h>
  29 #include <sys/cdefs.h>
  30 #include <sys/syslog.h>
  31
  32
  33 /*!
  34         @header SCD.h
  35         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.
  36
  37 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.
  38
  39 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.
  40
  41  */
  42
  43
  44 /*!
  45         @enum SCDStatus
  46         @discussion Returned status codes.
  47         @constant SCD_OK                Success
  48         @constant SCD_NOSESSION         Configuration daemon session not active
  49         @constant SCD_NOSERVER          Configuration daemon not (no longer) available
  50         @constant SCD_LOCKED            Lock already held
  51         @constant SCD_NEEDLOCK          Lock required for this operation
  52         @constant SCD_EACCESS           Permission denied (must be root to obtain lock)
  53         @constant SCD_NOKEY             No such key
  54         @constant SCD_EXISTS            Data associated with key already defined
  55         @constant SCD_STALE             Write attempted on stale version of object
  56         @constant SCD_INVALIDARGUMENT   Invalid argument
  57         @constant SCD_NOTIFIERACTIVE    Notifier is currently active
  58         @constant SCD_FAILED            Generic error
  59  */
  60 typedef enum {
  61         SCD_OK                  = 0,    /* Success */
  62         SCD_NOSESSION           = 1,    /* Configuration daemon session not active */
  63         SCD_NOSERVER            = 2,    /* Configuration daemon not (no longer) available */
  64         SCD_LOCKED              = 3,    /* Lock already held */
  65         SCD_NEEDLOCK            = 4,    /* Lock required for this operation */
  66         SCD_EACCESS             = 5,    /* Permission denied (must be root to obtain lock) */
  67         SCD_NOKEY               = 6,    /* No such key */
  68         SCD_EXISTS              = 7,    /* Data associated with key already defined */
  69         SCD_STALE               = 8,    /* Write attempted on stale version of object */
  70         SCD_INVALIDARGUMENT     = 9,    /* Invalid argument */
  71         SCD_NOTIFIERACTIVE      = 10,   /* Notifier is currently active */
  72         SCD_FAILED              = 9999  /* Generic error */
  73 } SCDStatus;
  74
  75
  76 /*!
  77         @typedef SCDSessionRef
  78         @discussion This is the type of a handle to an open "session" with the system
  79                 configuration daemon.
  80  */
  81 typedef const struct __SCDSession *     SCDSessionRef;
  82
  83 /*!
  84         @typedef SCDHandleRef
  85         @discussion This is the type of a handle to data being retrieved from or to be
  86                 stored by the system configuration daemon.
  87  */
  88 typedef const struct __SCDHandle *      SCDHandleRef;
  89
  90
  91 /*!
  92         @typedef SCDCallbackRoutine_t
  93         @discussion Type of the callback function used by the SCDNotifierInformViaCallback()
  94                 function.
  95         @param session The session handle.
  96         @param callback_argument The user-defined argument to be passed to the callback
  97                 function.
  98  */
  99 typedef boolean_t (*SCDCallbackRoutine_t)        (SCDSessionRef         session,
 100                                                   void                  *callback_argument);
 101
 102
 103 /*!
 104         @enum SCDKeyOption
 105         @discussion Used with the SCDList() and SCDNotifierAdd() functions to describe
 106                 the CFStringRef argument.
 107         @constant kSCDRegexKey Specifies that the key consists of a regular expression.
 108  */
 109 typedef enum {
 110         kSCDRegexKey            = 0100000,      /* pattern string is a regular expression */
 111 } SCDKeyOption;
 112
 113
 114 /*!
 115         @enum SCDOption
 116         @discussion Options which determine the run-time processing of the system
 117                 configuration framework functions.
 118         @constant kSCDOptionDebug Enable debugging
 119         @constant kSCDOptionVerbose Enable verbose logging
 120         @constant kSCDOptionUseSyslog Use syslog(3) for log messages
 121         @constant kSCDOptionUseCFRunLoop Calling application is CFRunLoop() based
 122  */
 123 typedef enum {
 124         kSCDOptionDebug         = 0,    /* Enable debugging */
 125         kSCDOptionVerbose       = 1,    /* Enable verbose logging */
 126         kSCDOptionUseSyslog     = 2,    /* Use syslog(3) for log messages */
 127         kSCDOptionUseCFRunLoop  = 3,    /* Calling application is CFRunLoop() based */
 128 } SCDOption;
 129
 130
 131 /*
 132  * "configd" loadable bundle / plug-in options
 133  */
 134
 135 /*!
 136         @typedef SCDBundleStartRoutine_t
 137         @discussion Type of the start() initializatioin function which will be called
 138                 after all plug-ins have been loaded.  This function should initialize any
 139                 variables, open any sessions with "configd", and register any needed
 140                 notifications.
 141         @param bundlePath The path name associated with the plug-in / bundle.
 142         @param bundleName The name of the plug-in / bundle.
 143  */
 144 typedef void (*SCDBundleStartRoutine_t) (const char *bundlePath,
 145                                          const char *bundleName);
 146
 147 /*!
 148         @typedef SCDBundlePrimeRoutine_t
 149         @discussion Type of the prime() initializatioin function which will be
 150                 called after all plug-ins have executed their start() function but
 151                 before the main plug-in run loop is started.  This function should
 152                 be used to initialize any configuration information and/or state
 153                 in the cache.
 154  */
 155 typedef void (*SCDBundlePrimeRoutine_t) ();
 156
 157 #define BUNDLE_DIRECTORY        "/SystemConfiguration"  /* [/System/Library]/... */
 158 #define BUNDLE_OLD_SUBDIR       "/"
 159 #define BUNDLE_NEW_SUBDIR       "/Contents/MacOS/"
 160 #define BUNDLE_DIR_EXTENSION    ".bundle"
 161 #define BUNDLE_DEBUG_EXTENSION  "_debug"
 162 #define BUNDLE_ENTRY_POINT      "_start"
 163 #define BUNDLE_ENTRY_POINT2     "_prime"
 164
 165
 166 __BEGIN_DECLS
 167
 168 /*!
 169         @function SCDHandleInit
 170         @discussion Creates a new handle used to access the cached configuration
 171                 dictionary data.
 172         @result A new "cache" data handle.
 173  */
 174 SCDHandleRef    SCDHandleInit                   ();
 175
 176 /*!
 177         @function SCDHandleRelease
 178         @discussion Releases the specified configuration data handle. The dictionary
 179                 (or other CFType) associated with this handle will also be released
 180                 unless a call was previously made to CFRetain().
 181         @param handle The cache data handle to be released.
 182  */
 183 void            SCDHandleRelease                (SCDHandleRef           handle);
 184
 185 /*!
 186         @function SCDHandleGetInstance
 187         @discussion Returns the instance number associated with the specified
 188                 configuration handle.
 189         @param handle The cache data handle.
 190         @result The instance number associated with the specified handle.
 191  */
 192 int             SCDHandleGetInstance            (SCDHandleRef           handle);
 193
 194 /*!
 195         @function SCDHandleGetData
 196         @discussion Returns a reference to the data associated with the specified
 197                 configuration handle.
 198         @param handle The cache data handle.
 199         @result The CFType data associated with the specified handle.
 200  */
 201 CFPropertyListRef SCDHandleGetData              (SCDHandleRef           handle);
 202
 203 /*!
 204         @function SCDHandleSetData
 205         @discussion Returns a reference to the data associated with the specified
 206                 configuration handle.
 207         @param handle The cache data handle.
 208         @param data The CFType data to be associated with the handle.
 209  */
 210 void            SCDHandleSetData                (SCDHandleRef           handle,
 211                                                  CFPropertyListRef      data);
 212 /*!
 213         @function SCDOpen
 214         @discussion Initiates a connection with the configuration daemon.
 215         @param session A pointer to memory which will be filled with an SCDSessionRef
 216                 handle to be used for all subsequent requests to the server.
 217                 If a session cannot be established with the server, the contents of
 218                 memory pointed to by this parameter are undefined.
 219         @param name Pass a string which describes the name of the calling process or
 220                 plug-in name of the caller.
 221         @result A constant of type SCDStatus indicating the success (or failure) of
 222                 the call.
 223  */
 224 SCDStatus       SCDOpen                         (SCDSessionRef          *session,
 225                                                  CFStringRef            name);
 226
 227 /*!
 228         @function SCDClose
 229         @discussion Closes the specified session to the configuration daemon.  All
 230                 outstanding notification requests will be cancelled.
 231         @param session Pass a pointer to an SCDSessionRef handle which should be closed.
 232         @result A constant of type SCDStatus indicating the success (or failure) of
 233                 the call.
 234  */
 235 SCDStatus       SCDClose                        (SCDSessionRef          *session);
 236
 237 /*!
 238         @function SCDLock
 239         @discussion Locks access to the configuration "cache".  All other clients
 240                 attempting to access the "cache" will block. All change notifications
 241                 will be deferred until the lock is released.
 242         @param session Pass a SCDSessionRef handle which should be used for
 243                 communication with the server.
 244         @result A constant of type SCDStatus indicating the success (or failure) of
 245                 the call.
 246  */
 247 SCDStatus       SCDLock                         (SCDSessionRef          session);
 248
 249 /*!
 250         @function SCDUnlock
 251         @discussion Unlocks access to the configuration "cache".  Other clients will
 252                 be able to access the "cache". Any change notifications will be delivered.
 253         @param session Pass a SCDSessionRef handle which should be used for
 254                 communication with the server.
 255         @result A constant of type SCDStatus indicating the success (or failure) of
 256                 the call.
 257  */
 258 SCDStatus       SCDUnlock                       (SCDSessionRef          session);
 259
 260 /*!
 261         @function SCDList
 262         @discussion Returns an array of CFStringRefs representing the configuration "cache"
 263                 entries which match the specified pattern key.
 264         @param session Pass a SCDSessionRef handle which should be used for
 265                 communication with the server.
 266         @param key The string which must prefix those keys in the configuration "cache"
 267                 (if regexOptions is zero) or a regex(3) regular expression string which
 268                 will be used to match configuration "cache" (if regexOptions is kSCDRegexKey).
 269         @param regexOptions Pass a bitfield of type SCDKeyOption containing one or more
 270                 flags describing the pattern key.
 271         @param subKeys Pass a pointer to a CFArrayRef which will be set to a new
 272                 array of CFStringRefs's matching the provided key.
 273         @result A constant of type SCDStatus indicating the success (or failure) of
 274                 the call.
 275  */
 276 SCDStatus       SCDList                         (SCDSessionRef          session,
 277                                                  CFStringRef            key,
 278                                                  int                    regexOptions,
 279                                                  CFArrayRef             *subKeys);
 280
 281 /*!
 282         @function SCDAdd
 283         @discussion Creates a new entry in the configuration "cache" using the
 284                 specified key and data.  An error is returned if the key is already
 285                 defined in the dictionary.
 286         @param session Pass a SCDSessionRef handle which should be used for
 287                 communication with the server.
 288         @param key Pass a reference to the CFStringRef object to be created.
 289         @param handle Pass a reference to the SCDHandle object containing the data
 290                 to be associated with the specified key.
 291         @result A constant of type SCDStatus indicating the success (or failure) of
 292                 the call.
 293  */
 294 SCDStatus       SCDAdd                          (SCDSessionRef          session,
 295                                                  CFStringRef            key,
 296                                                  SCDHandleRef           handle);
 297
 298 /*!
 299         @function SCDAddSession
 300         @discussion Creates a new entry in the configuration "cache" using the
 301         specified key and data.  This entry will, unless updated by another
 302         session, automatically be removed when the session is closed.  An
 303         error is returned if the key is already defined in the dictionary.
 304
 305         @param session Pass a SCDSessionRef handle which should be used for
 306                 communication with the server.
 307         @param key Pass a reference to the CFStringRef object to be created.
 308         @param handle Pass a reference to the SCDHandle object containing the data
 309                 to be associated with the specified key.
 310         @result A constant of type SCDStatus indicating the success (or failure) of
 311                 the call.
 312  */
 313 SCDStatus       SCDAddSession                   (SCDSessionRef          session,
 314                                                  CFStringRef            key,
 315                                                  SCDHandleRef           handle);
 316
 317 /*!
 318         @function SCDGet
 319         @discussion Returns a handle to the configuration "cache" data that corresponds
 320                 to the specified key.
 321         @param session Pass a SCDSessionRef handle which should be used for
 322                 communication with the server.
 323         @param key Pass a reference to the CFStringRef object to be returned.
 324         @param handle Pass a pointer to a SCDHandleRef which will be set to a
 325                 new object containing the data associated with the specified key.
 326         @result A constant of type SCDStatus indicating the success (or failure) of
 327                 the call.
 328  */
 329 SCDStatus       SCDGet                          (SCDSessionRef          session,
 330                                                  CFStringRef            key,
 331                                                  SCDHandleRef           *handle);
 332
 333 /*!
 334         @function SCDSet
 335         @discussion Updates the entry in the configuration "cache" that corresponds to
 336                 the specified key with the provided data.  An error will be returned if
 337                 the data in the "cache" has been updated since the data handle was last
 338                 updated.
 339         @param session Pass the SCDSessionRef handle which should be used to communicate
 340                 with the server.
 341         @param key Pass a reference to the CFStringRef object to be updated.
 342         @param handle Pass a reference to the SCDHandle object containing the data
 343                 to be associated with the specified key.
 344         @result A constant of type SCDStatus indicating the success (or failure) of
 345                 the call.
 346  */
 347 SCDStatus       SCDSet                          (SCDSessionRef          session,
 348                                                  CFStringRef            key,
 349                                                  SCDHandleRef           handle);
 350
 351 /*!
 352         @function SCDRemove
 353         @discussion Removes the data from the configuration "cache" data which corresponds
 354                 to the specified key.
 355         @param session Pass a SCDSessionRef handle which should be used for
 356                 communication with the server.
 357         @param key Pass a reference to the CFStringRef object to be removed.
 358         @result A constant of type SCDStatus indicating the success (or failure) of
 359                 the call.
 360  */
 361 SCDStatus       SCDRemove                       (SCDSessionRef          session,
 362                                                  CFStringRef            key);
 363
 364 /*!
 365         @function SCDTouch
 366         @discussion Updates the instance number for the data in the configuration "cache"
 367                 associated with the specified key.  If the specified key does not exist
 368                 then a CFDate object will be associated with the key.  If the associated
 369                 data is already a CFDate object then the value will be updated.
 370         @param session Pass a SCDSessionRef handle which should be used for
 371                 communication with the server.
 372         @param key Pass a reference to the CFStringRef object to be updated.
 373         @result A constant of type SCDStatus indicating the success (or failure) of
 374                 the call.
 375  */
 376 SCDStatus       SCDTouch                        (SCDSessionRef          session,
 377                                                 CFStringRef             key);
 378
 379 /*
 380         @function SCDSnapshot
 381         @discussion Records the current state of configd's cache dictionary into the
 382                 /var/tmp/configd-cache file and configd's session dictionary into the
 383                 /var/tmp/configd-session file.
 384         @result A constant of type SCDStatus indicating the success (or failure) of
 385                 the call.
 386  */
 387 SCDStatus       SCDSnapshot                     (SCDSessionRef          session);
 388
 389 /*!
 390         @function SCDNotifierList
 391         @discussion Returns an array of CFStringRefs representing the system configuration
 392                 data entries being monitored for changes.
 393         @param session Pass a SCDSessionRef handle which should be used for
 394                 communication with the server.
 395         @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether
 396                 the specific configuration cache key patterns are to be returned or those
 397                 based on regex(3) pattern strings.
 398         @param notifierKeys Pass a pointer to a CFArrayRef which will be set to a new
 399                 array of CFStringRef's being monitored.
 400         @result A constant of type SCDStatus indicating the success (or failure) of
 401                 the call.
 402  */
 403 SCDStatus       SCDNotifierList                 (SCDSessionRef          session,
 404                                                  int                    regexOptions,
 405                                                  CFArrayRef             *notifierKeys);
 406
 407 /*!
 408         @function SCDNotifierAdd
 409         @discussion Adds the specified key to the list of system configuration
 410                 data entries which are being monitored for changes.
 411         @param session Pass a SCDSessionRef handle which should be used for
 412                 communication with the server.
 413         @param key Pass a reference to the CFStringRef object to be monitored.
 414         @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether
 415                 the key is for a specific configuration cache key or if it consists
 416                 of a regex(3) pattern string.
 417         @result A constant of type SCDStatus indicating the success (or failure) of
 418                 the call.
 419  */
 420 SCDStatus       SCDNotifierAdd                  (SCDSessionRef          session,
 421                                                  CFStringRef            key,
 422                                                  int                    regexOptions);
 423
 424 /*!
 425         @function SCDNotifierRemove
 426         @discussion Removes the specified key from the list of system configuration
 427                 data entries which are being monitored for changes.
 428         @param session Pass a SCDSessionRef handle which should be used for
 429                 communication with the server.
 430         @param key Pass a reference to the CFStringRef object which should not be monitored.
 431         @param regexOptions Pass a bitfield of type SCDKeyOption which specifies whether
 432                 the key is for a specific configuration cache key or if it consists
 433                 of a regex(3) pattern string.
 434         @result A constant of type SCDStatus indicating the success (or failure) of
 435                 the call.
 436  */
 437 SCDStatus       SCDNotifierRemove               (SCDSessionRef          session,
 438                                                  CFStringRef            key,
 439                                                  int                    regexOptions);
 440
 441 /*!
 442         @function SCDNotifierGetChanges
 443         @discussion Returns an array of CFStringRefs representing the monitored system
 444                 configuration data entries which have changed since this function
 445                 was last called.
 446         @param session Pass a SCDSessionRef handle which should be used for
 447                 communication with the server.
 448         @param notifierKeys Pass a pointer to a CFArrayRef which will be set to a new
 449                 array of CFStringRef's being monitored.
 450         @result A constant of type SCDStatus indicating the success (or failure) of
 451                 the call.
 452  */
 453 SCDStatus       SCDNotifierGetChanges           (SCDSessionRef          session,
 454                                                  CFArrayRef             *notifierKeys);
 455
 456 /*!
 457         @function SCDNotifierWait
 458         @discussion Waits for a change to be made to a system configuration data
 459                 entry associated with the current sessions notifier keys.
 460
 461         Note: this function is not valid for "configd" plug-ins.
 462
 463         @param session Pass a SCDSessionRef handle which should be used for
 464                 communication with the server.
 465         @result A constant of type SCDStatus indicating the success (or failure) of
 466                 the call.
 467  */
 468 SCDStatus       SCDNotifierWait                 (SCDSessionRef          session);
 469
 470 /*!
 471         @function SCDNotifierInformViaCallback
 472         @discussion Requests that the specified function be called whenever a change
 473                 has been detected to one of the system configuration data entries
 474                 associated with the current sessions notifier keys.
 475
 476         The callback function will be called with two arguments, session and arg, which
 477         correspond to the current session and the provided argument.
 478         The function should return a boolean value indicating whether an
 479         error occurred during execution of the callback.
 480
 481         Note: if the calling application is based on the CFRunLoop() then an additional
 482         run loop source will be added for the notification.
 483         Applications which are not based on the CFRunLoop() will have a separate thread
 484         started to wait for changes.
 485         In either case, the additional run loop source and/or thread will terminate if
 486         the notification is cancelled or if the callback indicates that an error was
 487         detected.
 488
 489         Note: this function is not valid for "configd" plug-ins.
 490
 491         @param session Pass a SCDSessionRef handle which should be used for
 492                 communication with the server.
 493         @param func Pass a pointer to the callback applier function to call when a
 494                 monitored cache entry is changed.  If this parameter is not a pointer to
 495                 a function of the correct prototype (SCDCallbackRoutine_t), the behavior
 496                 is undefined.
 497         @result A constant of type SCDStatus indicating the success (or failure) of
 498                 the call.
 499  */
 500 SCDStatus       SCDNotifierInformViaCallback    (SCDSessionRef          session,
 501                                                  SCDCallbackRoutine_t   func,
 502                                                  void                   *arg);
 503
 504 /*!
 505         @function SCDNotifierInformViaMachPort
 506         @discussion Allocates a mach port which can be used to detect changes to
 507                 one of the system configuration data entries associated with the
 508                 current sessions notifier keys. When a change is detected, an
 509                 empty (no data) mach message with the specified identifier will
 510                 be delivered to the calling application via the allocated port.
 511
 512         @param session Pass a SCDSessionRef handle which should be used for
 513                 communication with the server.
 514         @param msgid Pass a mach message ID to be included with any notifications.
 515         @param port Pass a pointer to a mach port.  Upon return, port will be filled
 516                 with the mach port which will be used for any notifications.
 517         @result A constant of type SCDStatus indicating the success (or failure) of
 518                 the call.
 519  */
 520 SCDStatus       SCDNotifierInformViaMachPort    (SCDSessionRef          session,
 521                                                  mach_msg_id_t          msgid,
 522                                                  mach_port_t            *port);
 523
 524 /*!
 525         @function SCDNotifierInformViaFD
 526         @discussion Allocates a file descriptor which can be used to detect changes
 527                 to one of the system configuration data entries associated with the
 528                 current sessions notifier keys. When a change is detected, the
 529                 specified identifier (4 bytes) will be delivered to the calling
 530                 application via the allocated file descriptor.
 531
 532         @param session Pass a SCDSessionRef handle which should be used for
 533                 communication with the server.
 534         @param identifier Pass an (4 byte) integer identifer which be used for any
 535                 notifications.
 536         @param fd Pass a pointer to a file descriptor.  Upon return, fd will be filled
 537                 with the file descriptor which will be used for any notifications.
 538         @result A constant of type SCDStatus indicating the success (or failure) of
 539                 the call.
 540  */
 541 SCDStatus       SCDNotifierInformViaFD          (SCDSessionRef          session,
 542                                                  int32_t                identifier,
 543                                                  int                    *fd);
 544
 545 /*!
 546         @function SCDNotifierInformViaSignal
 547         @discussion Requests that the specified BSD signal be sent to the process
 548                 with the indicated process id whenever a change has been detected
 549                 to one of the system configuration data entries associated with the
 550                 current sessions notifier keys.
 551
 552                 Note: this function is not valid for "configd" plug-ins.
 553
 554         @param session Pass a SCDSessionRef handle which should be used for
 555                 communication with the server.
 556         @param pid Pass a UNIX proces ID which should be signalled for any notifications.
 557         @param sig Pass a signal number to be used.
 558         @result A constant of type SCDStatus indicating the success (or failure) of
 559                 the call.
 560  */
 561 SCDStatus       SCDNotifierInformViaSignal      (SCDSessionRef          session,
 562                                                  pid_t                  pid,
 563                                                  int                    sig);
 564
 565 /*!
 566         @function SCDNotifierCancel
 567         @discussion Cancels all outstanding notification delivery request for this
 568                 session.
 569
 570         @param session Pass a SCDSessionRef handle which should be used for
 571                 communication with the server.
 572         @result A constant of type SCDStatus indicating the success (or failure) of
 573                 the call.
 574  */
 575 SCDStatus       SCDNotifierCancel               (SCDSessionRef          session);
 576
 577 /*!
 578         @function SCDOptionGet
 579         @discussion Returns the value associated with the specified option.
 580         @param session Pass a SCDSessionRef handle of the option of interest (or
 581                 NULL for the global option setting).
 582         @param option Pass the SCDOption of interest.
 583         @result The current value of the specified option.
 584  */
 585 int             SCDOptionGet                    (SCDSessionRef          session,
 586                                                  int                    option);
 587
 588 /*!
 589         @function SCDOptionSet
 590         @discussion Sets the value associated with the specified option.
 591         @param session Pass a SCDSessionRef handle for the option to be set (or
 592                 NULL for the global option settings).
 593         @param option Pass the SCDOption to be updated.
 594         @param value Pass the new value for the option.
 595         @result The current value of the specified option.
 596  */
 597 void            SCDOptionSet                    (SCDSessionRef          session,
 598                                                  int                    option,
 599                                                  int                    value);
 600
 601 /*!
 602         @function SCDSessionLog
 603         @discussion Issues a log and/or debug message.
 604         @param session Pass a SCDSessionRef handle for the current session..
 605         @param level Pass a syslog(3) logging priority.
 606
 607         Note: LOG_DEBUG messages will not be issued if the verbose option has not been enabled.
 608         @param formatString Pass the CF format string
 609         @result The specified message will be logged.
 610  */
 611 void            SCDSessionLog                   (SCDSessionRef          session,
 612                                                  int                    level,
 613                                                  CFStringRef            formatString,
 614                                                  ...);
 615
 616 /*!
 617         @function SCDLog
 618         @discussion Issues a log and/or debug message.
 619         @param level Pass a syslog(3) logging priority.
 620         @param formatString Pass the CF format string
 621         @result The specified message will be logged.
 622  */
 623 void            SCDLog                          (int                    level,
 624                                                  CFStringRef            formatString,
 625                                                  ...);
 626
 627 const char *    SCDError                        (SCDStatus              status);
 628
 629 __END_DECLS
 630
 631 #endif /* _SCD_H */