gecko-dev/xpcom/sample/nsSampleFactory.cpp

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

/*

  A sample of XPConnect. This file contains the XPCOM factory the
  creates for SampleImpl objects.

*/

#include "nsCOMPtr.h"
#include "nscore.h"
#include "nsISample.h"
#include "nsIComponentManager.h"
#include "nsIServiceManager.h"
#include "nsXPComFactory.h"

/**
 * IIDs and CIDs (aka CLSIDs) are 32 digit hexadecimal numbers, called Globally
 * Unique IDs (GUIDs) as a whole.  They should only be generated by a trusted
 * guid generator.  GUID generatoration algorithms rely on parameters such as
 * the MAC address of your NIC, and the date/time of GUID creation to ensure
 * that no two GUIDs are ever the same.  The Windows program 'uuidgen' is one
 * way to create these numbers. The Unix alternative is probably out there
 * somewhere.
 *
 * NS_DEFINE_IID and NS_DEFINE_CID expand to define static IID/CID objects
 * that will be used later.  IID and CID objects are of the same type, the
 * distinction between InterfaceID and ClassID is made strictly by what the
 * ID represents, and not by any binary differences.
 */
static NS_DEFINE_IID(kISupportsIID,        NS_ISUPPORTS_IID);
static NS_DEFINE_IID(kIFactoryIID,         NS_IFACTORY_IID);
static NS_DEFINE_CID(kComponentManagerCID, NS_COMPONENTMANAGER_CID);
static NS_DEFINE_CID(kSampleCID,           NS_SAMPLE_CID);

/**
 * SampleFactoryImpl is a factory capable of creating nsSampleImpl objects.
 * It is the factory, as opposed to the class, which actually registers itself
 * with the XPCOM runtime, in a conversation that goes something like,
 * XPCOM: "Hello factory at <path-name>, what can you do for me?",
 * FACTORY: "Hello XPCOM, I can create the classes named <progID>:<CID>,
 * and <progID>:<CID> and ...".  This conversation is initiated when XPCOM calls
 * into the static NSRegisterSelf function of the shared library that houses this
 * factory.  Once this factory is properly registered, XPCOM can work it's magic.
 * After registration, any call into the Service Manager or Component Manager's
 * CreateInstance method requesting a progID or CID that this factory has
 * registered will cause XPCOM to call the static NSGetFactory function in
 * the .so, .dll, .whatever associated with this factory (if it hasn't already
 * done so), and then invoke the CreateInstance method of the resulting factory.
 */
class SampleFactoryImpl : public nsIFactory
{
public:
    SampleFactoryImpl(const nsCID &aClass, const char* className,
                      const char* progID);

    /**
     * This macro expands into a declaration of the nsISupports interface.
     * Every XPCOM component needs to implement nsISupports, as it acts
     * as the gateway to other interfaces this component implements.  You
     * could manually declare QueryInterface, AddRef, and Release instead
     * of using this macro, but why?
     */
    // nsISupports methods
    NS_DECL_ISUPPORTS

    // nsIFactory methods
    NS_IMETHOD CreateInstance(nsISupports *aOuter,
                              const nsIID &aIID,
                              void **aResult);

    NS_IMETHOD LockFactory(PRBool aLock);

protected:
    virtual ~SampleFactoryImpl();

protected:
    /**
     * When XPCOM calls into NSGetFactory, it informs us what kind of class
     * it intends to create with this factory.  CreateInstance does NOT get
     * this information, so we need to record what kind of class CreateInstance
     * should return for later reference.
     */
    nsCID       mClassID;
    const char* mClassName;
    const char* mProgID;
};

////////////////////////////////////////////////////////////////////////

/**
 * All the constructor needs does is initailize reference counting and
 * record the CID/ progID it should return when CreateInstance is called.
 * Convention dictates a one-to-one mapping between progIDs and CIDs.  Think
 * of a CID as an IP address, and a progID as the canonical name.  The
 * class name is a more descriptive representation of the progID.  Classnames
 * do not have to be unique.
 */
SampleFactoryImpl::SampleFactoryImpl(const nsCID &aClass, 
                                     const char* className,
                                     const char* progID)
    : mClassID(aClass), mClassName(className), mProgID(progID)
{
    NS_INIT_REFCNT();
}

SampleFactoryImpl::~SampleFactoryImpl()
{
    NS_ASSERTION(mRefCnt == 0, "non-zero refcnt at destruction");
}

/**
 * This is what a normal implementation of QueryInterface (sometimes
 * abbreviated QI) actually looks like. Because this QI only supports
 * nsISupports and nsIFactory, it, and the two NS_IMPL_* macros
 * that follow it could actually be replaced with the macro 
 * NS_IMPL_ISUPPORTS(nsIFactory, nsIFactory::GetIID) as nsSample does
 * in nsSample.cpp.
 * The XPCOM homepage (www.mozilla.org/projects/xpcom) has another reference
 * implementation of QueryInterface.
 */
NS_IMETHODIMP
SampleFactoryImpl::QueryInterface(const nsIID &aIID, void **aResult)
{
    if (! aResult)
        return NS_ERROR_NULL_POINTER;

    // Always NULL result, in case of failure
    *aResult = nsnull;

    if (aIID.Equals(kISupportsIID)) {
        *aResult = NS_STATIC_CAST(nsISupports*, this);
        AddRef();
        return NS_OK;
    } else if (aIID.Equals(kIFactoryIID)) {
        *aResult = NS_STATIC_CAST(nsIFactory*, this);
        AddRef();
        return NS_OK;
    }
    return NS_NOINTERFACE;
}

