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