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
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.77C-CCK-MCD Caldera Systems OpenLinux [en] (X11; U; Linux 2.4.2 i686) [Netscape]">
<title>OpenSLP Programmers Guide - Callbacks</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<h2>
Callbacks</h2>
<hr WIDTH="100%">
<h3>
What's a callback function?</h3>
If you are new to asynchronous programming, or have never used callback
functions before, just think of the SLP callback functions as a pieces
of code the you must write but never call directly. Yep, that's right,
you will probably never call your callback function directly, instead,
it will be called by the library when it is ready to report the status
or results of an operation. This allows your program to do other
things while data is being collected by the callback function. Callback
functions are required for all of the major SLP APIs for more information
see <a href="SLPReg.html">SLPReg()</a>,
<a href="SLPDereg.html">SLPDeReg()</a>,
<a href="SLPDelAttrs.html">SLPDelAttrs()</a>,
<a href="SLPFindSrvs.html">SLPFindSrvs()</a>,
<a href="SLPFindAttrs.html">SLPFindAttrs()</a>,
and <a href="SLPFindSrvTypes.html">SLPFindSrvTypes()</a>,
<p>Callback functions must accept the parameters that the caller (the SLP
library) expects to pass to them. This is why callback function types
are defined. See <a href="SLPRegReport.html">SLPRegReport()</a>,
<a href="SLPSrvURLCallback.html">SLPSrvURLCallback()</a>,
<a href="SLPAttrCallback.html">SLPAttrCallback()</a>.
<h3>
What's different about SLP callback functions?</h3>
Callbacks are an integral part of the SLP API. Developers usually
associate callbacks with asynchronous APIs, but the SLP API uses callbacks
for both synchronous and asynchronous operations. Whether the callback
is called synchronously or asynchronously, depends on the <tt><a href="SLPOpen.html#isasync">isasync</a>
</tt>parameter in the call to <tt><a href="SLPOpen.html">SLPOpen()</a></tt>.
Remember the following rules and you should not have any problems with
your callback functions.
<ul>
<li>
Callback functions are called in both synchronous and asynchronous cases.
The only difference is that in a synchronous case, the initiating function
(SLPReg(), SLPFindSrvs(), etc) will block until all results are reported
to the callback function.</li>
<li>
The memory passed in to callback functions is owned by the library.
i.e. the callback must <tt>strdup()</tt> strings before using them permanently
because the memory passed in will be <tt>free()</tt>d by the library when
the callback returns.</li>
<li>
<blink>Make your callback functions as efficient as possible.</blink>
This is especially important when a call is made with an async <tt><a href="SLPTypes.html#SLPHandle">SLPHandle</a></tt>
because results are not collected or collated by the library before the
callback function is called. In other words, in async mode,
the library will call the callback each time a reply message is received
until the request times out.</li>
<li>
If the <tt>errcode</tt> upon entry to the callback is set to anything but
<tt>SLP_OK</tt>,
the rest of the parameters may be invalid. Check the error code first.</li>
<li>
Use the <tt>cookie</tt> parameter. It is the best way to get information
to and from your callback.</li>
</ul>
<h3>
How does OpenSLP library handle asynchronous operation?</h3>
When an SLP library call is made with an SLPHandle that was opened in async
mode, the library does everything it can with out blocking. It then
creates a thread (hopefully a user level thread) and returns SLP_OK.
The newly created thread processes the request (possibly blocking to wait
for data to arrive from the network) and calls the callback function as
data is received.
<p>An important thing to remember is that <i>no collection or collation
of results is performed by the library when a call is initiated in async
mode. </i>This means that the callback may be called multiple times with
the same result. This would happen for example if two SAs or DAs
maintained the same registration.
<p>Currently all the code is in libslp to allow for asynchronous operation
except for the calls to pthread_create(). The reason for this is
mainly that no one has really needed asynchronous operation. If you
feel like you have a good reason to use asynchronous operation then please
send email to openslp-devel@lists.sourceforge.net.
<h3>
How does OpenSLP library handle synchronous operation?</h3>
When an SLP library call is made with an SLPHandle that was opened in sync
mode, the library will not create a thread. Instead, the calling
thread will perform all processing (which may block) and report results
to the callback function. When in sync mode, all of the results are
collated to ensure no duplicates are returned. The API function call
will not return until all results are finished being reported through the
callback.
<h3>
Why not just have separate synchronous and asynchronous APIs?</h3>
That would have been good choice, but for some reason, the SLP designers
thought their way would be better. OpenSLP API is just an implementation
of a standardized specification described in RFC 2614
<h3>
Can I see some example code?</h3>
Yes, example code can be found in the documentation for the <a href="SLPReg.html">SLPReg()</a>,
<a href="SLPFindSrvs.html">SLPFindSrv()</a>,
<a href="SLPFindAttrs.html">SLPFindAttrs()</a> and <a href="SLPFindSrvTypes.html">SLPFindSrvTypes()</a>
functions.
</body>
</html>
|
