---
name: "gk_server"
section: "3gk"
platform: "linux"
package: "groupkit"
version: "3.2-1"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/gk_server"
---

# gk\_server(3gk)

GroupKit client/server/peer support

## NAME

gk\_createServer, gk\_connectToServer, gk\_connectToPeer, gk\_shutdownServer -  GroupKit client/server/peer support

## SYNOPSIS

- **gk\_createServer** *env port keyfield ?info?*

  - **gk\_connectToServer** *host port info*

  - **gk\_connectToPeer** *host port*

  - **gk\_shutdownServer**

  - **gk\_serverQueryID** *callback*

  ## DESCRIPTION

These commands provide a level on top of Tcl-DP's RPC Client/Server routines.  The extra functionality is there to maintain a list of  clients connected to the server, along with information about each of these clients.

This information is stored in GroupKit **environments**.  When a server is created, an environment is specified which will hold information about all remote clients during the time they are connected to the server; this environment must already exist.   Information on remote clients is stored under the "remote" key in the environment.  Each client's information is stored under a key; this key may be assigned via the server, or be included in the client's information.  If the key is to be supplied by the client, the server must be provided with the name of the field holding the  key.

GroupKit **events** are generated whenever clients connect or  disconnect from the server.  An event of type **clientConnected**  is generated after a client connects and provides its information. The attribute **key** in the event specifies the key for the client. When a client disconnects, and immediately before information on the client is destroyed, an event of type **clientDisconnected** is  generated, again with a **key** attribute.

When a client provides its information to the server, the server supplements this information with the file descriptor which can be used to communicate with the client.  This is stored in the client's information under "remote.key.filedesc".

Peer connections are similar to client/server connections except that rather than the client providing information to the server, both ends of the peer provide information to the other.  When using a peer connection, information on the local peer is found under the "local" key in the environment.

## COMMANDS

- **gk\_createServer** *env port keyfield ?info?*

  Gk\_createServer creates a new server, running on the specified *port*. The environment *env* is used to hold information about each of the connected clients, under the "remote" key. *keyfield* specifies the name of the key in the client's information (e.g. usernum) to use to store information in the environment; if specified as "", the server will use a built-in counter for this purpose.   The parameter *info* may be used to import information about the server (or local peer, as the case may be) under the "local" key in the environment. This command returns the port number the server is listening on.

- **gk\_connectToServer** *host port info*

  Gk\_connectToServer opens up a connection to the given server (created with gk\_createServer, above), and arranges for the client information stored as a keyed list in "info" to be sent to the server as identification.  This command returns the file descriptor used for communicating with the server.

- **gk\_connectToPeer** *host port*

  Gk\_connectToPeer works similarly to **gk\_connectToServer** except that a peer connection is opened.  Local information, found under the "local" key in the environment, is sent to the remote peer, and information from the remote peer is received.

- **gk\_shutdownServer**

  Gk\_shutdownServer terminates the server; all socket connections are closed.

- Servers maintain a unique id number for each connected client; sometimes

  this can be useful to clients for their own purposes.  When a connected client sends this command to the server, the server will send back to the client a response consisting of the *callback* parameter appended with the server's id number for this client.

## SEE ALSO

dp\_rpc(n), environment(n), gk\_toAll(n)

## LIMITATIONS

Only one server per interpreter is permitted, since we're not keeping track of which socket the low level accept() occured on. As well, if a keyfield is specified in gk\_createServer but that field  is not found in the client's info, the client will not be added to the  environment.

## AUTHOR

Mark Roseman (roseman@cpsc.ucalgary.ca)