win.comm - WIN

Class comm
Inherits from __classBase.

The comm class provides a mechanism for a managed two way connection through a modem device. The mechanism implements a structured message table and discriminant routing of messages.

Applications utilize the connection by registering an interest through a window object, specifying an application filter identifier. Messages sent with the same filter are routed to the window's on_receive and on_sent handlers.

Properties

comm__name string The name of the connection.
comm__timeout number Count of os.clock () an operation will wait/attempt until a failure is accepted.
comm__interests table Registered interests in the connection.
comm__processing table List of messages currently being processed.

Methods

See also API Reference, WIN.

win.comm:call_receive_handlers

result comm:call_receive_handlers (msg)

Sends a comm_receive event to any windows registered for the event.

Parameters
msg msg The message being received.

Returns
result boolean True if at least one handler received the message, false if not.

Remarks
See window:on_receive.


top


win.comm:call_sent_handlers

comm:call_sent_handlers (msg, result)

Sends a comm_sent event to any windows registered for the event.

Parameters
msg msg The message structure.
success boolean True if the send operation succeeded, false if failed (no confirmation for an addressed message was received before the timeout count was reached).

Returns
none


Remarks
See also  window:on_sent


top


win.comm:constructor

com comm:constructor (name, timeout)

Constructs and returns the instantiated comm object.

Parameters
name string The name of the connection.
timeout number Count of os.clock() an operation will wait/attempt until a failure is accepted. If nil the default is 5.

Returns
com comm The instantiated comm object.

Remarks


top


win.comm:copy_msg

copy comm:copy_msg (msg)

Copies a msg structure table.

Parameters
msg msg The msg message structure to copy.

Returns
copy msg The copied structure.

Remarks
This method may be used as a static member of the class.


top


win.comm:get_name

name comm:get_name ()

Returns the name of the connection.

Parameters
none


Returns
name string The name of the connection.

Remarks
See comm:set_name.


top


win.comm:get_timeout

timeout comm:get_timeout ()

Returns the time out value for the connection.

Parameters
none


Returns
timeout number Count of os.clock() an operation will wait/attempt until a failure is accepted.

Remarks
See comm:set_timeout.


top


win.comm:is_confirmation

result comm:is_confirmation (msg)

Tests if the message is a confirmation of a sent message. Appropriate sent handlers are called if necessary.

Parameters
msg msg The message to test.

Returns
result boolean True if the message is a confirmation, false if not.

Remarks


top


win.comm:is_duplicate

result comm:is_duplicate (msg)

Checks if the message has already been processed.

Parameters
msg msg The message to test.

Returns
result boolean True if the message has already been processed, false if not.

Remarks


top


win.comm:is_for_me

result comm:is_for_me (msg, exclusive)

Tests a message to determine if it is addressed to this computer or is broadcasted, or not.

Parameters
msg msg The message to test.
exclusive boolean If true the message must be addressed to this computer, otherwise it will be accepted if broadcasted.

Returns
result boolean True if the message is addressed to this computer or is broadcasted (if exclusive is false), false if not.

Remarks


top


win.comm:is_from_me

result comm:is_from_me (msg)

Tests if a message was sent by this computer.

Parameters
msg msg The message to test.

Returns
result boolean True if the message was sent by this computer, false if not.

Remarks


top


win.comm:is_processing

result comm:is_processing ()

Returns true if the comm object has any messages to process, otherwise false.

Parameters
none



Returns
result
boolean
True if any messages to process, false if not.

Remarks


top


win.comm:process

comm:process ()

Processes the message queue. This method should be called at frequent, regular intervals to ensure timely actioning of the messages.

Parameters
none


Returns
none


Remarks


top


win.comm:receive

comm:receive (message, sender_id, target_id)

Processes received messages. This method is called directly from a wireless event with its parameters. Not all parameter values are used/respected by the comm connection.

Parameters
message string The raw message.
sender_id number The number id of the computer that sent the message.
target_id number The number id of the target computer (this computer). This will be nil if the message was broadcast.

Returns
none


Remarks


top


win.comm:register

comm:register (wnd, application)

Registers an interest in the comm connection to receive messages and sent notifications.

Parameters
wnd window The window interested in the connection.
application string Identifier for filtering which messages should be passed to the sent notification and receive handlers.

Returns
none


Remarks
When the interest in the connection is no longer required it must be unregistered with comm:unregister.

See window:on_receive, window:on_sent.


top


win.comm:send

message_id comm:send (recipient, application, context, data)

Send a message across the comm connection.

Parameters
recipient string/number/nil The intended recipient computer's name or id number. If nil the message is broadcasted to all computers.
application string Identifier for message filtering. This should match the sender's and recipient's registered application filter.
context string Message specific context. This states the purpose/structure of the data.
data table/string/number The data for the message, if any.

Returns
message_id number Unique identifier for the message, or nil if the send was not successful (the message was addressed to the sending computer). This can be used to identify the message in the sent handler.

Remarks
While a message may be sent without registering an interest in the connection, sent notifications cannot be implemented without it.

Messages are not sent directly through this call, but are queued to be sent by the mechanism. They are sent by comm:process.


top


win.comm:send_confirmation

comm:send_confirmation (msg)

Sends a confirmation message for the given message if it was not broadcasted.

Parameters
msg msg The message to confirm.

Returns
none


Remarks


top


win.comm:set_name

comm:set_name (name)

Sets the name for the connection.

Parameters
name string The name for the connection.

Returns
none


Remarks
See comm:get_name.


top


win.comm:set_timeout

comm:set_timeout (timeout)

Sets the time out value for the connection.

Parameters
timeout number Count of os.clock () an operation will wait/attempt until a failure is accepted. If nil the default is 5.

Returns
none


Remarks
See also  comm:get_timeout.


top


win.comm:transmit

result comm:transmit (msg)

Transmit the message through the comm connection.

Parameters
msg
msg
The message to transmit.

Returns
result boolean True if the message transmitted, false if not.

Remarks


top


win.comm:unregister

comm:unregister (wnd, application)

Unregisters an interest in the comm connection registered with comm:register.

Parameters
wnd window The window interested in the connection.
application string/nil The message filtering identifier the interest was registered with.

Returns
none


Remarks
The parameters passed to comm:unregister should match those passed to comm:register to register the interest. If only the wnd parameter is given all interests for that window on this connection are unregistered.


top


msg

Table msg

The msg table structure forms a message used through a comm connection.

Properties

sender_id number The identifier of the sending computer.
sender_name string The name of the sending computer.
recipient_id number The identifier of the intended recipient computer. It may be nil.
recipient_name string The name of the intended recipient computer. It may be nil.
application string Application filter identifier. Only registered interests in the connection with a matching application field of the sent message will receive the message.
context string Application specific indicator of the purpose/structure of the message/data.
data any Application specific data. If a table only simple data types can be used.
message_id number A random number dedicated by the comm mechanism to uniquely this message.
sequence number An incremented sequence of send attempts for the message.

Generally either the recipient_id or recipient_name are set to indicate the intended recipient of the message. If both are nil the message is a broadcasted message. The handler of every computer whose application field matches the message is called.


top


See also API Reference, WIN.