CommsStack Class

A CommsStack object allows you to stack communications modules to build a tailored communications channel to a remote service.

This is most commonly done by use of the script function buildStack but you can also build one 'by hand' if you require.

CommsStack Creation

The create function can be used to create a CommsStack object eg.

    (create CommsStack)

This newly-created stack does not contain any modules -- so it cannot yet do any communications. The modules can then be placed on the stack using the push method.

The CommsStack is simply a holder for its modules. It does nothing by itself -- instead, it uses its contained modules to provide the communications channel you require.

The order of modules on the stack is important. For example, the bottom module (ie. the one pushed on first) must do 'real' communications such as TCP/IP or TAPI. All higher modules (pushed on subsequently) do various 'protocol-related' tasks like Telnet etc.

CommsStack Properties

A CommsStack object supports the following properties:

property name	property type	description
`depth`	Integer	the no. of modules on the stack
`top`	CommsModule	the top-most module on the stack -- this can be any of the particular comms modules supported by Carapace
`bottom`	CommsModule	the bottom-most module on the stack -- this can be any of the particular comms modules supported by Carapace

CommsStack Methods

A CommsStack object supports the following methods:

method name	description
`push`	push the supplied module onto the stack -- it therefore becomes the top of the stack
`pop`	pop the supplied module from the stack -- this removes the top-most module
`set`	set the supplied attribute -- this is placed on the top-most module in the stack which supports that attribute
`get`	get the supplied attribute -- this is retrieved from the top-most module in the stack which supports that attribute
`hasAttribute`	tests if there is a module on the stack which supports the supplied attribute
`attributes`	list the configured attributes of all the contained comms modules
`info`	return a snapshot of the data transfer information from te top module on the stack
`layer`	return the module at the nth layer -- the bottom is layer 0

In addition, the standard comms module methods are supported.

NOTE: The following methods operate on the entire stack of modules, and not simply on any individual module within the stack.

method name	description
`connect`	connect this stack
`receive`	receive data
`receiveInto`	receive data into the supplied buffer
`send`	send data
`disconnect`	disconnect this stack
`bind`	bind address information for the entire stack
`listen`	prepare to listen for new connections
`accept`	wait for a new connection to arrive and, if it does, accept it -- if successful, this returns a new `CommsStack` which can be used to communicate with the remote client

`push`

Push the supplied module onto the stack -- it therefore becomes the top of the stack.

Arguments:

module CommsModule

Return type: the empty List () is returned.

`pop`

Pop the supplied module from the stack -- this removes the top-most module.

Arguments: none

Return type: the empty List () is returned.

`set`

Set the supplied attribute -- this is placed on the top-most module in the stack which supports that attribute.

Arguments:

name	`String`
value	`Object`

Return type: String -- an error is raised no module on the stack supports the attribute.

`get`

Get the supplied attribute -- this is retrieved from the top-most module in the stack which supports that attribute.

Arguments:

name String

Return type: Object -- an error is raised if is raised no module on the stack supports the attribute.

`hasAttribute`

Tests if there is a module on the stack which supports the supplied attribute.

Arguments:

name String

Return type: the Symbol true is returned if the attribute is supported, otherwise the empty List () is returned.

`attributes`

List the configured attributes of all the contained comms modules.

Arguments: none

Return type: List

`info`

Return a snapshot of the data transfer information from the top module on the stack. The information is returned in a CommsInfo object.

Arguments: none

Return type: CommsInfo

`layer`

Return the module at the nth layer -- the bottom is layer 0. The depth property returns the number of layers.

Arguments:

n Integer

Return type: CommsModule

Contents

Index

Current topic: communications

Related topics: communications classes, objects