1/* 2 * Copyright (c) 2000-2004, 2006 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 */ 74typedef 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 */ 87typedef 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 */ 98typedef 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 */ 111typedef 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 */ 125typedef 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 */ 139typedef 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 */ 159pid_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 */ 197pid_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 */ 212