PageRenderTime 256ms CodeModel.GetById 121ms app.highlight 11ms RepoModel.GetById 119ms app.codeStats 1ms

/gecko_api/include/nsIGenericFactory.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 454 lines | 188 code | 45 blank | 221 comment | 13 complexity | 2a110437b76428cfbdf29ea9fa0e8676 MD5 | raw file
  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
 46class nsIFile;
 47class 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
 62struct nsModuleComponentInfo; // forward declaration
 63
 64/**
 65 * Provides a Generic nsIFactory implementation that can be used by
 66 * DLLs with very simple factory needs.
 67 */
 68class nsIGenericFactory : public nsIFactory {
 69public:
 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
 76NS_DEFINE_STATIC_IID_ACCESSOR(nsIGenericFactory, NS_IGENERICFACTORY_IID)
 77
 78#ifndef XPCOM_GLUE_AVOID_NSPR
 79NS_COM_GLUE nsresult
 80NS_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  **/
107typedef 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 **/
135typedef 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 **/
162typedef 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 **/ 
173typedef 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 **/
190typedef NS_CALLBACK(NSGetInterfacesProcPtr)(PRUint32 *countp,
191                                            nsIID* **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 **/
209typedef 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 */
235struct 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 **/
263typedef nsresult (PR_CALLBACK *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 **/
273typedef void (PR_CALLBACK *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
291struct 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 */
312NS_COM_GLUE nsresult
313NS_NewGenericModule2(nsModuleInfo const *info, nsIModule* *result);
314
315/**
316 * Obsolete. Use NS_NewGenericModule2() instead.
317 */
318NS_COM_GLUE nsresult
319NS_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)  \
349static nsModuleInfo const kModuleInfo = {                                     \
350    NS_MODULEINFO_VERSION,                                                    \
351    (#_name),                                                                 \
352    (_components),                                                            \
353    (sizeof(_components) / sizeof(_components[0])),                           \
354    (_ctor),                                                                  \
355    (_dtor)                                                                   \
356};                                                                            \
357NSGETMODULE_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)                        \
368static 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)      \
396static 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) \
428static 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___ */