Main index  |  Module description  |  Classes  |  Enums  |  Functions

ClassUDPSocket

class UDPSocket( addrOrService, [service] ) from \
    Socket

UDP (datagram) manager. more...


Member list

Properties
remote Contains the origin address of the last datagram received with the UDPSocket.recv method.
remoteService Contains the origin port of the last datagram received with the UDPSocket.recv method.
Methods
broadcast Activates broadcasting and multicasting abilities on this UDP socket.
recv Reads incoming data.
sendTo

Detailed description

The UDPSocket class provides support for UDP transmissions (datagrams).

The constructor reserves the needed system resources and return an UDPSocket object that can be used to send and receive datagrams.


Class properties

remote
Contains the origin address of the last datagram received with the UDPSocket.recv method.

remoteService
Contains the origin port of the last datagram received with the UDPSocket.recv method.


Class methods

broadcast()

Activates broadcasting and multicasting abilities on this UDP socket.

UDPSocket.broadcast( )
Raises:
NetError

on system error.

This is provided as a method separated from the socket constructor as, on some systems, this call requires administrator privileges to be successful.

recv()

Reads incoming data.

UDPSocket.recv( bufOrSize, [size] )
bufOrSize

A pre-allocated buffer to fill, or a maximum size in bytes to be read.

size

Maximum size in bytes to be read.

Returns:

If bufOrSize is a size, returns a filled string buffer, otherwise it returns the amount of bytes actually read.

Raises:
NetError

on network error.

This method works as the TCPSocket.recv method, with the only difference that the incoming datagram is always completely read, provided that the specified size is enough to store the data.

Also, the (undefined) Expected a link class but found a string: UDPSocket and (undefined) Expected a link class but found a string: UDPSocket properties of the receiving object are filled with the address and port of the host sending the packet.

When the bufOrSize parameter is a buffer to be filled (i.e. a MemBuf or a string created with strBuffer), the buffer may be repeatedly used, sparing memory and allocation time. If the size parameter is not provided, the maximum amount of bytes that can be stored in the buffer will be used as read size limit,

This size won't change between call, even if the actual length of the data stored in the buffer changes.

If the size parameter is provided, it is used to define the maximum possible size of data stored in the buffer. If it is not great enough to store the data, it is resized.

When a target buffer is specified in the bufOrSize parameter, the method returns number of bytes that has been actually read. The size may be zero if the opposite side closed the connection, or if the timeout has elapsed. The returned size will presumably be smaller than the maximum, and it will be at maximum the size of a TCP packet that can travel on the current connection.

When a maximum size is specified in the bufOrSize parameter, the method returns a newly allocated buffer on success, and nil on failure.

In case of system error, a NetError is raised.

See also Socket.setTimeout.

sendTo()

UDPSocket.sendTo( host, service, buffer, [size], [start] )
host

Remote host where to send the datagram.

service

Remote service or port number where to send the datagram.

buffer

The buffer to be sent.

size

Amount of bytes from the buffer to be sent.

start

Begin position in the buffer.

Raises:
NetError

on network error.

This method works as the TCPSocket.send method, with the main difference that the outgoing datagram can be directed towards a specified host, and that a whole datagram is always completely filled before being sent, provided that the specified size does not exceed datagram size limits.

The (undefined) host parameter may be an host name to be resolved or an address; if the UDPSocket.broadcast method has been successfully called, it may be also a multicast or broadcast address.

The (undefined) service parameter is a string containing either a service name (i.e. "http") or a numeric port number (i.e. "80", as a string).

The buffer may be a byte-only string or a byte-wide MemBuf; it is possible to send also multibyte strings (i.e. strings containing international characters) or multi-byte memory buffers, but in that case the sent data may get corrupted as a transmission may deliver only part of a character or of a number stored in a memory buffer.

If a size parameter is not specified, the method will try to send the whole content of the buffer, otherwise it will send at maximum size bytes. If a start parameter is specified, then the data sent will be taken starting from that position in the buffer (counting in bytes from the start).

This is useful when sending big buffers in several steps, so that it is not necessary to create substrings for each send, sparing both CPU and memory.

The returned value may be 0 in case of timeout, otherwise it will be a number between 1 and the requested size. Programs should never assume that a succesful sendTo has sent all the data.

In case of error, a NetError is raised.

See also Socket.setTimeout.


Main index  |  Module description  |  Classes  |  Enums  |  Functions
Made with Faldoc 1.0.0