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 dynamicly 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.

  The best way to see how all of this works is to examine the source code
for the print spooler service and it's client.  These two pieces of code
detail some of the finer points with writing a service that haven't been
covered in this section.


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 Manage configuration
tool and add your service.  That's it!



