This module implements a high-level cross-platform sockets interface. The procedures implemented in this module are primarily for blocking sockets. For asynchronous non-blocking sockets use the asyncnet module together with the asyncdispatch module.

The first thing you will always need to do in order to start using sockets, is to create a new instance of the Socket type using the newSocket procedure.

SSL

In order to use the SSL procedures defined in this module, you will need to compile your application with the -d:ssl flag.

Examples

Connecting to a server

After you create a socket with the newSocket procedure, you can easily connect it to a server running at a known hostname (or IP address) and port. To do so over TCP, use the example below.

var socket = newSocket()
socket.connect("google.com", Port(80))

UDP is a connectionless protocol, so UDP sockets don't have to explicitly call the connect procedure. They can simply start sending data immediately.

var socket = newSocket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)
socket.sendTo("192.168.0.1", Port(27960), "status\n")

Creating a server

After you create a socket with the newSocket procedure, you can create a TCP server by calling the bindAddr and listen procedures.

var socket = newSocket()
socket.bindAddr(Port(1234))
socket.listen()

You can then begin accepting connections using the accept procedure.

var client: Socket
var address = ""
while true:
  socket.acceptAddr(client, address)
  echo("Client connected from: ", address)

Imports

nativesockets, os, strutils, times, sets, options, monotimes, ssl_certs, openssl, winlean

Types

Certificate = string: DER encoded certificate Source Edit
SslError = object of Exception: Source Edit
SslCVerifyMode = enum CVerifyNone, CVerifyPeer, CVerifyPeerUseEnvVars: Source Edit
SslProtVersion = enum protSSLv2, protSSLv3, protTLSv1, protSSLv23: Source Edit
SslContext = ref object context*: SslCtx referencedData: HashSet[int] extraInternal: SslContextExtraInternal: Source Edit
SslAcceptResult = enum AcceptNoClient = 0, AcceptNoHandshake, AcceptSuccess: Source Edit
SslHandshakeType = enum handshakeAsClient, handshakeAsServer: Source Edit
SslClientGetPskFunc = proc (hint: string): tuple[identity: string, psk: string]: Source Edit
SslServerGetPskFunc = proc (identity: string): string: Source Edit
SocketImpl = object fd: SocketHandle isBuffered: bool buffer: array[0 .. BufferSize, char] currPos: int bufLen: int when defineSsl: isSsl: bool sslHandle: SslPtr sslContext: SslContext sslNoHandshake: bool sslHasPeekChar: bool sslPeekChar: char lastError: OSErrorCode ## stores the last error on this socket domain: Domain sockType: SockType protocol: Protocol: socket type Source Edit
Socket = ref SocketImpl: Source Edit
SOBool = enum OptAcceptConn, OptBroadcast, OptDebug, OptDontRoute, OptKeepAlive, OptOOBInline, OptReuseAddr, OptReusePort, OptNoDelay: Boolean socket options. Source Edit
ReadLineResult = enum ReadFullLine, ReadPartialLine, ReadDisconnected, ReadNone: result for readLineAsync Source Edit
TimeoutError = object of Exception: Source Edit
SocketFlag {...}{.pure.} = enum Peek, SafeDisconn ## Ensures disconnection exceptions (ECONNRESET, EPIPE etc) are not thrown.: Source Edit
IpAddressFamily {...}{.pure.} = enum IPv6, ## IPv6 address IPv4 ## IPv4 address: Describes the type of an IP address Source Edit
IpAddress = object case family*: IpAddressFamily ## the type of the IP address (IPv4 or IPv6) of IpAddressFamily.IPv6: address_v6*: array[0 .. 15, uint8] ## Contains the IP address in bytes in ## case of IPv6 of IpAddressFamily.IPv4: address_v4*: array[0 .. 3, uint8] ## Contains the IP address in bytes in ## case of IPv4: stores an arbitrary IP address Source Edit

Consts

BufferSize: int = 4000: size of a buffered socket's buffer Source Edit
MaxLineLength = 1000000: Source Edit

Procs

proc isDisconnectionError(flags: set[SocketFlag]; lastError: OSErrorCode): bool {...}{. raises: [], tags: [].}

Determines whether lastError is a disconnection error. Only does this if flags contains SafeDisconn. Source Edit

proc toOSFlags(socketFlags: set[SocketFlag]): cint {...}{.raises: [], tags: [].}

Converts the flags into the underlying OS representation. Source Edit

proc newSocket(fd: SocketHandle; domain: Domain = AF_INET; sockType: SockType = SOCK_STREAM; protocol: Protocol = IPPROTO_TCP; buffered = true): owned(Socket) {...}{.raises: [], tags: [].}

Creates a new socket as specified by the params. Source Edit

proc newSocket(domain, sockType, protocol: cint; buffered = true): owned(Socket) {...}{. raises: [OSError], tags: [].}

Creates a new socket.

If an error occurs OSError will be raised.