4.3.1.2 Using SCF

The only include header file you need to include to utilize SCF functionality is ‘scf.h’. It contains a number of macros and functions that you will need for easier use of SCF.

Much basic functionality of SCF is provided by a central object. It can be accessed as ‘iSCF::SCF’ and is of type ‘iSCF*’ (which is also a valid SCF interface). This object is global and can be accessed from anywhere, even from dynamic libraries (plugin modules). It is used by several parts of SCF. Note that this object is only available after calling scfInitialize(), the main initialization function of SCF. In typical use, however, you rarely need to interact directly with ‘iSCF::SCF’. Instead, you invoke several convenient SCF macros which interact with ‘iSCF::SCF’ on your behalf.

All SCF classes should be derived from the basic interface ‘iBase’. This interface declares the bare minimum set of methods which all SCF classes should provide:

void IncRef()

This function should be called each time you get a new reference to a object and store it for a long-time usage. Rather than invoking this method manually, you can use a smart-pointer (csRef<>) to automate reference counting (see section Correctly Using Smart Pointers).

void DecRef()

Call this function to decrement the object's reference count. When the reference count reaches zero, the object is deleted automatically. There should be one matching DecRef() for each IncRef() invocation.

void AddRefOwner(void**)

Call this function to set up a weak reference to the object . A weak reference is one which is invalidated automatically when the referenced object is destroyed. This is useful in cases when some object wants to hold a pointer to an SCF object without actually owning a reference to the SCF object. Owning a reference prevents the SCF object from being destroyed, whereas holding a weak reference merely says that you are interested in this object as long as it is alive, but that you don't want to forcibly keep it alive. The argument to this method is a pointer to a variable which can hold a pointer to an SCF object. Rather than invoking this method manually, you typically would use a weak-reference template to automate the reference management (‘CS/include/csutil/weakref.h’).

void RemoveRefOwner(void**)

Call this function to remove a weak reference to the object.

void* QueryInterface(scfInterfaceID InterfaceID, int Version); This

method will return a pointer to an interface. The Interface ID is synonymous to the name of the interface. You can get the ID of an interface by invoking scfInterfaceTraits<Interface>::GetID().

To simplify things even further, ‘scf.h’ provides several templates that provide default declarations and default implementations of these methods. There is also the SCF_IMPLEMENT_FACTORY() macro which will implement the factory function for your class which returns new instances of the class to callers.

Example:

// Abstract interface file (itest.h)
struct iTest : public virtual iBase
{
  SCF_INTERFACE (iTest, 1, 0, 0);

  virtual void Foo () = 0;
};

// Concrete implementation header (test.h)
class Test : public scfImplementation1<Test, iTest>
{
public:
  Test (iBase* p = 0);
  virtual ~Test ();

  virtual void Foo ();
};

// Concrete implementation source (test.cpp)
SCF_IMPLEMENT_FACTORY(Test)

Test::Test (iBase* p)
  : scfImplementationType (this, p)
{
}
Test::~Test ()
{
}

void Test::Foo ()
{
  puts ("Foo");
}

This document was generated using texi2html 1.76.