SystemConfiguration.fproj/SCDPlugin.h

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