nsigenericfactory.h

gaca源码

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is 
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#ifndef nsIGenericFactory_h___
#define nsIGenericFactory_h___

#include "nsIFactory.h"
#include "nsIModule.h"
#include "nsIClassInfo.h"
#ifdef HAVE_DEPENDENT_LIBS
#include "dependentLibs.h"
#endif

// {3bc97f01-ccdf-11d2-bab8-b548654461fc}
#define NS_GENERICFACTORY_CID                                                 \
  { 0x3bc97f01, 0xccdf, 0x11d2,                                               \
    { 0xba, 0xb8, 0xb5, 0x48, 0x65, 0x44, 0x61, 0xfc } }

// {3bc97f00-ccdf-11d2-bab8-b548654461fc}
#define NS_IGENERICFACTORY_IID                                                \
  { 0x3bc97f00, 0xccdf, 0x11d2,                                               \
    { 0xba, 0xb8, 0xb5, 0x48, 0x65, 0x44, 0x61, 0xfc } }

#define NS_GENERICFACTORY_CONTRACTID "@mozilla.org/generic-factory;1"
#define NS_GENERICFACTORY_CLASSNAME "Generic Factory"

struct nsModuleComponentInfo; // forward declaration

/**
 * Provides a Generic nsIFactory implementation that can be used by
 * DLLs with very simple factory needs.
 */
class nsIGenericFactory : public nsIFactory {
public:
    NS_DEFINE_STATIC_IID_ACCESSOR(NS_IGENERICFACTORY_IID)
    
    NS_IMETHOD SetComponentInfo(const nsModuleComponentInfo *info) = 0;
    NS_IMETHOD GetComponentInfo(const nsModuleComponentInfo **infop) = 0;
};

NS_COM nsresult
NS_NewGenericFactory(nsIGenericFactory **result,
                     const nsModuleComponentInfo *info);


/** Component Callbacks **/

 /** 
  * NSConstructorProcPtr
  *
  * This function will be used by the generic factory to create an 
  * instance of the given CID.
  *
  * @param aOuter    : Pointer to a component that wishes to be aggregated
  *                    in the resulting instance. This will be nsnull if no
  *                    aggregation is requested.
  * @param iid       : The IID of the interface being requested in
  *                    the component which is being currently created.
  * @param result    : [out] Pointer to the newly created instance, if successful.
  *
  * @return NS_OK                     Component successfully created and the interface 
  *                                   being requested was successfully returned in result.
  *         NS_NOINTERFACE            Interface not accessible.
  *         NS_ERROR_NO_AGGREGATION   if an 'outer' object is supplied, but the
  *                                   component is not aggregatable.
  *         NS_ERROR*                 Method failure.
  **/
typedef NS_CALLBACK(NSConstructorProcPtr)(nsISupports *aOuter, 
                                          REFNSIID aIID,
                                          void **aResult);

/**
 * NSRegisterSelfProcPtr
 *
 * One time registration call back.  Allows you to perform registration 
 * specific activity like adding yourself to a category.
 *
 * @param aCompMgr    : The global component manager
 * @param aFile       : Component File. This file must have an associated 
 *                      loader and export the required symbols which this 
 *                      loader defines.
 * @param aLoaderStr  : Opaque loader specific string.  This value is
 *                      passed into the nsIModule's registerSelf
 *                      callback and must be fowarded unmodified when
 *                      registering factories via their location.
 * @param aType       : Component Type of CID aClass.  This value is
 *                      passed into the nsIModule's registerSelf
 *                      callback and must be fowarded unmodified when
 *                      registering factories via their location.
 * @param aInfo       : Pointer to array of nsModuleComponentInfo 
 *
 * @param aInfo         
 * @return NS_OK        Registration was successful.
 *         NS_ERROR*    Method failure.
 **/
typedef NS_CALLBACK(NSRegisterSelfProcPtr)(nsIComponentManager *aCompMgr,
                                           nsIFile *aPath,
                                           const char *aLoaderStr,
                                           const char *aType,
                                           const nsModuleComponentInfo *aInfo);

