You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
115 lines
5.6 KiB
HTML
115 lines
5.6 KiB
HTML
<!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>
|