openserver() , closeserver() , serveruser() , servergroup() , serverpass() - Connect and disconnect from service

SYNOPSIS

#include <sys/types.h>
#include "tstone.h"
SERVER *openserver(char *hostname,char *port);
SERVER *closeserver(SERVER *serverhandle);
int     serveruser(char *username);
int     servergroup(char *groupname);
int     serverpass(char *password);

DESCRIPTION
These rather generic sounding functions are for establishing or disconnecting a communication channel to a Thunderstone Server. The presumption is made that the host and port you open is the correct one for the type of calls you will be making.

In general, the openserver() call returns a handle to the requested service at the specified hostname and port. The returned handle is of the type SERVER * and will have the value SERVERPN if there's a problem.

The closeserver() call shuts the open communication channel with a server and frees the allocated memory on both the client and the server associated with the connection. closeserver() will return the value SERVERPN.

The hostname is a string that is the given internet name or number of the machine on which the requested service is running. For example: thunder.thunderstone.com or 198.49.220.81. The port number is also a string, and is the port number assigned to the service when it is brought up initially on the server machine. The port number may also be assigned a name of a service that is enumerated in the file /etc/services.

Either hostname or port or both may be the empty string ("") indicating that the compiled in default is to be used. The default for hostname is "localhost" indicating the same machine that the client application is running on. The default port is "10000" for Metamorph and "10002" for Texis.

The serveruser(), servergroup(), and serverpass() calls set the user name, group name, and password, respectively, that openserver() will use when logging into the server. These functions will return zero on error. Non-zero is returned on success. If servergroup() is not used, the user will be logged into their default group as defined by the server.

The default user name and password are both the empty string ("").

If no user name is given then Texis will default to PUBLIC. If a user name and password is given then Texis will verify them against the users defined in Texis. You can use tsql to add users. See Chapter here for an in-depth discussion of security.

EXAMPLE

SERVER *se;                              /* network server pointer */
 SRCH   *sr;                                      /* search pointer */

                                           /* connect to the server */
 if(serveruser("me")         &&
    servergroup("somegroup") &&
    serverpass("mypassword") &&
    (se=openserver("thunder.thunderstone.com","666"))!=SERVERPN)
    {
     n_reghitcb(se,(void *)NULL,mycallback);  /* setup hit callback */
     if((sr=n_setqry(se,"power struggle"))!=SRCHPN)  /* setup query */
         {
          if(!n_search(se,sr))                     /* find all hits */
              puts("n_search() failed");
          n_closesrch(se,sr);                  /* cleanup the query */
         }
     closeserver(se);                     /* disconnect from server */
    }

CAVEATS
Make sure you are talking to the right port!

SEE ALSO
/etc/services, services(4)