# Home    # nevrax.com   
Nevrax
Nevrax.org
#News
#Mailing-list
#Documentation
#CVS
#Bugs
#License
Docs
 
Documentation  
Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages   Search  

How to create a service ?
Author:
Olivier Cado, Vianney Lecroart
Date:
Updated October 30, 2001

Introduction

A service is set of functionalities provided by a server. The class NLNET::IService5 is the base class of all services. This class can be found in the file nel/src/net/service_5.cpp and nel/include/nel/net/service_5.h

Warning:
The class NLNET::IService is still available but is deprecated. 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.
NLNET::IService5 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.

NLNET::IService5 base class is located in NeL, but user-defined services are located in /code/nelns.

A shard is a set of services and contains standard services (that are in /code/nelns ) and your services. To create a shard you must 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.

How to create a user-defined service ?

  1. Create a class inherited from NLNET::IService5.
  2. Create an array of callbacks. Example : 
    void cbPing(CMessage &msgin, const std::string &serviceName, uint16 sid)
{
        // Process the ping message
}

TUnifiedCallbackItem CallbackArray[] =
{
        { "PING", cbPing }
};
  3. 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.
  4. Add in your source file the NLNET_SERVICE_MAIN line, with the following arguments :
  • The name of your class (or NLNET::IService5 if you do not inherit from it (*))
  • The short name of your service (for example "PS" for ping service)
  • Its long name (for example "ping_service" for ping service) (**)
  • The chosen port number (set it to 0 for "auto-assigned by the naming service")
  • The callback array Example: 
    NLNET_SERVICE_MAIN (CMyService, "MS", "my_service", 0, CallbackArray);

    (*) 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 NLMISC::IService5 directly and write NLMISC::IService5 instead of CMyService.

    (**) 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"

    To run your service, create a file "<service_long_name>.cfg" in the working directory, containing the location of your naming service.

    Example: my_service.cfg: 

    NSHost = "itsalive.nevrax.org";
NSPort = 50000;

    Update rules

    Use the setUpdateTimeout() to set the quantum of time use for the network update. You are absolutely certain that your update() function will not be called before this amount of time.

    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 update() .

    If you set the update time-out value to 0, all messages in queue will be processed once before calling the user update() .

    If you set the update time-out value to -1, only one message will be process once before calling the user update() .

    The default time-out is 100ms, therefore the update() function of your service will be called every 100ms or so.

    Examples

    See the NeLNS services source code for examples on how to create a class inherited from NLMISC::IService5.

    Note that some NeLNS services use the old IService class and it's normal because these services are special.

    All your services should use service 5 and if not, you should know exactly how to deal with that.

    See also the net_layer5 samples in the nel/samples/net_layer5 directory.

    Take a look on the nel/include/nel/net/service_5.h and nel/include/nel/net/unified_network.h header for more information about methods.