SystemConfiguration.fproj/SCDPlugin.h

   1 /*
   2  * Copyright (c) 2000-2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SCDPLUGIN_H
  25 #define _SCDPLUGIN_H
  26
  27 #include <sys/cdefs.h>
  28 #include <sys/types.h>
  29 #include <sys/time.h>
  30 #include <sys/resource.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32
  33
  34 /*!
  35         @header SCDPlugin
  36  */
  37
  38
  39 /*
  40         @defined kSCBundleRequiresKey
  41  */
  42 #define kSCBundleRequiresKey            CFSTR("Requires")
  43
  44
  45 /*
  46         @defined kSCBundleVerboseKey
  47  */
  48 #define kSCBundleVerboseKey             CFSTR("Verbose")
  49
  50
  51 /*
  52         @defined kSCBundleIsBuiltinKey
  53  */
  54 #define kSCBundleIsBuiltinKey           CFSTR("Builtin")
  55
  56
  57 /*!
  58         @typedef SCDynamicStoreBundleLoadFunction
  59         @discussion Type of the load() initialization function that will be
  60                 called when a plug-in is loaded.  This function is called
  61                 before calling the start() function and can be uesd to
  62                 initialize any variables, open any sessions with "configd",
  63                 and register any needed notifications.
  64         @param bundle The CFBundle being loaded.
  65         @param bundleVerbose A boolean value indicating whether verbose logging has
  66                 been enabled for this bundle.
  67  */
  68 typedef void    (*SCDynamicStoreBundleLoadFunction)     (CFBundleRef    bundle,
  69                                                          Boolean        bundleVerbose);
  70
  71 /*!
  72         @typedef SCDynamicStoreBundleStartFunction
  73         @discussion Type of the start() initialization function that will be
  74                 called after all plug-ins have been loaded and their load()
  75                 functions have been called.  This function can initialize
  76                 variables, open sessions with "configd", and register any
  77                 needed notifications.
  78         @param bundleName The name of the plug-in / bundle.
  79         @param bundlePath The path name associated with the plug-in / bundle.
  80  */
  81 typedef void    (*SCDynamicStoreBundleStartFunction)    (const char     *bundleName,
  82                                                          const char     *bundlePath);
  83
  84 /*!
  85         @typedef SCDynamicStoreBundlePrimeFunction
  86         @discussion Type of the prime() initialization function that will be
  87                 called after all plug-ins have executed their start() function but
  88                 before the main plug-in run loop is started.  This function should
  89                 be used to initialize any configuration information and/or state
  90                 in the store.
  91  */
  92 typedef void    (*SCDynamicStoreBundlePrimeFunction)    ();
  93
  94
  95 /*!
  96         @typedef SCDynamicStoreBundleStopFunction
  97         @discussion Type of the stop() termination function that will be
  98                 called when configd has been requested to shut down.
  99         @param stopRls A run loop source which should be signaled using
 100                 CFRunLoopSourceSignal() when the plugin has been shut down.
 101
 102         Note: a plugin can delay shut down of the daemon by no more than
 103                 30 seconds.
 104  */
 105 typedef void    (*SCDynamicStoreBundleStopFunction)     (CFRunLoopSourceRef     stopRls);
 106
 107
 108 /*!
 109         @typedef SCDPluginExecCallBack
 110         @discussion Type of the callback function used when a child process
 111                 started by a plug-in has exited.
 112         @param pid The process id of the child which has exited.
 113         @param status The exit status of the child which has exited.
 114         @param rusage A summary of the resources used by the child process
 115                 and all its children.
 116         @param context The callback argument specified on the call
 117                 to _SCDPluginExecCommand().
 118  */
 119 typedef void    (*SCDPluginExecCallBack)                (pid_t          pid,
 120                                                          int            status,
 121                                                          struct rusage  *rusage,
 122                                                          void           *context);
 123
 124
 125 /*!
 126         @typedef SCDPluginExecSetup
 127         @discussion Type of the setup function used when a child process
 128                 is being started.
 129         @param pid The process id of the child, zero for the child process.
 130         @param setupContext The setup argument specified on the call
 131                 to _SCDPluginExecCommand2().
 132  */
 133 typedef void    (*SCDPluginExecSetup)                   (pid_t          pid,
 134                                                          void           *setupContext);
 135
 136
 137 __BEGIN_DECLS
 138
 139 /*!
 140         @function _SCDPluginExecCommand
 141         @discussion Starts a child process.
 142         @param callout The function to be called when the child
 143                 process exits.  A NULL value can be specified if no
 144                 callouts are desired.
 145         @param context A argument which will be passed
 146                 to the callout function.
 147         @param uid The desired user id of the child process.
 148         @param gid The desired group id of the child process.
 149         @param path The command to be executed.
 150         @param argv The arguments to be passed to the child process.
 151         @result The process ID of the child.
 152  */
 153 pid_t
 154 _SCDPluginExecCommand           (
 155                                 SCDPluginExecCallBack   callout,
 156                                 void                    *context,
 157                                 uid_t                   uid,
 158                                 gid_t                   gid,
 159                                 const char              *path,
 160                                 char * const            argv[]
 161                                 );
 162
 163 /*!
 164         @function _SCDPluginExecCommand2
 165         @discussion Starts a child process.
 166         @param callout The function to be called when the child
 167                 process exits.  A NULL value can be specified if no
 168                 callouts are desired.
 169         @param context An argument which will be passed
 170                 to the callout function.
 171         @param uid The desired user id of the child process.
 172         @param gid The desired group id of the child process.
 173         @param path The command to be executed.
 174         @param argv The arguments to be passed to the child process.
 175         @param setup A pointer to a function which, if specified, will
 176                 be called after the call to fork(2) but before the call
 177                 to exec(3).
 178                 The function will be called in both the parent and child
 179                 processes.
 180                 The process ID returned by fork(2) will be passed as
 181                 an argument to this function (i.e. non-zero in the parent,
 182                 zero in the child).
 183
 184                 Note: the setup function is responsibile for establishing
 185                 (and closing) all file descriptors that are (not) needed
 186                 by the child process.
 187         @param setupContext An argument which will be passed
 188                 to the setup function.
 189         @result The process ID of the child.
 190  */
 191 pid_t
 192 _SCDPluginExecCommand2          (
 193                                 SCDPluginExecCallBack   callout,
 194                                 void                    *context,
 195                                 uid_t                   uid,
 196                                 gid_t                   gid,
 197                                 const char              *path,
 198                                 char * const            argv[],
 199                                 SCDPluginExecSetup      setup,
 200                                 void                    *setupContext
 201                                 );
 202
 203 __END_DECLS
 204
 205 #endif /* _SCDPLUGIN_H */