SystemConfiguration.fproj/SCDPlugin.h

   1 /*
   2  * Copyright (c) 2000-2004, 2006, 2017 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 kSCBundleEnabledKey
  47  */
  48 #define kSCBundleEnabledKey             CFSTR("Enabled")
  49
  50
  51 /*
  52         @defined kSCBundleVerboseKey
  53  */
  54 #define kSCBundleVerboseKey             CFSTR("Verbose")
  55
  56
  57 /*
  58         @defined kSCBundleIsBuiltinKey
  59  */
  60 #define kSCBundleIsBuiltinKey           CFSTR("Builtin")
  61
  62
  63 /*!
  64         @typedef SCDynamicStoreBundleLoadFunction
  65         @discussion Type of the load() initialization function that will be
  66                 called when a plug-in is loaded.  This function is called
  67                 before calling the start() function and can be uesd to
  68                 initialize any variables, open any sessions with "configd",
  69                 and register any needed notifications.
  70         @param bundle The CFBundle being loaded.
  71         @param bundleVerbose A boolean value indicating whether verbose logging has
  72                 been enabled for this bundle.
  73  */
  74 typedef void    SCDynamicStoreBundleLoadFunction        (CFBundleRef    bundle,
  75                                                          Boolean        bundleVerbose);
  76
  77 /*!
  78         @typedef SCDynamicStoreBundleStartFunction
  79         @discussion Type of the start() initialization function that will be
  80                 called after all plug-ins have been loaded and their load()
  81                 functions have been called.  This function can initialize
  82                 variables, open sessions with "configd", and register any
  83                 needed notifications.
  84         @param bundleName The name of the plug-in / bundle.
  85         @param bundlePath The path name associated with the plug-in / bundle.
  86  */
  87 typedef void    SCDynamicStoreBundleStartFunction       (const char     *bundleName,
  88                                                          const char     *bundlePath);
  89
  90 /*!
  91         @typedef SCDynamicStoreBundlePrimeFunction
  92         @discussion Type of the prime() initialization function that will be
  93                 called after all plug-ins have executed their start() function but
  94                 before the main plug-in run loop is started.  This function should
  95                 be used to initialize any configuration information and/or state
  96                 in the store.
  97  */
  98 typedef void    SCDynamicStoreBundlePrimeFunction       (void);
  99
 100
 101 /*!
 102         @typedef SCDynamicStoreBundleStopFunction
 103         @discussion Type of the stop() termination function that will be
 104                 called when configd has been requested to shut down.
 105         @param stopRls A run loop source which should be signaled using
 106                 CFRunLoopSourceSignal() when the plugin has been shut down.
 107
 108         Note: a plugin can delay shut down of the daemon by no more than
 109                 30 seconds.
 110  */
 111 typedef void    SCDynamicStoreBundleStopFunction        (CFRunLoopSourceRef     stopRls);
 112
 113
 114 /*!
 115         @typedef SCDPluginExecCallBack
 116         @discussion Type of the callback function used when a child process
 117                 started by a plug-in has exited.
 118         @param pid The process id of the child which has exited.
 119         @param status The exit status of the child which has exited.
 120         @param rusage A summary of the resources used by the child process
 121                 and all its children.
 122         @param context The callback argument specified on the call
 123                 to _SCDPluginExecCommand().
 124  */
 125 typedef void    (*SCDPluginExecCallBack)                (pid_t          pid,
 126                                                          int            status,
 127                                                          struct rusage  *rusage,
 128                                                          void           *context);
 129
 130
 131 /*!
 132         @typedef SCDPluginExecSetup
 133         @discussion Type of the setup function used when a child process
 134                 is being started.
 135         @param pid The process id of the child, zero for the child process.
 136         @param setupContext The setup argument specified on the call
 137                 to _SCDPluginExecCommand2().
 138  */
 139 typedef void    (*SCDPluginExecSetup)                   (pid_t          pid,
 140                                                          void           *setupContext);
 141
 142
 143 __BEGIN_DECLS
 144
 145 /*!
 146         @function _SCDPluginExecCommand
 147         @discussion Starts a child process.
 148         @param callout The function to be called when the child
 149                 process exits.  A NULL value can be specified if no
 150                 callouts are desired.
 151         @param context A argument which will be passed
 152                 to the callout function.
 153         @param uid The desired user id of the child process.
 154         @param gid The desired group id of the child process.
 155         @param path The command to be executed.
 156         @param argv The arguments to be passed to the child process.
 157         @result The process ID of the child.
 158  */
 159 pid_t
 160 _SCDPluginExecCommand           (
 161                                 SCDPluginExecCallBack   callout,
 162                                 void                    *context,
 163                                 uid_t                   uid,
 164                                 gid_t                   gid,
 165                                 const char              *path,
 166                                 char * const            argv[]
 167                                 );
 168
 169 /*!
 170         @function _SCDPluginExecCommand2
 171         @discussion Starts a child process.
 172         @param callout The function to be called when the child
 173                 process exits.  A NULL value can be specified if no
 174                 callouts are desired.
 175         @param context An argument which will be passed
 176                 to the callout function.
 177         @param uid The desired user id of the child process.
 178         @param gid The desired group id of the child process.
 179         @param path The command to be executed.
 180         @param argv The arguments to be passed to the child process.
 181         @param setup A pointer to a function which, if specified, will
 182                 be called after the call to fork(2) but before the call
 183                 to exec(3).
 184                 The function will be called in both the parent and child
 185                 processes.
 186                 The process ID returned by fork(2) will be passed as
 187                 an argument to this function (i.e. non-zero in the parent,
 188                 zero in the child).
 189
 190                 Note: the setup function is responsibile for establishing
 191                 (and closing) all file descriptors that are (not) needed
 192                 by the child process.
 193         @param setupContext An argument which will be passed
 194                 to the setup function.
 195         @result The process ID of the child.
 196  */
 197 pid_t
 198 _SCDPluginExecCommand2          (
 199                                 SCDPluginExecCallBack   callout,
 200                                 void                    *context,
 201                                 uid_t                   uid,
 202                                 gid_t                   gid,
 203                                 const char              *path,
 204                                 char * const            argv[],
 205                                 SCDPluginExecSetup      setup,
 206                                 void                    *setupContext
 207                                 );
 208
 209 __END_DECLS
 210
 211 #endif /* _SCDPLUGIN_H */