/**
 * NSUnregisterSelfProcPtr
 *
 * One time unregistration call back.  Allows you to perform unregistration
 * specific activity like removing yourself from a category.
 *
 * @param aCompMgr    : The global component manager
 * @param aFile       : Component File. This file must have an associated 
 *                      loader and export the required symbols which this 
 *                      loader defines.
 * @param aLoaderStr  : Opaque loader specific string.  This value is
 *                      passed into the nsIModule's registerSelf
 *                      callback and must be fowarded unmodified when
 *                      registering factories via their location
 * @param aInfo       : Pointer to array of nsModuleComponentInfo 
 *
 * @param aInfo         
 * @return NS_OK        Registration was successful.
 *         NS_ERROR*    Method failure.

 **/
typedef NS_CALLBACK(NSUnregisterSelfProcPtr)(nsIComponentManager *aCompMgr,
                                             nsIFile *aPath,
                                             const char *aLoaderStr,
                                             const nsModuleComponentInfo *aInfo);

/** 
 * NSFactoryDestructorProcPtr
 *
 * This function will be called when the factory is being destroyed. 
 *
 **/ 
typedef NS_CALLBACK(NSFactoryDestructorProcPtr)(void);


/** 
 * NSGetInterfacesProcPtr
 *
 * This function is used to implement class info.
 *       
 * Get an ordered list of the interface ids that instances of the class 
 * promise to implement. Note that nsISupports is an implicit member 
 * of any such list and need not be included. 
 *
 * Should set *count = 0 and *array = null and return NS_OK if getting the 
 * list is not supported.
 * 
 * @see nsIClassInfo.idl
 **/
typedef NS_CALLBACK(NSGetInterfacesProcPtr)(PRUint32 *countp,
                                            nsIID* **array);

/** 
 * NSGetLanguageHelperProcPtr
 *      
 * This function is used to implement class info.
 *
 * Get a language mapping specific helper object that may assist in using
 * objects of this class in a specific lanaguage. For instance, if asked
 * for the helper for nsIProgrammingLanguage::JAVASCRIPT this might return 
 * an object that can be QI'd into the nsIXPCScriptable interface to assist 
 * XPConnect in supplying JavaScript specific behavior to callers of the 
 * instance object.
 *
 * @see: nsIClassInfo.idl, nsIProgrammingLanguage.idl
 *
 * Should return null if no helper available for given language.
 **/
typedef NS_CALLBACK(NSGetLanguageHelperProcPtr)(PRUint32 language,
                                                nsISupports **helper);

/**
 * nsModuleComponentInfo
 *
 * Use this type to define a list of module component info to pass to 
 * NS_NewGenericModule. 
 *
 * @param mDescription           : Class Name of given object
 * @param mCID                   : CID of given object
 * @param mContractID            : Contract ID of given object
 * @param mConstructor           : Constructor of given object
 * @param mRegisterSelfProc      : (optional) Registration Callback
 * @param mUnregisterSelfProc    : (optional) Unregistration Callback
 * @param mFactoryDestructor     : (optional) Destruction Callback
 * @param mGetInterfacesProc     : (optional) Interfaces Callback
 * @param mGetLanguageHelperProc : (optional) Language Helper Callback
 * @param mClassInfoGlobal       : (optional) Global Class Info of given object 
 * @param mFlags                 : (optional) Class Info Flags @see nsIClassInfo 
 *                                 
 * E.g.:
 *     static nsModuleComponentInfo components[] = { ... };
 *
 * See xpcom/sample/nsSampleModule.cpp for more info.
 */
struct nsModuleComponentInfo {
    const char*                                 mDescription;
    nsCID                                       mCID;
    const char*                                 mContractID;
    NSConstructorProcPtr                        mConstructor;
    NSRegisterSelfProcPtr                       mRegisterSelfProc;
    NSUnregisterSelfProcPtr                     mUnregisterSelfProc;
    NSFactoryDestructorProcPtr                  mFactoryDestructor;
    NSGetInterfacesProcPtr                      mGetInterfacesProc;
    NSGetLanguageHelperProcPtr                  mGetLanguageHelperProc;
    nsIClassInfo **                             mClassInfoGlobal;