diff options
Diffstat (limited to 'debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Divergence.html')
| -rw-r--r-- | debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Divergence.html | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Divergence.html b/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Divergence.html new file mode 100644 index 00000000..4cfa98d9 --- /dev/null +++ b/debian/openslp-dfsg/openslp-dfsg-1.2.1/doc/html/ProgrammersGuide/Divergence.html @@ -0,0 +1,180 @@ +<!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 - Divergence from RFC 2614</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000"> + +<h2> +Divergence from RFC 2614</h2> + +<hr WIDTH="100%"> +<h3> +SLP Service URLs are required</h3> +SLP Service URL syntax is required for all functions that accept url strings. +The following is a list of affected functions: +<ul> +<li> +<tt>SLPReg()</tt></li> + +<li> +<tt>SLPDeReg()</tt></li> + +<li> +<tt>SLPDelAttrs()</tt></li> + +<li> +<tt>SLPFindAttrs()</tt></li> + +<li> +<tt>SLPParseSrvURL()</tt></li> + +<li> +<tt>SLPSrvURLCallback()</tt></li> +</ul> +The decision to require SLP Service URL syntax was made based on in part +the following scenario: +<blockquote>Suppose that two calls were made to SLPReg() with <tt>srvurl</tt>s +and <tt>srvtype</tt>s of "192.168.100.2","http" and "192.168.100.2","ftp". +Now the developer wants to deregister one service with out deregistering +the other. How can it be done? The SLPDeReg() call does not +have a service type parameter so it would be impossible for the underlying +implementation to distinguish between the two registrations. In attempt +to standardize, OpenSLP expects valid Service URLS.</blockquote> +OpenSLP requires strict Service URL syntax because a Service URL can be +treated as a unique "database key" that identifies a registered service. +Not requiring Service URL syntax allows for several ambiguities like the +one mentioned above. +<br> +<h3> +Scopelist may be the empty string ("")</h3> +In the calls where a scope list is accepted as a parameters, RFC 2614 says +that this parameter may not be the empty string or NULL. +OpenSLP allows scope list to be NULL or the empty string. If the +empty string is passed in as a scopelist, then OpenSLP will use the scopelist +the system administrator has configured for the machine. This saves +99% of all developers the time of calling SLPFindScopes() and parsing the +result. +<p>Scoping is almost entirely an administrative task that is only required +for scalebility of the SLP wire protocol. Having to deal with and +understand scopes will be a burdon to the large majority of programmers. +Unless they are writing some sort of SLP browser, they will be very content +to use the scope that the machine is configured to use. +<br> +<h3> +The SLPSetProperty() is ignored</h3> +The SLPSetProperty() and SLPGetProperty() calls are impossible implement +in a way that would be both scalable and thread safe. The SLPGetProperty() +call could never be made thread safe unless return value was a pointer +to a buffer dynamically allocated the library and freed by the caller. +The SLPSetProperty() call would still access with the data store in such +a way that mutexes would be required to ensure that SLPSetProperty() and +SLPGetProperty() were never used the same buffers at the same time. +Even if a thread safe data store were devised, the SLPGetProperty() call +would be used so frequently during internal operations of the library that +performance might be adversely affected due to mutex bottlenecking or the +amount of processing required to resolve the attribute name to a value. +<br> +<h3> +NULL and empty string are acceptable parameters</h3> +According to RFC 2614, NULL is not exceptable value for any parameter. +Instead programmers are instructed to passed the empty string "". +OpenSLP allows programmers to use either NULL or the empty string. +It is very easy to deal with both NULL or empty string in the implementation, +and allows developers to write more familiar and slightly more efficient +code. There should not be any reason why the compiler should be required +to pass a pointer to a static constant empty string when NULL will do just +a well. This is why the vast majority of C APIs use NULL to +indicate an ignored parameter or default value -- not the empty string +(""). +<br> +<h3> +Incremental registrations an de-registrations</h3> +The only reason I can think of ever wanting to expose the functionality +of incremental registration and deregistration is to represent dynamic +data via SLP attributes. I can think of a long list of reasons why +this is a very very bad idea. With out doubt, it is best to instruct +SLP developers to minimize when ever possible, the number of calls that +ultimately generate SrvReg and SrvDereg messages. If dynamic data +is to be represented, it is best do do it via a specialized protocol optimized +for the given service. OpenSLP does not support incremental registrations +and de-registrations via SLPReg() and SLPDelAttrs() because we have found +that when developers really learn what happens "under the SLP covers" they +are very careful *not* to call then very often. +<p>In addition to poor usage of network resources, incremental registrations +and de-registrations require additional code that decreases the efficiency +of and increases the size, and complexity of API and agent implementations. +<p>The work around for this behavior involves the following: +<ul> +<li> +Design application usage of SLP such that SLP is not used to store great +quantities of data</li> + +<li> +Design application usage of SLP such that SLP is not used to store dynamic +data</li> + +<li> +If the need does arise to add or remove an attribute from an existing registration +simply re-register the service with new attributes as "fresh" registration.</li> +</ul> + +<h3> +Addition of a very simple attribute parsing function</h3> +The following function is secretly included with OpenSLP and has proven +to be very useful. +<p><tt>/*=========================================================================*/</tt> +<br><tt>SLPError SLPParseAttrs(const char* pcAttrList,</tt> +<br><tt> +const char *pcAttrId,</tt> +<br><tt> +char** ppcAttrVal);</tt> +<br><tt>/* +*/</tt> +<br><tt>/* Used to get individual attribute values from an attribute string +that */</tt> +<br><tt>/* is passed to the SLPAttrCallback +*/</tt> +<br><tt>/* +*/</tt> +<br><tt>/* pcAttrList (IN) A character buffer containing a comma separated, +null */</tt> +<br><tt>/* +terminated list of attribute id/value assignments, in */</tt> +<br><tt>/* +SLP wire format; i.e. "(attr-id=attr-value-list)" +*/</tt> +<br><tt>/* +*/</tt> +<br><tt>/* pcAttrId (IN) The string indicating which attribute +value to return. */</tt> +<br><tt>/* +MUST not be null. MUST not be the empty string (""). +*/</tt> +<br><tt>/* +*/</tt> +<br><tt>/* ppcAttrVal (OUT) A pointer to a pointer to the buffer to receive +*/</tt> +<br><tt>/* +attribute value. The memory should be freed by a call */</tt> +<br><tt>/* +to SLPFree() when no longer needed. +*/</tt> +<br><tt>/* +*/</tt> +<br><tt>/* Returns: Returns SLP_PARSE_ERROR if an attribute of the specified +id */</tt> +<br><tt>/* was not +found otherwise SLP_OK +*/</tt> +<br><tt>/*=========================================================================*/</tt> +<br> +<h3> +Some .conf properties are ignored</h3> +See the <a href="../UsersGuide/SlpConf.html">OpenSLP Users Guide</a> for +more details +<br> +</body> +</html> |