NS_IMPL_ADDREF(SampleFactoryImpl);
NS_IMPL_RELEASE(SampleFactoryImpl);

/**
 * The IID passed in here is for COM Aggregation.  Aggregation deals with
 * classes contained within other classes, a topic out of the scope of
 * this sample.
 * Notice that this CreateInstance is very methodical...  It verifies that it
 * has been asked to create a supported class, even though we only registered
 * for one, and it calls QI on the newly created object, verifying that the
 * created class can actually support the interface we thought it could.  This
 * is (probably) regarded as a good thing in CreateInstance, and even if you
 * think you know whats going to happen in your CreateInstance, it's a good
 * idea to follow this same formula.
 */
NS_IMETHODIMP
SampleFactoryImpl::CreateInstance(nsISupports *aOuter,
                                  const nsIID &aIID,
                                  void **aResult)
{
    if (! aResult)
        return NS_ERROR_NULL_POINTER;

    if (aOuter)
        return NS_ERROR_NO_AGGREGATION;

    *aResult = nsnull;

    nsresult rv;

    nsISupports *inst = nsnull;
    if (mClassID.Equals(kSampleCID)) {
        if (NS_FAILED(rv = NS_NewSample((nsISample**) &inst)))
            return rv;
    }
    else {
        return NS_ERROR_NO_INTERFACE;
    }

    if (! inst)
        return NS_ERROR_OUT_OF_MEMORY;

    if (NS_FAILED(rv = inst->QueryInterface(aIID, aResult))) {
        // We didn't get the right interface.
        NS_ERROR("didn't support the interface you wanted");
    }

    NS_IF_RELEASE(inst);
    return rv;
}

/**
 * I'm really not sure what LockFactory would do if it were implemented :(
 */
nsresult SampleFactoryImpl::LockFactory(PRBool aLock)
{
    // Not implemented in simplest case.
    return NS_OK;
}

////////////////////////////////////////////////////////////////////////

/**
 * The XPCOM runtime will call this to get a new factory object for the
 * CID/progID it passes in.  XPCOM is responsible for caching the resulting
 * factory.
 */
// return the proper factory to the caller
extern "C" PR_IMPLEMENT(nsresult)
NSGetFactory(nsISupports* aServMgr,
             const nsCID &aClass,
             const char *aClassName,
             const char *aProgID,
             nsIFactory **aFactory)
{
    if (! aFactory)
        return NS_ERROR_NULL_POINTER;

    SampleFactoryImpl* factory = new SampleFactoryImpl(aClass, aClassName,
                                                       aProgID);
    if (factory == nsnull)
        return NS_ERROR_OUT_OF_MEMORY;

    NS_ADDREF(factory);
    *aFactory = factory;
    return NS_OK;
}

/**
 * When the XPCOM runtime is initialized, it searches the component directory
 * for shared objects, and attempts to call NSRegisterSelf for each one it
 * encounters.  You are expected to register each component the factory can
 * create as either a Service or a Component.  By convention, Services are
 * singletons, while Components are not.  Services are managed by the 
 * Service Manager, and Components are managed by (what else?) the Component
 * Manager.  The Component Manager itself is a Service, and so you can
 * retrieve it via the ServiceManager, as this function does.
 *
 * If you've gto some spare time, and _really_ want to see whats going on
 * behind the scenes at registration time, soak up PlatformPrePopulateRegistry
 * (and all the functions it calls) in 
 * mozilla/xpcom/components/nsComponentManager.cpp
 */
extern "C" PR_IMPLEMENT(nsresult)
NSRegisterSelf(nsISupports* aServMgr , const char* aPath)
{
    nsresult rv;

    nsCOMPtr<nsIServiceManager> servMgr(do_QueryInterface(aServMgr, &rv));
    if (NS_FAILED(rv)) return rv;

    NS_WITH_SERVICE(nsIComponentManager, compMgr, kComponentManagerCID, &rv);
    if (NS_FAILED(rv)) return rv;

    rv = compMgr->RegisterComponent(kSampleCID,
                                    "Sample World Component",
                                    "component://netscape/sample/sample-world",
                                    aPath, PR_TRUE, PR_TRUE);

    if (NS_FAILED(rv)) return rv;

    return NS_OK;
}

/**
 * NSUnregisterSelf is responsible for undoing anything NSRegisterSelf does
 * to the registry.  It would presumably be called if your component is
 * uninstalled or upgraded.
 */
extern "C" PR_IMPLEMENT(nsresult)
NSUnregisterSelf(nsISupports* aServMgr, const char* aPath)
{
    nsresult rv;

    nsCOMPtr<nsIServiceManager> servMgr(do_QueryInterface(aServMgr, &rv));
    if (NS_FAILED(rv)) return rv;

    NS_WITH_SERVICE(nsIComponentManager, compMgr, kComponentManagerCID, &rv);
    if (NS_FAILED(rv)) return rv;

    rv = compMgr->UnregisterComponent(kSampleCID, aPath);
    if (NS_FAILED(rv)) return rv;

    return NS_OK;
}