diff options
Diffstat (limited to 'debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Callbacks.html')
| -rw-r--r-- | debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Callbacks.html | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Callbacks.html b/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Callbacks.html new file mode 100644 index 00000000..ba3e0a66 --- /dev/null +++ b/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Callbacks.html @@ -0,0 +1,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> |