/*------------------------------------------------------------------------*/
/*                                                                        *
 *  $Id: Services 1.1 1994/11/29 13:36:31 heinz Exp $
 *                                                                        */
/*------------------------------------------------------------------------*/

Envoy Services
==============

I. Introduction
---------------

  One of the problems when writing client-server applications is
determining exactly how the client is supposed to initiate a
connection with a server. Another problem is deciding how and when the
server's process is to be started.  It would seem desirable to have a
system that provided a standard way to handle both problems.  This is
where the Envoy Services system comes into play.

  The Envoy Services system is designed to standardize the way in
which nipc client applications initiate connections with nipc servers.
This is done by providing a services.library that deals with locating
the requested service on the remote machine and making the connection
to the server.

  The other problem, that of how and when to start servers, is handled
on the "server side" of the connection via the Envoy Services Manager.
The Envoy Services Manager receives requests for services from the
client machine and then passes this information on to an Envoy Service
which then takes any actions that are required to activate the server.

  The Envoy Services themselves are implemented as Amiga shared
libraries. By using this model, Services may be dynamically loaded
from disk, and may also be flushed if they are inactive.  Services
also make use of special library LVO's that are used to start
services, query the service, etc.


II. How does a client make a connection to a Service?
-----------------------------------------------------

  The first step in connecting to a service is to open nipc.library
and the services.library.  You must use nipc.library to create the
Entity that you will be using for your side of the communications
path. Then, you call the services.library function FindService() which
will make an attempt to connect to the service you are requesting to
use.

Example:

     ...

     if(svc_entity = FindService("Cruncher","Printer Service",my_entity,
                                 FSVC_UserName,"Joe",
                                 FSVC_Password,"Joe's Password",
                                 FSVC_Error, &error_code,
                                 TAG_DONE)
     {
        ...

  FindService() requires that you specify the name of the host that
the service you want to use is located on (in the above case,
"Cruncher") , the name of the service ("Printer Service"), and the
Entity that you will use for your side of the connection.  You may
also optionally specify a user's name, a user's password or a pointer
to a ULONG that will be filled in with an error code (if any) if the
connection failed. For more information, please see the
services.library/FindServce() autodoc.


III. How do I disconnect from a Service?
----------------------------------------

  To disconnect from a Service you simply call the services.library
function LoseService() with a pointer to the Entity returned by
FindService().

Example:

        ...
        LoseService(svc_entity);
        ...


IV. So, how do I write a Service?
---------------------------------

  Before you write a service, you should have a good grasp on writing
Amiga shared libraries.  An example shared library can be found in the
Amiga Libraries RKM.

  Each Service must implement at least two LVO's that are used by the
Envoy Services Manager and it's configuration tool.  These two LVO's
are StartService() and GetServiceAttrs().  StartService() is called by
Services Manager when there is a new request for a service from a
client. The second call, GetServiceAttrs() is used byt the Services
Mangager configuration tool to determine the name of your service (not
to be confused with your Service's filename).

  When the Services Manager calls your StartService() function, you
must take whatever steps are required to start providing your service
to the requesting client.  You will be passed information such as the
name of the user and his password.  You will also be passed a pointer
to string that you are to fill in with the name of the Entity that the
client should connect to.

  Depending on how you are designing your service, you may or may not
need to start a new task for each client that connects to you.  You
will need at least one task, however. There currently is no way to
have a task-less service.

  When your StartService() function returns, the Services Manager will
reply to the client's request for service with the name of the Entity
it should connect to or will return an error code if you could not
start the service for some reason.


V. How do I make the Envoy Services Manager aware of my service?
----------------------------------------------------------------

  All you have to do to to make the Services Manager start accepting
requests for your service is to run the Services Manager configuration
tool and add your service.  That's it!



