create-async-io-state-and-udp-socket Function

Summary

Creates an async-io-state where object is an unconnected UDP socket.

Package

comm

Signature

create-async-io-state-and-udp-socket collection &key name errorp ipv6 queue-output read-timeout write-timeout user-info local-address local-port => async-io-state

Arguments

Values

Description

The function create-async-io-state-and-udp-socket creates an async-io-state where object is an unconnected UDP socket.

async-io-state is associated with collection.

create-async-io-state-and-udp-socket creates a new UDP socket, optionally binds it if local-port or local-address is non-nil, and then creates and returns an async-io-state object that can be used to perform I/O operations on the socket. The I/O operations are performed using async-io-state-receive-message and async-io-state-send-message-to-address. local-address and local-port specify the local socket address as described in 25.3 Specifying the target for connecting and binding a socket. Both values can be nil.

queue-output controls what happens if you try to perform a write operation on the state while another write operation is ongoing. When nil, this will cause an error. When non-nil, the second write operation is queued and actually executed later. The default value of queue-output is t.

When ipv6 is :any, the system selects whether to use an IPv4 or IPv6 socket (normally it will be IPv4). When ipv6 is t it forces using IPv6, and nil forces IPv4. The value :both means using IPv6, but also allow receiving messages in IPv4. The default value of ipv6 is :any.

When errorp is nil, create-async-io-state-and-udp-socket returns nil for run time errors rather than signaling an error. The default value of errorp is t.

read-timeout, write-timeout, user-info and name are set the new async-io-state using the corresponding accessors async-io-state-read-timeout, async-io-state-write-timeout, async-io-state-user-info and async-io-state-name.

The default value of name is a string "UDP".

Notes

1. If the socket is used to receive messages from unknown senders (that is as a server), then you need to bind the socket by supplying local-port. If the socket is only used to send messages then you do not need to bind it, because the recipient of the messages can find the socket's address if it needs to send a reply. You can supply local-address to restrict which connections are allowed.
2. You can find the source address of a message that is received using the result of create-async-io-state-and-udp-socket by supplying needs-address t to async-io-state-receive-message.
3. If you need to connect the socket, use create-async-io-state-and-connected-udp-socket instead.
4. The call to create-async-io-state-and-udp-socket itself is synchronous.
5. You cannot use async-io-state-send-message (without address) with the result of create-async-io-state-and-udp-socket (because the socket address to send to must be specified).

Examples

(example-edit-file "async-io/udp")

See also

async-io-state-receive-message
async-io-state-send-message-to-address
create-async-io-state-and-connected-udp-socket
25.7.2 The Async-I/O-State API
25 TCP and UDP socket communication and SSL