Communication Modules

All communication modules within Carapace share a set of methods -- these are based on the 'socket' approach to communications originating from Unix.

Module Creation

The create function can be used to create an Xxxx module eg.

    (create Xxxx)

where Xxxx is the name of the module eg. Tcp.

Once created, this module is tailored using its properties and methods.

Module Properties

The only standard property is as follows:

property name	property type	description
`log`	Log	a log for the communications

All other properties are module-specific.

Module Methods

The following methods are common to all comms modules:

method name	description
`connect`	connect this module
`receive`	receive data
`receiveInto`	receive data into the supplied buffer
`send`	send data
`disconnect`	disconnect this module
`bind`	bind address information for this module
`listen`	prepare to listen for new connections
`accept`	wait for a new connection to arrive and, if it does, accept it
`set`	set the value of an attribute on the stack
`get`	get the value of an attribute from the stack
`do`	invoke a module-specific method on the stack

A module may, and usually does, support other methods as well.

`connect`

Connect this module.

If this is the bottom module of the stack then it attempts to connect directly to its peer. If this is not the bottom module, then it attempts to connect to its peer by communicating through the module directly below it on the stack.

Arguments: none -- since all address information is set up as properties of the module.

Return type: the empty List () is returned. An error is raised if the connection fails.

`receive`

Receive data from its peer -- either directly (if this is the bottom module) or via the layer below in the stack.

Arguments:

timeout Integer

Return type: Object -- an error is raised if no data is received in time.

`receiveInto`

Receive data from its peer into the supplied buffer.

Arguments:

buffer	`Buffer`
timeout	`Integer`

Return type: the empty List () is returned.

`send`

Send the supplied data to the peer -- an error is raised if not all the data could be sent in a suitable time.

Arguments:

data	an Object -- typically `String` or `Binary` or `Buffer`

Return type: the empty List () is returned.

`disconnect`

Disconnect this module from its peer.

Arguments: none

Return type: the empty List () is returned. An error is raised if the disconnection fails.

`bind`

Bind address information for this module. The address information is set up as properties of the module.

Arguments: none

Return type: the empty List () is returned. An error is raised if the binding fails -- this may happen if the address is already in use etc.

`listen`

Prepare to listen for new connections. The number of queued connections (the 'backlog') is supplied.

Arguments:

backlog Integer

Return type: the empty List () is returned. An error is raised if the disconnection fails.

`accept`

Wait for a new connection to arrive and, if it does, accept it.

Arguments:

timeout Integer

Return type: If a new connection is received in time, then a comms module of the same sort as this one is returned, otherwise the empty List () is returned.

`set`

Set the value of an attribute on the stack. The stack is searched from the top down for a module which supports this attribute. If such a module is found, the attribute is set on that module. An error is raised if there is no module on the stack which supports this attribute.

Arguments:

attributeName	`String`
value	`Object`

Return type: the empty List () is returned.

`get`

Get the value of an attribute from the stack. The stack is searched from the top down for a module which supports this attribute. If such a module is found, the attribute is retrieved from that module. An error is raised if there is no module on the stack which supports this attribute.

Arguments:

attributeName String

Return type: the returned Object can be of any type.

`do`

Invoke a module-specific method on the stack. The stack is searched from the top down for a module which supports this method. If such a module is found, the method is invoked on that module. An error is raised if there is no module on the stack which supports this method.

Arguments:

methodName	`String`
`...`	any no. of arguments depending on the particular method

Return type: Object

Contents

Index

Current topic: communications

Related topics: communications classes, objects