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