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. See the newContext procedure for additional details.

SSL on Windows

On Windows the SSL library checks for valid certificates. It uses the cacert.pem file for this purpose which was extracted from https://curl.se/ca/cacert.pem. Besides the OpenSSL DLLs (e.g. libssl-1_1-x64.dll, libcrypto-1_1-x64.dll) you also need to ship cacert.pem with your .exe file.

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))

For SSL, use the following example (and make sure to compile with -d:ssl):

var socket = newSocket()
var ctx = newContext()
wrapSocket(ctx, socket)
socket.connect("google.com", Port(443))

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

since, nativesockets, os, strutils, times, sets, options, monotimes, ssl_certs, ssl_config, winlean, openssl, posix, posix

Types

Certificate = string: DER encoded certificate Source Edit
SslError = object of CatchableError: 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 sslNoShutdown: bool 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 CatchableError: 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; inheritable = defined(nimInheritHandles)): owned(Socket) {...}{. raises: [OSError], tags: [].}

Creates a new socket.

The SocketHandle associated with the resulting Socket will not be inheritable by child processes by default. This can be changed via the inheritable parameter.

If an error occurs OSError will be raised.