home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 1.2 / amidev_cd_12.iso / contrib / iam / networking / envoy-2.0 / obs / services < prev    next >
Encoding:
Text File  |  1994-12-22  |  5.1 KB  |  127 lines
  1. /*------------------------------------------------------------------------*/
  2. /*                                                                        *
  3.  *  $Id: Services 1.1 1994/11/29 13:36:31 heinz Exp $
  4.  *                                                                        */
  5. /*------------------------------------------------------------------------*/
  6.  
  7. Envoy Services
  8. ==============
  9.  
  10. I. Introduction
  11. ---------------
  12.  
  13.   One of the problems when writing client-server applications is
  14. determining exactly how the client is supposed to initiate a
  15. connection with a server. Another problem is deciding how and when the
  16. server's process is to be started.  It would seem desirable to have a
  17. system that provided a standard way to handle both problems.  This is
  18. where the Envoy Services system comes into play.
  19.  
  20.   The Envoy Services system is designed to standardize the way in
  21. which nipc client applications initiate connections with nipc servers.
  22. This is done by providing a services.library that deals with locating
  23. the requested service on the remote machine and making the connection
  24. to the server.
  25.  
  26.   The other problem, that of how and when to start servers, is handled
  27. on the "server side" of the connection via the Envoy Services Manager.
  28. The Envoy Services Manager receives requests for services from the
  29. client machine and then passes this information on to an Envoy Service
  30. which then takes any actions that are required to activate the server.
  31.  
  32.   The Envoy Services themselves are implemented as Amiga shared
  33. libraries. By using this model, Services may be dynamically loaded
  34. from disk, and may also be flushed if they are inactive.  Services
  35. also make use of special library LVO's that are used to start
  36. services, query the service, etc.
  37.  
  38.  
  39. II. How does a client make a connection to a Service?
  40. -----------------------------------------------------
  41.  
  42.   The first step in connecting to a service is to open nipc.library
  43. and the services.library.  You must use nipc.library to create the
  44. Entity that you will be using for your side of the communications
  45. path. Then, you call the services.library function FindService() which
  46. will make an attempt to connect to the service you are requesting to
  47. use.
  48.  
  49. Example:
  50.  
  51.      ...
  52.  
  53.      if(svc_entity = FindService("Cruncher","Printer Service",my_entity,
  54.                                  FSVC_UserName,"Joe",
  55.                                  FSVC_Password,"Joe's Password",
  56.                                  FSVC_Error, &error_code,
  57.                                  TAG_DONE)
  58.      {
  59.         ...
  60.  
  61.   FindService() requires that you specify the name of the host that
  62. the service you want to use is located on (in the above case,
  63. "Cruncher") , the name of the service ("Printer Service"), and the
  64. Entity that you will use for your side of the connection.  You may
  65. also optionally specify a user's name, a user's password or a pointer
  66. to a ULONG that will be filled in with an error code (if any) if the
  67. connection failed. For more information, please see the
  68. services.library/FindServce() autodoc.
  69.  
  70.  
  71. III. How do I disconnect from a Service?
  72. ----------------------------------------
  73.  
  74.   To disconnect from a Service you simply call the services.library
  75. function LoseService() with a pointer to the Entity returned by
  76. FindService().
  77.  
  78. Example:
  79.  
  80.         ...
  81.         LoseService(svc_entity);
  82.         ...
  83.  
  84.  
  85. IV. So, how do I write a Service?
  86. ---------------------------------
  87.  
  88.   Before you write a service, you should have a good grasp on writing
  89. Amiga shared libraries.  An example shared library can be found in the
  90. Amiga Libraries RKM.
  91.  
  92.   Each Service must implement at least two LVO's that are used by the
  93. Envoy Services Manager and it's configuration tool.  These two LVO's
  94. are StartService() and GetServiceAttrs().  StartService() is called by
  95. Services Manager when there is a new request for a service from a
  96. client. The second call, GetServiceAttrs() is used byt the Services
  97. Mangager configuration tool to determine the name of your service (not
  98. to be confused with your Service's filename).
  99.  
  100.   When the Services Manager calls your StartService() function, you
  101. must take whatever steps are required to start providing your service
  102. to the requesting client.  You will be passed information such as the
  103. name of the user and his password.  You will also be passed a pointer
  104. to string that you are to fill in with the name of the Entity that the
  105. client should connect to.
  106.  
  107.   Depending on how you are designing your service, you may or may not
  108. need to start a new task for each client that connects to you.  You
  109. will need at least one task, however. There currently is no way to
  110. have a task-less service.
  111.  
  112.   When your StartService() function returns, the Services Manager will
  113. reply to the client's request for service with the name of the Entity
  114. it should connect to or will return an error code if you could not
  115. start the service for some reason.
  116.  
  117.  
  118. V. How do I make the Envoy Services Manager aware of my service?
  119. ----------------------------------------------------------------
  120.  
  121.   All you have to do to to make the Services Manager start accepting
  122. requests for your service is to run the Services Manager configuration
  123. tool and add your service.  That's it!
  124.  
  125.  
  126.  
  127.