gk_runtime(3gk)

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.

AUTHOR

Mark Roseman ([email protected])