diff options
Diffstat (limited to 'docs/doxygen/nel/service_howto.html')
| -rw-r--r-- | docs/doxygen/nel/service_howto.html | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/docs/doxygen/nel/service_howto.html b/docs/doxygen/nel/service_howto.html new file mode 100644 index 00000000..a6654a46 --- /dev/null +++ b/docs/doxygen/nel/service_howto.html @@ -0,0 +1,147 @@ +<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> + <TITLE>nevrax.org : docs</TITLE> + <LINK REL=stylesheet TYPE="text/css" HREF="http://www.nevrax.org/inc/css/nevrax.css"> + <link href="doxygen.css" rel="stylesheet" type="text/css"> +</HEAD> +<BODY MARGINHEIGHT="0" MARGINWIDTH="0"> + +<!-- uplinks --> +<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0> + <TR> + <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD> + <TD WIDTH=140 BGCOLOR=#dddddd><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD> + <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD> + <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle> <A CLASS=uplinks HREF=http://www.nevrax.org><b>Home</B></FONT></A> </TD> + <TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle> <A CLASS=uplinks HREF=http://www.nevrax.com><b>nevrax.com</B></FONT></A> </TD> + </TR> +</TABLE> + +<!-- banner Nevrax --> +<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 WIDTH=100%> + <TR><TD BGCOLOR="#000000" BACKGROUND="http://www.nevrax.org/inc/img/black_banner.jpg"><A HREF="http://www.nevrax.org"><IMG SRC="http://www.nevrax.org/inc/img/nevrax.gif" WIDTH="170" HEIGHT="45" BORDER=0 ALT="Nevrax" ></A></TD></TR> +</TABLE> + +<!-- main table --> +<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 height=100%> + <TR> + <TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD> + <TD WIDTH=140 BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT=""> + + <!------ Begin Box ------> + <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=black><TR><TD><TABLE border=0 cellspacing=2 cellpadding=0 width=120><tr><TD ALIGN=middle bgcolor=black> + <FONT COLOR=white FACE="sans-serif"><B>Nevrax.org</B></FONT></TD></TR><tr><td colspan=2 bgcolor=#FFFFFF> + <TABLE cellspacing=0 cellpadding=1 border=0> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="Rubrique news"><img width=13 height=15 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-news.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="News">News</a></td></tr> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Rubrique mail"><img width=15 height=11 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-mail.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Rubrique docs"><img width=14 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-docs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Documentation">Documentation</a></td></tr> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="Rubrique cvs"><img width=13 height=17 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-cvs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="CVS Web">CVS</a></td></tr> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Rubrique bugs"><img width=20 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-bugs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Bugtracking">Bugs</a></td></tr> + <tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="Rubrique license"><img width=18 height=12 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-gpl.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="License">License</a></td></tr> + </TABLE> + </TD></TR></TABLE></TD></TR></TABLE> + <!------ End Box ------> + + </TD> + <TD WIDTH=15><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD> + <TD ALIGN=left valign=top><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT=""> + +<!-- title --> +<TABLE background="http://www.nevrax.org/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td> +<A HREF="http://www.nevrax.org/docs/"><img src="http://www.nevrax.org/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A> +</td><td><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="1" HEIGHT="1" BORDER=0 ALT=""> +</td></tr></table> + + +<!-- block --> +<TABLE bgcolor="#dddddd" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td width=1% valign=middle><img width=6 height=14 hspace=2 vspace=2 src="http://www.nevrax.org/inc/img/reddots.gif"></TD> + <TD><B>Documentation</B></TD> + <TD ALIGN=RIGHT> </td> +</tr></table> +<!-- Generated by Doxygen 1.2.14 --> +<center> +<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="namespaces.html">Namespace List</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="classes.html">Alphabetical List</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="namespacemembers.html">Namespace Members</a> <a class="qindex" href="functions.html">Compound Members</a> <a class="qindex" href="globals.html">File Members</a> <a class="qindex" href="pages.html">Related Pages</a> <a class="qindexRef" doxygen="_cgi:http://www.nevrax.org/cgi-bin/nel-search.cgi" href="http://www.nevrax.org/cgi-bin/nel-search.cgi">Search</a> </center> +<hr><a name="service_howto"><h2>How to create a service ?</h2></a> + <dl compact><dt><b> +Author: </b><dd> +Olivier Cado, Vianney Lecroart</dl><dl compact><dt><b> +Date: </b><dd> +Updated October 30, 2001</dl><a name="service_intro"><h3>Introduction</h3></a> + +<p> +A service is set of functionalities provided by a server. The class <code>NLNET::IService5</code> is the base class of all services. This class can be found in the file <code>nel/src/net/service_5.cpp</code> and <code>nel/include/nel/net/service_5.h</code> +<p> +<dl compact><dt><b> +Warning: </b><dd> +The class <code><a class="el" href="classNLNET_1_1IService.html">NLNET::IService</a></code> is still available but is <b>deprecated</b>. You should transform your old services with the new service5. service and service5 are not compatible so all services in the shard must be based on either the old one or the new one.</dl><code>NLNET::IService5</code> performs automatically the basic functionalities of any service, such as registration to the Naming Service, server start-up and shutdown, argument and config file parsing. +<p> +<code>NLNET::IService5</code> base class is located in NeL, but user-defined services are located in <code>/code/nelns</code>. +<p> +A shard is a set of services and contains standard services (that are in <code>/code/nelns</code> ) and your services. To create a shard you <b>must</b> have at least the naming_service running, other services are optional but should be launch. All services try to connect to the admin_executor_service on the localhost so you should run it on every server to prevent this connection from failing (services retry to connect to the admin_executor_service evenly). You can launch the admin_service if you want to use the admin system. You can launch the login_service and welcome_service if you want to use client authentification. +<p> +<a name="service"><h3>How to create a user-defined service ?</h3></a> + +<p> +<ol> +<li>Create a class inherited from <code>NLNET::IService5</code>.<li>Create an array of callbacks. Example : <div class="fragment"><pre><font class="keywordtype">void</font> cbPing(CMessage &msgin, <font class="keyword">const</font> std::string &serviceName, uint16 sid) +{ + <font class="comment">// Process the ping message</font> +} + +TUnifiedCallbackItem CallbackArray[] = +{ + { <font class="stringliteral">"PING"</font>, cbPing } +}; +</pre></div><li>Reimplement the methods init(), update() and release() of the class if you need to (optional). After each call to update(), the service will update all network connections (and call your callbacks), check if config files have changed and flush buffers of outgoing data.<li>Add in your source file the <code>NLNET_SERVICE_MAIN</code> line, with the following arguments :</ol> +<ul> +<li>The name of your class (or <code>NLNET::IService5</code> if you do not inherit from it (*))<li>The short name of your service (for example "PS" for ping service)<li>Its long name (for example "ping_service" for ping service) (**)<li>The chosen port number (set it to 0 for "auto-assigned by the naming service")<li>The callback array</ol> +Example: <div class="fragment"><pre><a class="code" href="service_8h.html#a0">NLNET_SERVICE_MAIN</a> (CMyService, <font class="stringliteral">"MS"</font>, <font class="stringliteral">"my_service"</font>, 0, CallbackArray); +</pre></div> +<p> +(*) Note: if your service does nothing else than calling your callbacks, i.e. init(), update() and release() are empty, you don't need to create a new class : you can use <code>NLMISC::IService5</code> directly and write <code>NLMISC::IService5</code> instead of <code>CMyService</code>. +<p> +(**) Note: the long name is used to find the config file. If the long name is "ping_service" the service will try to open the config file named "ping_service.cfg" +<p> +To run your service, create a file "<service_long_name>.cfg" in the working directory, containing the location of your naming service. +<p> +Example: my_service.cfg: <div class="fragment"><pre>NSHost = <font class="stringliteral">"itsalive.nevrax.org"</font>; +NSPort = 50000; +</pre></div> +<p> +<a name="services_update"><h3>Update rules</h3></a> + +<p> +Use the <code>setUpdateTimeout()</code> to set the quantum of time use for the network update. You are absolutely certain that your <code>update()</code> function will <b>not</b> be called <b>before</b> this amount of time. +<p> +If you set the update time-out value higher than 0, all messages in queue will be processed until the time becomes greater than the time-out, before calling the user <code>update()</code> . +<p> +If you set the update time-out value to 0, all messages in queue will be processed once before calling the user <code>update()</code> . +<p> +If you set the update time-out value to -1, only one message will be process once before calling the user <code>update()</code> . +<p> +The default time-out is 100ms, therefore the <code>update()</code> function of your service will be called every 100ms or so. +<p> +<a name="services_examples"><h3>Examples</h3></a> + +<p> +See the NeLNS services source code for examples on how to create a class inherited from <code>NLMISC::IService5</code>. +<p> +Note that some NeLNS services use the old IService class and it's normal because these services are special. +<p> +All your services should use service 5 and if not, you should know exactly how to deal with that. +<p> +See also the net_layer5 samples in the <code>nel/samples/net_layer5</code> directory. +<p> +Take a look on the <code>nel/include/nel/net/service_5.h</code> and <code><a class="el" href="unified__network_8h.html">nel/include/nel/net/unified_network.h</a></code> header for more information about methods. +<p> + + +<!-- footer --> +<BR><FONT Size=+5> </FONT> +</TD> +<TD WIDTH=15><IMG SRC=http://www.nevrax.org/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD> +</TR> +</TABLE> +</BODY> +</HTML> |