diff --git a/mozilla/xpcom/sample/nsISample.idl b/mozilla/xpcom/sample/nsISample.idl index a72bd5d2195..4d52137c3f7 100644 --- a/mozilla/xpcom/sample/nsISample.idl +++ b/mozilla/xpcom/sample/nsISample.idl @@ -20,14 +20,25 @@ * Contributor(s): */ -/* - - A sample of XPConnect. This file contains a sample interface. - +/** + * A sample of XPConnect. This file contains a sample interface. + * */ #include "nsISupports.idl" +/** + * The uuid is a unique number identifying the interface normally + * called IID. It can be generated as follows: + * + * Windows: guidgen.exe + * Unix: uuidgen which comes with e2fsprogs package + * Mac: ??? + * All platform: Using irc, connect to irc.mozilla.org and type in + * /join #mozilla + * /msg mozbot uuid + * + */ [scriptable, uuid(7CB5B7A1-07D7-11d3-BDE2-000064657374)] interface nsISample : nsISupports { @@ -38,10 +49,15 @@ interface nsISample : nsISupports %{ C++ -// {7CB5B7A0-07D7-11d3-BDE2-000064657374} +/** + * {7CB5B7A0-07D7-11d3-BDE2-000064657374} + * The CID is also a unique number that look just like the IID + * and identifies uniquely an implementation + */ #define NS_SAMPLE_CID \ { 0x7cb5b7a0, 0x7d7, 0x11d3, { 0xbd, 0xe2, 0x0, 0x0, 0x64, 0x65, 0x73, 0x74 } } -extern nsresult -NS_NewSample(nsISample** aSample); +#define NS_SAMPLE_PROGID "component://netscape/sample" %} + + diff --git a/mozilla/xpcom/sample/nsSample.cpp b/mozilla/xpcom/sample/nsSample.cpp index 725d1fb3aaa..7e6d08c42a8 100644 --- a/mozilla/xpcom/sample/nsSample.cpp +++ b/mozilla/xpcom/sample/nsSample.cpp @@ -21,85 +21,18 @@ */ -/* - - A sample of XPConnect. This file contains an implementation of - nsISample. - -*/ -#include "nscore.h" -#include "nsISample.h" +/** + * + * A sample of XPConnect. This file contains an implementation nsSample + * of the interface nsISample. + * + */ #include "nsIAllocator.h" #include "plstr.h" #include "stdio.h" -/** - * SampleImpl is an implementation of the nsISample interface. In XPCOM, - * there can be more than one implementation of an given interface. Class - * IDs (CIDs) uniquely identify a particular implementation of an interface. - * Interface IDs (IIDs) uniquely identify an interface. - */ -class SampleImpl : public nsISample -{ -public: - SampleImpl(); - virtual ~SampleImpl(); +#include "nsSample.h" - /** - * 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 interface - NS_DECL_ISUPPORTS - - /** - * This macro is defined in the nsISample.h file, and is generated - * automatically by the xpidl compiler. It expands to - * declarations of all of the methods required to implement the - * interface. xpidl will generate a NS_DECL_[INTERFACENAME] macro - * for each interface that it processes. - * - * The methods of nsISample are discussed individually below, but - * commented out (because this macro already defines them.) - */ - NS_DECL_NSISAMPLE - - /** - * NS_IMETHOD expands to the standard XPCOM return type. XPCOM methods - * should never return any other type. The return value is used - * behind the scenes by the XPConnect runtime to figure out if the call - * failed in any way. - * These methods were generated by "attribute string Value" in - * nsISample.idl. When reflected into JavaScript, XPCOM will use these - * calls as Getter/Setter ops, so that they can be called transparently - * as "sample.Value='foo';" and "var val = sample.Value" - */ - // nsISample interface - /* NS_IMETHOD GetValue(char * *aValue); */ - /* NS_IMETHOD SetValue(char * aValue); */ - - /** - * The const came from the "in" specifier in nsISample.idl. "in" - * specifies that the value of this parameter is used only for input, - * this method is not allowed to modify the contents of the buffer. - */ - /* NS_IMETHOD WriteValue(const char *aPrefix); */ - - /** - * nsISample.idl specifies all of it's string types as string, instead - * of wstring (wide string), the Unicode type. If the world were a - * perfect place, all normal strings in XPCOM interfaces would be unicode. - * If this type had been specified as wstring, it would appear as - * PRUnichar * in C++, which is the NSPR type for unicode characters. - */ - /* NS_IMETHOD Poke(const char* aValue); */ - -private: - char* mValue; -}; //////////////////////////////////////////////////////////////////////// @@ -110,9 +43,9 @@ private: * interface, it only gets included, verbatim, in nsISample.h. * This is so that the factory for this class (nsSampleFactory.cpp) * can create a nsSample object. Normally you would expect to use - * "SampleImpl s = new SampleImpl();" to create the object, the catch here - * is that SampleImpl is not declared anywhere except in this file, so the - * factory has no idea what a SampleImpl is. Instead, this static function's + * "nsSampleImpl s = new nsSampleImpl();" to create the object, the catch here + * is that nsSampleImpl is not declared anywhere except in this file, so the + * factory has no idea what a nsSampleImpl is. Instead, this static function's * prototype is declared in in nsISample.h (generated from nsISample.idl), * which any nsISample factory would require for the declaration of * nsISample anyway. @@ -124,7 +57,7 @@ NS_NewSample(nsISample** aSample) if (! aSample) return NS_ERROR_NULL_POINTER; - *aSample = new SampleImpl(); + *aSample = new nsSampleImpl(); if (! *aSample) return NS_ERROR_OUT_OF_MEMORY; @@ -151,13 +84,13 @@ NS_NewSample(nsISample** aSample) //////////////////////////////////////////////////////////////////////// -SampleImpl::SampleImpl() : mValue(nsnull) +nsSampleImpl::nsSampleImpl() : mValue(nsnull) { NS_INIT_REFCNT(); mValue = PL_strdup("initial value"); } -SampleImpl::~SampleImpl() +nsSampleImpl::~nsSampleImpl() { if (mValue) PL_strfree(mValue); @@ -174,7 +107,7 @@ SampleImpl::~SampleImpl() * Notice that the second parameter to the macro is the static IID accessor * method, and NOT the #defined IID. */ -NS_IMPL_ISUPPORTS(SampleImpl, nsISample::GetIID()); +NS_IMPL_ISUPPORTS(nsSampleImpl, nsISample::GetIID()); /** * Notice that in the protoype for this function, the NS_IMETHOD macro was @@ -182,7 +115,7 @@ NS_IMPL_ISUPPORTS(SampleImpl, nsISample::GetIID()); * type is declared by NS_IMETHODIMP */ NS_IMETHODIMP -SampleImpl::GetValue(char** aValue) +nsSampleImpl::GetValue(char** aValue) { NS_PRECONDITION(aValue != nsnull, "null ptr"); if (! aValue) @@ -191,7 +124,7 @@ SampleImpl::GetValue(char** aValue) if (mValue) { /** * GetValue's job is to return data known by an instance of - * SampleImpl to the outside world. If we were to simply return + * nsSampleImpl to the outside world. If we were to simply return * a pointer to data owned by this instance, and the client were to * free it, bad things would surely follow. * On the other hand, if we create a new copy of the data for our @@ -215,7 +148,7 @@ SampleImpl::GetValue(char** aValue) } NS_IMETHODIMP -SampleImpl::SetValue(const char* aValue) +nsSampleImpl::SetValue(const char* aValue) { NS_PRECONDITION(aValue != nsnull, "null ptr"); if (! aValue) @@ -236,13 +169,13 @@ SampleImpl::SetValue(const char* aValue) } NS_IMETHODIMP -SampleImpl::Poke(const char* aValue) +nsSampleImpl::Poke(const char* aValue) { return SetValue((char*) aValue); } NS_IMETHODIMP -SampleImpl::WriteValue(const char* aPrefix) +nsSampleImpl::WriteValue(const char* aPrefix) { NS_PRECONDITION(aPrefix != nsnull, "null ptr"); if (! aPrefix) diff --git a/mozilla/xpcom/sample/nsSample.h b/mozilla/xpcom/sample/nsSample.h new file mode 100644 index 00000000000..6fae7de8b3d --- /dev/null +++ b/mozilla/xpcom/sample/nsSample.h @@ -0,0 +1,102 @@ +/* -*- 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.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 Netscape are + * Copyright (C) 1998 Netscape Communications Corporation. All + * Rights Reserved. + * + * Contributor(s): + */ + +/** + * A sample of XPConnect. This file is the header of an implementation + * nsSample of the nsISample interface. + * + */ + +#include "nsISample.h" + +/** + * SampleImpl is an implementation of the nsISample interface. In XPCOM, + * there can be more than one implementation of an given interface. Class + * IDs (CIDs) uniquely identify a particular implementation of an interface. + * Interface IDs (IIDs) uniquely identify an interface. + */ +class nsSampleImpl : public nsISample +{ +public: + nsSampleImpl(); + virtual ~nsSampleImpl(); + + /** + * 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 interface + NS_DECL_ISUPPORTS + + /** + * This macro is defined in the nsISample.h file, and is generated + * automatically by the xpidl compiler. It expands to + * declarations of all of the methods required to implement the + * interface. xpidl will generate a NS_DECL_[INTERFACENAME] macro + * for each interface that it processes. + * + * The methods of nsISample are discussed individually below, but + * commented out (because this macro already defines them.) + */ + NS_DECL_NSISAMPLE + + /** + * The following is an explanation of how the interface header + * file expands to for a c++ implementation. NS_DELC_NSISAMPLE + * takes care of defining the right c++ implementation. + * + * The following if provided for more understanding. + * + * NS_IMETHOD expands to the standard XPCOM return type. XPCOM methods + * should never return any other type. The return value is used + * behind the scenes by the XPConnect runtime to figure out if the call + * failed in any way. + * These methods were generated by "attribute string Value" in + * nsISample.idl. When reflected into JavaScript, XPCOM will use these + * calls as Getter/Setter ops, so that they can be called transparently + * as "sample.Value='foo';" and "var val = sample.Value" + */ + /* NS_IMETHOD GetValue(char * *aValue); */ + /* NS_IMETHOD SetValue(char * aValue); */ + + /** + * The const came from the "in" specifier in nsISample.idl. "in" + * specifies that the value of this parameter is used only for input, + * this method is not allowed to modify the contents of the buffer. + */ + /* NS_IMETHOD WriteValue(const char *aPrefix); */ + + /** + * nsISample.idl specifies all of it's string types as string, instead + * of wstring (wide string), the Unicode type. If the world were a + * perfect place, all normal strings in XPCOM interfaces would be unicode. + * If this type had been specified as wstring, it would appear as + * PRUnichar * in C++, which is the NSPR type for unicode characters. + */ + /* NS_IMETHOD Poke(const char* aValue); */ + +private: + char* mValue; +}; diff --git a/mozilla/xpcom/sample/nsSampleModule.cpp b/mozilla/xpcom/sample/nsSampleModule.cpp index a6f43b3b243..37ead2fc253 100644 --- a/mozilla/xpcom/sample/nsSampleModule.cpp +++ b/mozilla/xpcom/sample/nsSampleModule.cpp @@ -19,257 +19,40 @@ * * Contributor(s): */ -#include "nsCOMPtr.h" #include "nsIModule.h" #include "nsIGenericFactory.h" -#include "nsISample.h" -static NS_DEFINE_CID(kSampleCID, NS_SAMPLE_CID); +#include "nsSample.h" -// Module implementation -class nsSampleModule : public nsIModule +//////////////////////////////////////////////////////////////////////// +// Define the contructor function for the object nsSample +// +// What this does is defines a functions nsSampleConstructor which we +// will specific in the nsModuleComponentInfo table. This functions will +// be used the generic factory to create an instance of nsSample. +// +// NOTE: This creates an instance of nsSample by using the default +// constructor. +// +NS_GENERIC_FACTORY_CONSTRUCTOR(nsSampleImpl) + +//////////////////////////////////////////////////////////////////////// +// Define a table of CIDs implemented by this module along with other +// information like the function to create an instance, progid, and +// class name. +// +static nsModuleComponentInfo components[] = { -public: - nsSampleModule(); - virtual ~nsSampleModule(); - - NS_DECL_ISUPPORTS - - NS_DECL_NSIMODULE - -protected: - nsresult Initialize(); - - void Shutdown(); - - PRBool mInitialized; - nsCOMPtr mFactory; + { NS_SAMPLE_CID, &nsSampleImplConstructor, NS_SAMPLE_PROGID, + "Sample Component" }, }; -//---------------------------------------------------------------------- +//////////////////////////////////////////////////////////////////////// +// Implement the Module object +// +NS_IMPL_MODULE(nsSampleModule, components) -// Functions used to create new instances of a given object by the -// generic factory. - -#define MAKE_CTOR(_name) \ -static NS_IMETHODIMP \ -CreateNew##_name(nsISupports* aOuter, REFNSIID aIID, void **aResult) \ -{ \ - if (!aResult) { \ - return NS_ERROR_INVALID_POINTER; \ - } \ - if (aOuter) { \ - *aResult = nsnull; \ - return NS_ERROR_NO_AGGREGATION; \ - } \ - nsCOMPtr inst; \ - nsresult rv = NS_New##_name(getter_AddRefs(inst)); \ - if (NS_FAILED(rv)) { \ - *aResult = nsnull; \ - return rv; \ - } \ - rv = inst->QueryInterface(aIID, aResult); \ - if (NS_FAILED(rv)) { \ - *aResult = nsnull; \ - } \ - return rv; \ -} - -MAKE_CTOR(Sample) - -//---------------------------------------------------------------------- - -nsSampleModule::nsSampleModule() - : mInitialized(PR_FALSE) -{ - NS_INIT_ISUPPORTS(); -} - -nsSampleModule::~nsSampleModule() -{ - Shutdown(); -} - -NS_IMPL_ISUPPORTS(nsSampleModule, NS_GET_IID(nsIModule)) - -// Perform our one-time intialization for this module -nsresult -nsSampleModule::Initialize() -{ - if (mInitialized) { - return NS_OK; - } - mInitialized = PR_TRUE; - return NS_OK; -} - -// Shutdown this module, releasing all of the module resources -void -nsSampleModule::Shutdown() -{ - // Release the factory object - mFactory = nsnull; -} - -// Create a factory object for creating instances of aClass. -NS_IMETHODIMP -nsSampleModule::GetClassObject(nsIComponentManager *aCompMgr, - const nsCID& aClass, - const nsIID& aIID, - void** r_classObj) -{ - nsresult rv; - - // Defensive programming: Initialize *r_classObj in case of error below - if (!r_classObj) { - return NS_ERROR_INVALID_POINTER; - } - *r_classObj = NULL; - - // Do one-time-only initialization if necessary - if (!mInitialized) { - rv = Initialize(); - if (NS_FAILED(rv)) { - // Initialization failed! yikes! - return rv; - } - } - - // Choose the appropriate factory, based on the desired instance - // class type (aClass). - nsCOMPtr fact; - if (aClass.Equals(kSampleCID)) { - if (!mFactory) { - // Create and save away the factory object for creating - // new instances of Sample. This way if we are called - // again for the factory, we won't need to create a new - // one. - rv = NS_NewGenericFactory(getter_AddRefs(mFactory), - CreateNewSample); - } - fact = mFactory; - } - else { - rv = NS_ERROR_FACTORY_NOT_REGISTERED; -#ifdef DEBUG - char* cs = aClass.ToString(); - printf("+++ nsSampleModule: unable to create factory for %s\n", cs); - nsCRT::free(cs); -#endif - } - - if (fact) { - rv = fact->QueryInterface(aIID, r_classObj); - } - - return rv; -} - -//---------------------------------------- - -struct Components { - const char* mDescription; - const nsID* mCID; - const char* mProgID; -}; - -// The list of components we register -static Components gComponents[] = { - { "Sample World Component", &kSampleCID, - "component://mozilla/sample/sample-world", }, -}; -#define NUM_COMPONENTS (sizeof(gComponents) / sizeof(gComponents[0])) - -NS_IMETHODIMP -nsSampleModule::RegisterSelf(nsIComponentManager *aCompMgr, - nsIFileSpec* aPath, - const char* registryLocation, - const char* componentType) -{ - nsresult rv = NS_OK; - -#ifdef DEBUG - printf("*** Registering sample components\n"); -#endif - - Components* cp = gComponents; - Components* end = cp + NUM_COMPONENTS; - while (cp < end) { - rv = aCompMgr->RegisterComponentSpec(*cp->mCID, cp->mDescription, - cp->mProgID, aPath, PR_TRUE, - PR_TRUE); - if (NS_FAILED(rv)) { -#ifdef DEBUG - printf("nsSampleModule: unable to register %s component => %x\n", - cp->mDescription, rv); -#endif - break; - } - cp++; - } - - return rv; -} - -NS_IMETHODIMP -nsSampleModule::UnregisterSelf(nsIComponentManager* aCompMgr, - nsIFileSpec* aPath, - const char* registryLocation) -{ -#ifdef DEBUG - printf("*** Unregistering sample components\n"); -#endif - Components* cp = gComponents; - Components* end = cp + NUM_COMPONENTS; - while (cp < end) { - nsresult rv = aCompMgr->UnregisterComponentSpec(*cp->mCID, aPath); - if (NS_FAILED(rv)) { -#ifdef DEBUG - printf("nsSampleModule: unable to unregister %s component => %x\n", - cp->mDescription, rv); -#endif - } - cp++; - } - - return NS_OK; -} - -NS_IMETHODIMP -nsSampleModule::CanUnload(nsIComponentManager *aCompMgr, PRBool *okToUnload) -{ - if (!okToUnload) { - return NS_ERROR_INVALID_POINTER; - } - *okToUnload = PR_FALSE; - return NS_ERROR_FAILURE; -} - -//---------------------------------------------------------------------- - -static nsSampleModule *gModule = NULL; - -extern "C" NS_EXPORT nsresult NSGetModule(nsIComponentManager *servMgr, - nsIFileSpec* location, - nsIModule** return_cobj) -{ - nsresult rv = NS_OK; - - NS_ENSURE_ARG_POINTER(return_cobj); - NS_ENSURE_FALSE(gModule, NS_ERROR_FAILURE); - - // Create and initialize the module instance - nsSampleModule *m = new nsSampleModule(); - if (!m) { - return NS_ERROR_OUT_OF_MEMORY; - } - - // Increase refcnt and store away nsIModule interface to m in return_cobj - rv = m->QueryInterface(NS_GET_IID(nsIModule), (void**)return_cobj); - if (NS_FAILED(rv)) { - delete m; - m = nsnull; - } - gModule = m; // WARNING: Weak Reference - return rv; -} +//////////////////////////////////////////////////////////////////////// +// Implment the NSGetModule() exported function for your module +// +NS_IMPL_NSGETMODULE(nsSampleModule)