dt_evict

Daylight v4.9
Release Date: 1 February 2008

Name

dt_evict - evict clients from a server

Generic Prototype

dt_evict(dt_Handle, dt_String, dt_String) => dt_Boolean

C Prototype

#include "dt_thor.h"

dt_Boolean dt_evict(dt_Handle object, dt_Integer alen, dt_String auth_pw, dt_Integer ulen, dt_String username, dt_Handle message, dt_Boolean do_eviction)

FORTRAN Prototype

include 'dt_f_thor.inc'

logical dt_f_evict(object, auth_pw, username, message, do_eviction)

integer*4 object
character*() auth_pw
character*() value
character*() username
integer*4 message
logical do_eviction

Description

Evict a client or all clients from a server or database.

WARNING: Evicting clients should be avoided in almost all situations. Eviction should only be considered after strategies, such as "Please log out now" messages (see dt_setmessage(3)) have been attempted, and clients have been given the opportunity to save work in progress.

If 'do_eviction' is TRUE, then evictions proceed as follows. If 'object' is a Thor or Merlin server, the client's connection to the server is broken and the client is "logged out." If 'object' is a Thor or Merlin database, the client's connection to the database is broken, and the client has no further access to the database. In either case, the client gets an error message indicating that he/she has been "evicted" from the server or database. All of the client's work in progress on the server or database is lost.

The string 'auth_pw' is a password to authorize the eviction. If the object is a Thor or Merlin server, then the password must match that of the user "thor". If the object is a database, then the password must match the executive password for the database.

The string 'username' is of the form "user@host", and specifies which client or clients are to be evicted (see dt_getusers(3), thorwho(1)). An empty (zero-length) username indicates that all other clients (i.e. all clients except the one invoking this function) are to be evicted. If the name is ambiguous (i.e. several clients have logged in using the same name, and that name matches 'username'), all of them are evicted.

The object 'message' contains a message that is sent to all users whose names match 'username' (or all users if 'username' is an empty string). It can be any object that responds to dt_stringvalue(3), or a sequence or stream of such objects. If the object is not a stream or sequence, then its stringvalue is the message that is sent as a single "NOTE:" in the error queue. If it is a sequence or stream, each object it contains will be a separate "NOTE:" in the error queue. If an object returns the 'invalid string', it is replaced by a string of length zero (""). If 'message' is a sequence or stream, it is reset (see dt_reset(3)). If 'message' is NULL_OB, then no message is sent.

The parameter 'do_eviction' controls whether eviction takes place: If it is TRUE, then clients are evicted as described above. If FALSE, then no clients are evicted, but the function sends the message and returns the number of users who would have been evicted if 'do_eviction' were TRUE. This feature can be used, for example, to send users a warning and allow a "grace" period before doing the actual eviction.

Note that this does not deallocate server and database objects in the client's program; it simply makes them unusable. For example, the object represented by the handle returned by dt_thor_server(3) in an evicted client's program remains a valid object, but any further attempts by the client program to communicate with the server via the object will fail and will generate an error message.

Return Value

Returns the number of users whose name matches 'username' -- i.e. the number actually or potentially evicted, depending on 'do_evictions'. Returns -1 if a problem is detected, such as an incorrect password.

Bugs

There is nothing to prevent an evicted client from immediately re-establishing a connection to the server or re-opening the database.