File 'net/server.cls' (part of 'Pool_Net')


Home | Packages | Files | Procedures | Classes | Keywords | External packages


Written by
Andreas Kupries
Description
Framework for construction of line-oriented servers (like smtp, pop3, ...). See background for more information and net/pop3/server.cls for an example of its usage. See net/serverUtil.tcl too.
Keywords
Server, Framework for servers, Construction of servers

Class 'server'

Description
Base class for the construction of servers handling a line and command oriented protocol like SMTP, POP3, etc. Actual server classes should derive from it.
Membervariables
cmdMap, connMap, port, sockMap
Methods
Attach, CloseConnection, Detach, DoCloseConnection, GreetPeer, HandleCommand, HandleNewConnection, HandleUnknownCmd, InitializeNewConnection, Log, Respond2Client, SetCmdMap, managesSock, reportError, server, start, ~server

cmdMap
Maps a command name to the method handling it. Must be set by subclasses, see SetCmdMap.
connMap
Together with sockMap the fundamental datastructure of a server. This array maps from internal connection ids to the handle of the socket used to talk to the client.
port
The port the server shall listen on for new connections. Must be set by subclasses. The default value causes an error in start.
sockMap
Together with connMap the fundamental datastructure of a server. This array maps from socket handles to a 3-element list containing the remote host, remote port and internal connection id of the connection running over the socket.

Attach (connId)

Reenables listening for commands for the given connection. See Detach too.
Argument: connIdConnection identifier referencing into connMap.

CloseConnection ()

Abstract method. Called by DoCloseConnection to execute class specific code. Should do any class specific cleanup for the connection in destruction.

Detach (connId)

After this call the given connection does not listen for commands anymore. This is useful to allow temporary operation of 'fcopy' et. al. The complementary command is Attach.
Argument: connIdConnection identifier referencing into connMap.

DoCloseConnection (connId)

Closes the connection described by connId. Must be associated to this server. Closes the associated channel, then cleans and destroys the connection descriptor. Uses the abstract method CloseConnection to execute class specific code.
Argument: connIdConnection identifier referencing into connMap.

GreetPeer (connId)

Abstract method. Called by HandleNewConnection to execute class specific code. Should sent a greeting message to the new client.
Argument: connIdConnection identifier referencing into connMap.

HandleCommand (connId sock)

Called by the event system after arrival of a new command for connection connId.
Argument: connIdConnection identifier referencing into connMap.
Argument: sockDirect access to the channel representing the connection.

HandleNewConnection (sock rHost rPort)

A new connection to the server was opened. The connection descriptor is generated and initialized. A greeting will be sent upon sucessful completion of this task. In case of a failure the connection is closed immediately, without any response. Uses the abstract methods InitializeNewConnection and GreetPeer to execute class specific setup code and the greeting of the new client.
Notes: This is the part of the code you have to change if you want to implement a host based access scheme.
Argument: sockThe channel handle of the new connection.
Argument: rHostThe host the client resides on.
Argument: rPortThe port used by the client.

HandleUnknownCmd (connId cmd line)

Standard way of handling an unknown command sent by the client to us. The 'error' is catched in HandleCommand, reported via
Argument: connIdConnection identifier referencing into connMap.
Argument: cmdThe name of the command not understood by the server.
Argument: lineThe complete line sent by the client.

InitializeNewConnection (connId)

Abstract method. Called by HandleNewConnection to execute class specific code. Should do any class specific initializations for the new connection.
Argument: connIdConnection identifier referencing into connMap.

Log (level args)

Convenience method, wraps around the syslog interface, automatically adds the server handle to the written text. See ::pool::syslog::syslog too.
Argument: levelRelative importance of the logged message. Should be one of the strings returned by ::pool::syslog::levels.
Argument: argsList containing the texts to log.

Respond2Client (conn ok text)

Internal procedure. Writes a response text to the client represented by conn. To the caller it is equivalent to the builtin 'return'.
Argument: connDescriptor of connection to write to.
Argument: okPrimary response, specific to the server subclass
Argument: textAdditional text following the primary response.

SetCmdMap (map)

Used by derived classes to establish the mapping from command names to their handler methods.
Argument: mapThe mapping in 'array set/get' format.

managesSock (sock)

Used by the custom background handler in net/serverUtil.tcl to check wether a socket is handled by the queried server or not.
Argument: sockThe handle of the socket to look for.
Returns: a boolean value. 1 indicates that the socket is handled here.

reportError (sock errmsg)

Reports an error in the underlying server, closes the affected connection.
Argument: sockHandle of the channel representing the connection.
Argument: errmsgThe message to print out.

server ()

Constructor. Installs the custom background error handler upon the first call, see net/serverUtil.tcl. Always registers the new server in the map (<cv servers>) used by the error handler.

start ()

A server is dormant until this method is called.

~server ()

Destructor. This closes all currently open connections too.


Generated by AutoDoc 2.1 at 02/20/1999, invoked by Andreas Kupries