Function

Summary

Asynchronously receives a message from a socket.

Package

comm

Signature

async-io-state-receive-message async-io-state buffer callback &key start end timeout error-callback needs-address user-info

Arguments

async-io-state

An async-io-state.

buffer

A cl:base-string or an 8-bit cl:simple-array.

callback

A function designator.

start

A lower bounding index designator for buffer.

end

An upper bounding index designator for buffer.

timeout

nil or a non-negative real.

error-callback

A function designator.

needs-address

A boolean.

user-info

A Lisp object.

Values

None.

Description

The function async-io-state-receive-message starts a read operation of "receiving" on async-io-state, which means that when there is input on the socket it calls recv or recvfrom to read the data into buffer between start and end.

The default value of start is 0. The default value of end is the length of buffer.

callback should be a function of 3 or 5 arguments. If the reading succeeds and needs-address is nil, then callback is called with this signature:

callback async-io-state buffer number-of-bytes-read

If the reading succeeds and needs-address is non-nil, then callback is called with this signature:

callback async-io-state buffer number-of-bytes-read ip-address port-number

where ip-address and port-number are the socket address of the sender, and can be used as the hostspec and service when required. Typically these are used in async-io-state-send-message-to-address to send a message back to the sender.

The default value of needs-address is nil.

error-callback, timeout, start, end and user-info have the same meaning as in async-io-state-read-buffer.

Notes

1. async-io-state-receive-message is typically used only with an async-io-state containing a UDP socket, created by create-async-io-state-and-udp-socket, create-async-io-state-and-connected-udp-socket or calling create-async-io-state with udp non-nil.
2. The socket may or may not be connected.

See also

create-async-io-state-and-udp-socket
create-async-io-state-and-connected-udp-socket
async-io-state-send-message
async-io-state-send-message-to-address
The Async-I/O-State API