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

# gk\_runtime(3gk)

description of GroupKit conference runtime environment

## NAME

gk\_runtime - description of GroupKit conference runtime environment

## DESCRIPTION

This manual entry describes the runtime environment of GroupKit conferences and the way its information may be accessed. This document is broken into several sections: creating the runtime environment, events generated by GroupKit conferences, and extracting information from the runtime environment.

This manual entry assumes knowledge of two constructs used in GroupKit: events and environments.  See *gk\_newenv(n)* and *gk\_event(n)* respectively.

## CREATING THE RUNTIME ENVIRONMENT

The runtime environment for conferences is created via  **gk\_initConf**.  This routine must be passed several pieces of information that describe the conference, including information about the local user.  This information is passed to the conference program by the registrar client that created it on its command line.  It is therefore sufficient to pass **gk\_initConf** the conference's command line arguments (*argv*).

## GROUPKIT CONFERENCE EVENTS

The runtime environment for GroupKit conferences will automatically take care of users joining and leaving conferences, under the  direction of its registrar client.  However, if your conference needs to know about these circumstances, a number of events are  generated.

Note that your program can intercept these events using either the gk\_on(n) mechanism, or the gk\_bind(n) mechanism.

- **newUserArrived**

  An event of this type is generated when a new user is joined to the conference.  The attribute *usernum* contains the user number of the newly arrived user, which may be used to find out further information, as described below.

- **userDeleted**

  An event of this type is generated when a user leaves the conference. The attribute *usernum* contains the user number of the departing user.  At this point, the user's information has not yet been deleted, so it can be queried as described below.

- **updateEntrant**

  An event of this type is sent to one existing user in the conference when a new user joins.  The recipient of this event can bring the new user up to date (for example, by sending them a copy of the current conference state) if this is required by the conference.  The  attribute *usernum* specifies the new user to be updated.

## EXTRACTING INFORMATION FROM THE RUNTIME ENVIRONMENT

GroupKit maintains the "users" environment containing information about all conference users, including the local user.  The  information in this environment may be accessed directly, for  example as "users local.username" or "users remote.1.username" to retrieve the user name of either the local user or the remote user having user number 1.  See the description of peer connections in the *gk\_server(n)* manual entry for more information on how  the environment is organized.

The entry for each user minimally provides the following information: "userid", "host", "port", and "username".  As well, additional information  about the local user, the conference itself and the registrar client that spawned it can be found as "local.usernum", "local.confnum",  "local.reghost" and "local.regport".  Additional attributes may be added, and existing ones changed, but do the latter at your own risk!

The following commands are also available to retrieve and change information in the "users" environment.  They are provided for compatibility with earlier versions of GroupKit; it is preferable to access the environment directly.

- **gk\_getUserAttrib** *usernum attribute*

  This command retrieves the value of *attribute* for the given *usernum*.   *Usernum* may specify either the local or a remote user.

- **gk\_setUserAttrib** *usernum attribute value*

  This command sets the attribute specified by *attribute* for *usernum* to be *value*. *Usernum* may specify either the local or a remote user.

- **gk\_getLocalAttrib** *attribute*

  This command retrieves the value of *attribute* for the local user.

- **gk\_setLocalAttrib** *attribute value*

  This command sets the attribute specified by *attribute* for the local user to be *value*.

## USER PREFERENCES

There is also an environment called "userprefs" which holds user  preference information.  This is read in from the user's .groupkitrc file.  This environment is supplemented with the following information:

- **userprefs host**

  This holds the name of the host the conference is running on.

- **userprefs port**

  This holds the port number of the socket that listens for connections from other conference processes.

- **userprefs scriptpath**

  This holds the name of the directory path where the Tcl script for the conference was located.  The full path including the file name can be retrieved via the Tcl global **argv0**.

## SEE ALSO

gk\_server(n), gk\_initConf(n), gk\_event(n), gk\_newenv(n), gk\_toAll(n)

## AUTHOR

Mark Roseman (roseman@cpsc.ucalgary.ca)