Chapter 1

Convenience functions are trivial wrappers for things that could otherwise be done with a
smaller API. If a class contains two functions Foo() and Bar(), which do all that's required
by the class, but you often find that code using your API contains sequences such as
x.Foo();
x.Bar();
or this
x.Foo(x.Bar());
y = (x.Foo() + x.Bar()) / 2;
then you may wish to code some kind of convenience function FooAnd- Bar() that
represents the sequence. This will reduce code size, reduce mistakes, and make code
easier to read.
The cost of convenience is another function to design and document, and the risk of being
tempted to produce many convenience functions that aren't really all that necessary or even
convenient – and then being forced to maintain them for ever more, because people depend
on them. This is a fine judgment call: sometimes we provide too few convenience functions
and sometimes too many.
3.4.2 DLLs and Other API Elements
An object-oriented system delivers APIs mainly as C++ classes, together with all their
member functions and data. Classes that form part of an API are declared in header files,
implemented in C++ source files, and delivered in DLLs.
Library APIs (or the library parts of a framework API) are delivered in shared library DLLs
with a .dll file extension. The DLL's exported functions are made available in a .lib file to
the linker at program build time.
Framework APIs are usually defined in terms of C++ classes containing virtual functions and
an interface specification for a polymorphic DLL with an extension other than .dll (for
instance, .app for a GUI-based application).
It's important to make sure that only the interface – not the implementation – is made
available to programs that use the API. Classes that are not part of the API should not be
declared in API header files, and their functions should not be exported from the DLLs that
implement them. Functions and data that belong to the API classes, but are not part of the
API, should be marked private.
Besides classes, C++ APIs may contain enumerations, constants, template functions, and
even nonmember functions.
3.4.3 Exported Functions
For a nonvirtual, noninline member function to be part of an API, it must be
� declared public in a C++ class that appears in a public header file
� exported from its DLL.
You will see exported functions marked in their header files with IMPORT_C, like this
class RTimer : public RHandleBase
{