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