nsIGenericFactory.h@ 103977

Last change on this file since 103977 was 63379, checked in by vboxsync, 8 years ago
xpcom18a4: warnings (gcc)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 22.7 KB

Line
1	/* -- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -- */
2	/* *** BEGIN LICENSE BLOCK ***
3	* Version: MPL 1.1/GPL 2.0/LGPL 2.1
4	*
5	* The contents of this file are subject to the Mozilla Public License Version
6	* 1.1 (the "License"); you may not use this file except in compliance with
7	* the License. You may obtain a copy of the License at
8	* http://www.mozilla.org/MPL/
9	*
10	* Software distributed under the License is distributed on an "AS IS" basis,
11	* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12	* for the specific language governing rights and limitations under the
13	* License.
14	*
15	* The Original Code is mozilla.org code.
16	*
17	* The Initial Developer of the Original Code is
18	* Netscape Communications Corporation.
19	* Portions created by the Initial Developer are Copyright (C) 1998
20	* the Initial Developer. All Rights Reserved.
21	*
22	* Contributor(s):
23	*
24	* Alternatively, the contents of this file may be used under the terms of
25	* either of the GNU General Public License Version 2 or later (the "GPL"),
26	* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27	* in which case the provisions of the GPL or the LGPL are applicable instead
28	* of those above. If you wish to allow use of your version of this file only
29	* under the terms of either the GPL or the LGPL, and not to allow others to
30	* use your version of this file under the terms of the MPL, indicate your
31	* decision by deleting the provisions above and replace them with the notice
32	* and other provisions required by the GPL or the LGPL. If you do not delete
33	* the provisions above, a recipient may use your version of this file under
34	* the terms of any one of the MPL, the GPL or the LGPL.
35	*
36	* *** END LICENSE BLOCK *** */
37
38	#ifndef nsIGenericFactory_h___
39	#define nsIGenericFactory_h___
40
41	#include "nsIFactory.h"
42	#include "nsIModule.h"
43	#include "nsIClassInfo.h"
44	#ifdef HAVE_DEPENDENT_LIBS
45	#include "dependentLibs.h"
46	#endif
47
48	// {3bc97f01-ccdf-11d2-bab8-b548654461fc}
49	#define NS_GENERICFACTORY_CID \
50	{ 0x3bc97f01, 0xccdf, 0x11d2, \
51	{ 0xba, 0xb8, 0xb5, 0x48, 0x65, 0x44, 0x61, 0xfc } }
52
53	// {3bc97f00-ccdf-11d2-bab8-b548654461fc}
54	#define NS_IGENERICFACTORY_IID \
55	{ 0x3bc97f00, 0xccdf, 0x11d2, \
56	{ 0xba, 0xb8, 0xb5, 0x48, 0x65, 0x44, 0x61, 0xfc } }
57
58	#define NS_GENERICFACTORY_CONTRACTID "@mozilla.org/generic-factory;1"
59	#define NS_GENERICFACTORY_CLASSNAME "Generic Factory"
60
61	struct nsModuleComponentInfo; // forward declaration
62
63	/**
64	* Provides a Generic nsIFactory implementation that can be used by
65	* DLLs with very simple factory needs.
66	*/
67	class nsIGenericFactory : public nsIFactory {
68	public:
69	NS_DEFINE_STATIC_IID_ACCESSOR(NS_IGENERICFACTORY_IID)
70
71	NS_IMETHOD SetComponentInfo(const nsModuleComponentInfo *info) = 0;
72	NS_IMETHOD GetComponentInfo(const nsModuleComponentInfo **infop) = 0;
73	};
74
75	NS_COM nsresult
76	NS_NewGenericFactory(nsIGenericFactory **result,
77	const nsModuleComponentInfo *info);
78
79
80	/ Component Callbacks /
81
82	/**
83	* NSConstructorProcPtr
84	*
85	* This function will be used by the generic factory to create an
86	* instance of the given CID.
87	*
88	* @param aOuter : Pointer to a component that wishes to be aggregated
89	* in the resulting instance. This will be nsnull if no
90	* aggregation is requested.
91	* @param iid : The IID of the interface being requested in
92	* the component which is being currently created.
93	* @param result : [out] Pointer to the newly created instance, if successful.
94	*
95	* @return NS_OK Component successfully created and the interface
96	* being requested was successfully returned in result.
97	* NS_NOINTERFACE Interface not accessible.
98	* NS_ERROR_NO_AGGREGATION if an 'outer' object is supplied, but the
99	* component is not aggregatable.
100	* NS_ERROR* Method failure.
101	**/
102	typedef NS_CALLBACK(NSConstructorProcPtr)(nsISupports *aOuter,
103	REFNSIID aIID,
104	void **aResult);
105
106	/**
107	* NSRegisterSelfProcPtr
108	*
109	* One time registration call back. Allows you to perform registration
110	* specific activity like adding yourself to a category.
111	*
112	* @param aCompMgr : The global component manager
113	* @param aFile : Component File. This file must have an associated
114	* loader and export the required symbols which this
115	* loader defines.
116	* @param aLoaderStr : Opaque loader specific string. This value is
117	* passed into the nsIModule's registerSelf
118	* callback and must be fowarded unmodified when
119	* registering factories via their location.
120	* @param aType : Component Type of CID aClass. This value is
121	* passed into the nsIModule's registerSelf
122	* callback and must be fowarded unmodified when
123	* registering factories via their location.
124	* @param aInfo : Pointer to array of nsModuleComponentInfo
125	*
126	* @param aInfo
127	* @return NS_OK Registration was successful.
128	* NS_ERROR* Method failure.
129	**/
130	typedef NS_CALLBACK(NSRegisterSelfProcPtr)(nsIComponentManager *aCompMgr,
131	nsIFile *aPath,
132	const char *aLoaderStr,
133	const char *aType,
134	const nsModuleComponentInfo *aInfo);
135
136	/**
137	* NSUnregisterSelfProcPtr
138	*
139	* One time unregistration call back. Allows you to perform unregistration
140	* specific activity like removing yourself from a category.
141	*
142	* @param aCompMgr : The global component manager
143	* @param aFile : Component File. This file must have an associated
144	* loader and export the required symbols which this
145	* loader defines.
146	* @param aLoaderStr : Opaque loader specific string. This value is
147	* passed into the nsIModule's registerSelf
148	* callback and must be fowarded unmodified when
149	* registering factories via their location
150	* @param aInfo : Pointer to array of nsModuleComponentInfo
151	*
152	* @param aInfo
153	* @return NS_OK Registration was successful.
154	* NS_ERROR* Method failure.
155
156	**/
157	typedef NS_CALLBACK(NSUnregisterSelfProcPtr)(nsIComponentManager *aCompMgr,
158	nsIFile *aPath,
159	const char *aLoaderStr,
160	const nsModuleComponentInfo *aInfo);
161
162	/**
163	* NSFactoryDestructorProcPtr
164	*
165	* This function will be called when the factory is being destroyed.
166	*
167	**/
168	typedef NS_CALLBACK(NSFactoryDestructorProcPtr)(void);
169
170
171	/**
172	* NSGetInterfacesProcPtr
173	*
174	* This function is used to implement class info.
175	*
176	* Get an ordered list of the interface ids that instances of the class
177	* promise to implement. Note that nsISupports is an implicit member
178	* of any such list and need not be included.
179	*
180	* Should set count = 0 and array = null and return NS_OK if getting the
181	* list is not supported.
182	*
183	* @see nsIClassInfo.idl
184	**/
185	typedef NS_CALLBACK(NSGetInterfacesProcPtr)(PRUint32 *countp,
186	nsIID* **array);
187
188	/**
189	* NSGetLanguageHelperProcPtr
190	*
191	* This function is used to implement class info.
192	*
193	* Get a language mapping specific helper object that may assist in using
194	* objects of this class in a specific lanaguage. For instance, if asked
195	* for the helper for nsIProgrammingLanguage::JAVASCRIPT this might return
196	* an object that can be QI'd into the nsIXPCScriptable interface to assist
197	* XPConnect in supplying JavaScript specific behavior to callers of the
198	* instance object.
199	*
200	* @see: nsIClassInfo.idl, nsIProgrammingLanguage.idl
201	*
202	* Should return null if no helper available for given language.
203	**/
204	typedef NS_CALLBACK(NSGetLanguageHelperProcPtr)(PRUint32 language,
205	nsISupports **helper);
206
207	/**
208	* nsModuleComponentInfo
209	*
210	* Use this type to define a list of module component info to pass to
211	* NS_NewGenericModule.
212	*
213	* @param mDescription : Class Name of given object
214	* @param mCID : CID of given object
215	* @param mContractID : Contract ID of given object
216	* @param mConstructor : Constructor of given object
217	* @param mRegisterSelfProc : (optional) Registration Callback
218	* @param mUnregisterSelfProc : (optional) Unregistration Callback
219	* @param mFactoryDestructor : (optional) Destruction Callback
220	* @param mGetInterfacesProc : (optional) Interfaces Callback
221	* @param mGetLanguageHelperProc : (optional) Language Helper Callback
222	* @param mClassInfoGlobal : (optional) Global Class Info of given object
223	* @param mFlags : (optional) Class Info Flags @see nsIClassInfo
224	*
225	* E.g.:
226	* static nsModuleComponentInfo components[] = { ... };
227	*
228	* See xpcom/sample/nsSampleModule.cpp for more info.
229	*/
230	struct nsModuleComponentInfo {
231	const char* mDescription;
232	nsCID mCID;
233	const char* mContractID;
234	NSConstructorProcPtr mConstructor;
235	NSRegisterSelfProcPtr mRegisterSelfProc;
236	NSUnregisterSelfProcPtr mUnregisterSelfProc;
237	NSFactoryDestructorProcPtr mFactoryDestructor;
238	NSGetInterfacesProcPtr mGetInterfacesProc;
239	NSGetLanguageHelperProcPtr mGetLanguageHelperProc;
240	nsIClassInfo ** mClassInfoGlobal;
241	PRUint32 mFlags;
242	};
243
244
245	/ Module Callbacks /
246
247
248	/**
249	* nsModuleConstructorProc
250	*
251	* This function is called when the module is first being constructed.
252	* @param self module which is being constructed.
253	*
254	* @return NS_OK Construction successful.
255	* NS_ERROR* Method failure which will result in module not being
256	* loaded.
257	**/
258	typedef nsresult (PR_CALLBACK nsModuleConstructorProc) (nsIModule self);
259
260
261	/**
262	* nsModuleDestructorProc
263	*
264	* This function is called when the module is being destroyed.
265	* @param self module which is being destroyed.
266	*
267	**/
268	typedef void (PR_CALLBACK nsModuleDestructorProc) (nsIModule self);
269
270	/**
271	* nsModuleInfo
272	*
273	* Use this structure to define meta-information about the module
274	* itself, including the name, its components, and an optional
275	* module-level initialization or shutdown routine.
276	*
277	* @param mVersion : Module Info Version
278	* @param mModuleName : Module Name
279	* @param mComponents : Array of Components
280	* @param mCount : Count of mComponents
281	* @param mCtor : Module user defined constructor
282	* @param mDtor : Module user defined destructor
283	* @param mLibraryDependencies : array of library which this module is
284	* dependent on.
285	*
286	**/
287
288	struct nsModuleInfo {
289	PRUint32 mVersion;
290	const char* mModuleName;
291	const nsModuleComponentInfo* mComponents;
292	PRUint32 mCount;
293	nsModuleConstructorProc mCtor;
294	nsModuleDestructorProc mDtor;
295	const char** mLibraryDependencies;
296	};
297
298	/**
299	* Rev this if you change the nsModuleInfo, and are worried about
300	* binary compatibility. (Ostensibly fix NS_NewGenericModule2() to deal
301	* with older rev's at the same time.)
302	*/
303	#define NS_MODULEINFO_VERSION 0x00015000UL // 1.5
304
305	/**
306	* Create a new generic module. Use the NS_IMPL_NSGETMODULE macro, or
307	* one of its relatives, rather than using this directly.
308	*/
309	NS_COM nsresult
310	NS_NewGenericModule2(nsModuleInfo info, nsIModule *result);
311
312	/**
313	* Obsolete. Use NS_NewGenericModule2() instead.
314	*/
315	NS_COM nsresult
316	NS_NewGenericModule(const char* moduleName,
317	PRUint32 componentCount,
318	nsModuleComponentInfo* components,
319	nsModuleDestructorProc dtor,
320	nsIModule* *result);
321
322	#if defined(XPCOM_TRANSLATE_NSGM_ENTRY_POINT)
323	# define NS_MODULEINFO nsModuleInfo
324	# define NSMODULEINFO(_name) _name##_gModuleInfo
325	# define NSGETMODULE_ENTRY_POINT(_info)
326	# define NSDEPENDENT_LIBS(_name) const char* _name##_gDependlibs[]={DEPENDENT_LIBS "\0"};
327	# define NSDEPENDENT_LIBS_NAME(_name) _name##_gDependlibs
328	#else
329	# define NS_MODULEINFO static nsModuleInfo
330	# define NSMODULEINFO(_name) gModuleInfo
331	# define NSDEPENDENT_LIBS(_name) static const char* gDependlibs[]={DEPENDENT_LIBS "\0"};
332	# define NSDEPENDENT_LIBS_NAME(_name) gDependlibs
333	# define NSGETMODULE_ENTRY_POINT(_info) \
334	extern "C" NS_EXPORT nsresult \
335	NSGetModule(nsIComponentManager *servMgr, \
336	nsIFile* location, \
337	nsIModule** result) \
338	{ \
339	(void)servMgr; \
340	(void)location; \
341	return NS_NewGenericModule2(&(_info), result); \
342	}
343	#endif
344
345	/**
346	* Ease of use Macros which define NSGetModule for your component.
347	* See xpcom/sample/nsSampleModule.cpp for more info.
348	*
349	**/
350
351	#define NS_IMPL_NSGETMODULE(_name, _components) \
352	NS_IMPL_NSGETMODULE_WITH_CTOR_DTOR(_name, _components, nsnull, nsnull)
353
354	#define NS_IMPL_NSGETMODULE_WITH_CTOR(_name, _components, _ctor) \
355	NS_IMPL_NSGETMODULE_WITH_CTOR_DTOR(_name, _components, _ctor, nsnull)
356
357	#define NS_IMPL_NSGETMODULE_WITH_DTOR(_name, _components, _dtor) \
358	NS_IMPL_NSGETMODULE_WITH_CTOR_DTOR(_name, _components, nsnull, _dtor)
359
360	#ifndef DEPENDENT_LIBS
361
362	#define NS_IMPL_NSGETMODULE_WITH_CTOR_DTOR(_name, _components, _ctor, _dtor) \
363	NS_MODULEINFO NSMODULEINFO(_name) = { \
364	NS_MODULEINFO_VERSION, \
365	(#_name), \
366	(_components), \
367	(sizeof(_components) / sizeof(_components[0])), \
368	(_ctor), \
369	(_dtor), \
370	(nsnull) \
371	}; \
372	NSGETMODULE_ENTRY_POINT(NSMODULEINFO(_name))
373
374	#else // DEPENDENT_LIBS
375
376	#define NS_IMPL_NSGETMODULE_WITH_CTOR_DTOR(_name, _components, _ctor, _dtor) \
377	NSDEPENDENT_LIBS(_name) \
378	NS_MODULEINFO NSMODULEINFO(_name) = { \
379	NS_MODULEINFO_VERSION, \
380	(#_name), \
381	(_components), \
382	(sizeof(_components) / sizeof(_components[0])), \
383	(_ctor), \
384	(_dtor), \
385	(NSDEPENDENT_LIBS_NAME(_name)) \
386	}; \
387	NSGETMODULE_ENTRY_POINT(NSMODULEINFO(_name))
388
389	#endif
390
391	////////////////////////////////////////////////////////////////////////////////
392
393	#define NS_GENERIC_FACTORY_CONSTRUCTOR(_InstanceClass) \
394	static NS_IMETHODIMP \
395	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
396	void **aResult) \
397	{ \
398	nsresult rv; \
399	\
400	_InstanceClass * inst; \
401	\
402	*aResult = NULL; \
403	if (NULL != aOuter) { \
404	rv = NS_ERROR_NO_AGGREGATION; \
405	return rv; \
406	} \
407	\
408	NS_NEWXPCOM(inst, _InstanceClass); \
409	if (NULL == inst) { \
410	rv = NS_ERROR_OUT_OF_MEMORY; \
411	return rv; \
412	} \
413	NS_ADDREF(inst); \
414	rv = inst->QueryInterface(aIID, aResult); \
415	NS_RELEASE(inst); \
416	\
417	return rv; \
418	} \
419
420
421	#define NS_GENERIC_FACTORY_CONSTRUCTOR_INIT(_InstanceClass, _InitMethod) \
422	static NS_IMETHODIMP \
423	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
424	void **aResult) \
425	{ \
426	nsresult rv; \
427	\
428	_InstanceClass * inst; \
429	\
430	*aResult = NULL; \
431	if (NULL != aOuter) { \
432	rv = NS_ERROR_NO_AGGREGATION; \
433	return rv; \
434	} \
435	\
436	NS_NEWXPCOM(inst, _InstanceClass); \
437	if (NULL == inst) { \
438	rv = NS_ERROR_OUT_OF_MEMORY; \
439	return rv; \
440	} \
441	NS_ADDREF(inst); \
442	rv = inst->_InitMethod(); \
443	if(NS_SUCCEEDED(rv)) { \
444	rv = inst->QueryInterface(aIID, aResult); \
445	} \
446	NS_RELEASE(inst); \
447	\
448	return rv; \
449	} \
450
451	// 'Constructor' that uses an existing getter function that gets a singleton.
452	// NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
453	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR(_InstanceClass, _GetterProc) \
454	static NS_IMETHODIMP \
455	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
456	void **aResult) \
457	{ \
458	nsresult rv; \
459	\
460	_InstanceClass * inst; \
461	\
462	*aResult = NULL; \
463	if (NULL != aOuter) { \
464	rv = NS_ERROR_NO_AGGREGATION; \
465	return rv; \
466	} \
467	\
468	inst = _GetterProc(); \
469	if (NULL == inst) { \
470	rv = NS_ERROR_OUT_OF_MEMORY; \
471	return rv; \
472	} \
473	/* NS_ADDREF(inst); */ \
474	rv = inst->QueryInterface(aIID, aResult); \
475	NS_RELEASE(inst); \
476	\
477	return rv; \
478	} \
479
480	#endif /* nsIGenericFactory_h___ */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/xpcom18a4/xpcom/glue/nsIGenericFactory.h@ 103977

Download in other formats: