1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HTML>
<HEAD>
<TITLE>Crystal Space: SCF Using</TITLE>
<META NAME="description" CONTENT="Crystal Space: SCF Using">
<META NAME="keywords" CONTENT="Crystal Space: SCF Using">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC299"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_135.html#SEC298"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_137.html#SEC300"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_131.html#SEC294"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_134.html#SEC297"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_142.html#SEC310"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<HR SIZE=1>
<H3> 6.4.2 Using SCF </H3>
<!--docid::SEC299::-->
<P>
The only include file you need in both your client and server modules is
`<TT>scf.h</TT>'. It contains a number of macros and functions that you will need
for easier use of SCF. You will also have to add `<TT>scfimp.cpp</TT>' for
both the server and the client, and `<TT>scf.cpp</TT>' for the client.
</P><P>
Some basic functionality of SCF is provided by a central object. It can
be accessed as `<SAMP>iSCF::SCF</SAMP>' and is of type `<SAMP>iSCF*</SAMP>' (which is also a
valid interface). This object can be accessed from <EM>anywhere</EM>, even from
dynamic libraries. It is used by several parts of SCF. Note that this
object is only available after calling <CODE>scfInitialize()</CODE>, the main
initialization function of SCF.
</P><P>
To simplify things, all exported classes are supposed to be derived from some
basical interface called `<SAMP>iBase</SAMP>'. Thus, any interface is supposed to
implement some basical functionality. Currently `<SAMP>iBase</SAMP>' defines three
interface functions:
</P><P>
<DL COMPACT>
<DT><CODE>void IncRef();</CODE>
<DD>This function should be called each time you get a new reference to a object
and store it for a long-time usage.
<P>
<DT><CODE>void DecRef();</CODE>
<DD>Call this function to decrement the object's reference count. When reference
count reaches zero, the object is automatically deleted, provided that it is
not an interface embedded within another object,
<A HREF="cs_137.html#SCF Embedded Interfaces">SCF Embedded Interfaces</A>.
<P>
<DT><CODE>iBase* QueryInterface(scfInterfaceID iInterfaceID, int iVersion);</CODE>
<DD>This method will return a pointer to an interface or to an embedded interface,
<A HREF="cs_137.html#SCF Embedded Interfaces">SCF Embedded Interfaces</A>. The <EM>Interface ID</EM> is synonymous to the
name of the interface. In previous versions of SCF this method used to
accept a string containing the name of the interface. This has been replaced
by the <EM>ID</EM> for performance reasons. You can get the ID for an interface
by using `<SAMP>iSCF::SCF->GetInterfaceID (name)</SAMP>'.
</DL>
<P>
To simplify things even more, `<TT>scf.h</TT>' provides several macros that
provide default declarations and default implementations of these three
methods. The `<SAMP>SCF_DECLARE_IBASE</SAMP>' macro will declare these three methods
within any class definition that is derived from `<SAMP>iBase</SAMP>'. The
`<SAMP>SCF_IMPLEMENT_IBASE</SAMP>' will add the default implementation of these function
to your module. Example:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>struct iTest : public iBase
{
<small>...</small>
};
class Test : public iTest
{
SCF_DECLARE_IBASE;
};
SCF_IMPLEMENT_IBASE(Test)
</pre></td></tr></table></P><P>
In reality, we need a few more macros because the <CODE>QueryInterface()</CODE>
function is not static--it depends on the interfaces implemented by given
object. In fact, <CODE>SCF_IMPLEMENT_IBASE()</CODE> defines <CODE>IncRef()</CODE> and
<CODE>DecRef()</CODE> and the beginning of the <CODE>QueryInterface()</CODE> function,
but not the end of that function (i.e. the closing brace). That's because you
have to use an additional macro called <CODE>SCF_IMPLEMENTS_INTERFACE()</CODE> that
will add the code required to support all implemented interface inside the
<CODE>QueryInterface()</CODE>:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>SCF_IMPLEMENT_IBASE(Test)
SCF_IMPLEMENTS_INTERFACE(iTest)
SCF_IMPLEMENT_IBASE_END
</pre></td></tr></table></P><P>
The `<SAMP>SCF_DECLARE_IBASE</SAMP>' macro also defines two member variables:
`<SAMP>scfRefCount</SAMP>' and `<SAMP>scfParent</SAMP>'. `<SAMP>scfRefCount</SAMP>' is the counter
for external references to this object and is used by <CODE>IncRef()</CODE> and
<CODE>DecRef()</CODE> methods. The `<SAMP>scfParent</SAMP>' variable points to the parent
object and is also used by <CODE>IncRef()</CODE> and <CODE>DecRef()</CODE>. Objects are
chained together in a tree-like fashion, and an call to <CODE>IncRef()</CODE> will
also call <CODE>scfParent->IncRef()</CODE>; same with <CODE>DecRef()</CODE>. The root of
the chain is the class factory, that is, an object that is used to create
objects of a specific class. The object tree looks like this:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>ClassFactory
=> Object
=> Embedded interface
=> Embedded interface
=> Sub-embedded interface
</pre></td></tr></table></P><P>
Thus, if we call the <CODE>IncRef()</CODE> method for <EM>Sub-embedded interface</EM>,
we also will increment reference count for <EM>Object</EM> and
<EM>ClassFactory</EM>.
</P><P>
You also should call <CODE>SCF_CONSTRUCT_IBASE(<VAR>parent</VAR>)</CODE> inside your class
constructor, this macro will initialize `<SAMP>scfRefCount</SAMP>' to zero and
`<SAMP>scfParent</SAMP>' to <VAR>parent</VAR>. In fact, the constructor of any class
should receive at least one argument of type `<SAMP>iBase*</SAMP>' which should then
be passed along to the <CODE>SCF_CONSTRUCT_IBASE()</CODE> macro.
</P><P>
<A NAME="SCF Multiple Interfaces"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_135.html#SEC298"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_137.html#SEC300"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_131.html#SEC294"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_134.html#SEC297"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_142.html#SEC310"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
