The functions in this class include wrappers to several Windows™ functions; they are available only in the Proteus interpreter specific to this platform. The predefined public identifier OS is 2 it the interpreter running the script is the Windows™ version; moreover, the directive WINDOWS is predefined (it is possible to conditionally execute code between !ifdef WINDOWS.. and !endif).
Many functions presented here require constant parameters, whose values can be found in the include files win32.prt and socket.prt, which should be included every time one of the following functions is used.
 
The functions are divided in the following categories:

• registry management
• Windows™ error management
• window management
• file functions
• serial port functions
• pipe functions
• socket functions
• other function

Registry management

W32READREGVALUE(nRoot, cPath, @value)

reads the key corresponding to cPath, in the branch nRoot, and saves its value. This function returns -1 on error, the key type otherwise.

Possible values for nRoot:

• W32_HKEY_CLASSES_ROOT
• W32_HKEY_CURRENT_USER
• W32_HKEY_LOCAL_MACHINE
• W32_HKEY_USERS 
• W32_HKEY_PERFORMANCE_DATA
• W32_HKEY_CURRENT_CONFIG

Possible values returned:

• W32_REG_SZ 
• W32_REG_EXPAND_SZ 
• W32_REG_BINARY 
• W32_REG_DWORD 
• W32_REG_DWORD_BIG_ENDIAN 
• W32_REG_LINK 
• W32_REG_MULTI_SZ 
• W32_REG_RESOURCE_LIST 
• W32_REG_FULL_RESOURCE_DESCRIPTOR
• W32_REG_RESOURCE_REQUIREMENTS_LIST

(see win32.prt for additional information)

W32WRITEREGVALUE(nRoot, cPath, nType, value)

writes value to cPath inside the branch nRoot. This function returns -1 on error, 0 otherwise. See W32READREGVALUE for the possible values of nType and nRoot.

W32DELREGVALUE(nRoot, cPath)

deletes the value specified using cPath and nRoot. This function returns -1 on error, 0 otherwise.

W32DELREGKEY(nRoot, cPath)

deletes the key specified using cPath and nRoot (including all the values contained). This function returns -1 on error, 0 otherwise.

Windows™ error management

W32GETLASTERROR()

returns the error code for the last error which happened

W32FORMATERROR(nErrNumber)

returns the description corresponding to the error nErrNumber

Window management

W32GETFOCUS()

returns the handle of the window having focus, 0 if no window has focus

W32SETFOCUS(wHandle)

brings to foreground and sets the focus to the specified window. This function returns 0 on error, non-zero otherwise.

W32FINDWINDOW(cTitle)

finds the first window corresponding to cTitle, that can be specified using a simple regular expression (including * and ?). The comparison is case-unsensitive.

W32GETWINDOW(wHandle, nRelation)

returns the handle of a window that is in the required relationship with the specified window, 0 on error. The possible values for nRelation are the following (see win32.prt):

Value	Meaning
GW_CHILD	returns a handle that identifies the child window in the Z-order, if the specified window is a father; returns a null value otherwise. This function examines only the children of the specified window, not its descendants.
GW_ENABLEDPOPUP	only for Windows™ NT 5.0 and later; returns a handle that identifies the enabled popup window, owned by the specified window (the search begins from the first window returned by a call using GW_HWNDNEXT); if the search fails, returns wHandle
GW_HWNDFIRST	returns the handle for the window of the same type at the top of the Z order.
GW_HWNDLAST	returns the handle for the window of the same type at the bottom of the Z order.
GW_HWNDNEXT	returns the handle for the window underlying the one specified in the Z order.
GW_HWNDPREV	returns the handle for the window coming before the one specified in the Z order.
GW_OWNER	returns the handle for the window owning the one specified (if it exists).

 W32GETWINTITLE(wHandle)

returns the title of the specified window, an empty string on error.

File functions

W32CREATEFILE(cPathName, nAccess, nSharing, nCreation, nAttribute[, wTemplate])

creates a file, pipe, mailslot etc. using the specified parameters; return its handle or 0 (error). The meaning of the parameters is specified in the following table (see win32.prt): 

Parameter	Description
cPathName	file name to create/open
nAccess	access mode (read/write): 0 = only access request W32_GENERIC_READ = read only W32_GENERIC_WRITE = write only
nSharing	sharing: 0 = no sharing W32_FILE_SHARE_READ = allow read access to others W32_FILE_SHARE_WRITE = allow write access to others W32_FILE_SHARE_DELETE = allow delete access to others
nCreation	creation dispositions: W32_CREATE_NEW = create a new file; fail if the file exists W32_CREATE_ALWAYS = create a new file; if it exists, it is overwritten and its attributes are reset W32_OPEN_EXISTING = open the file; fail if it does not exist W32_OPEN_ALWAYS = open the file; if it does not exist, it is created W32_TRUNCATE_EXISTING = open the file and truncate it to 0 length (write rights are required); fail if the file does not exist
nAttribute	attributes: W32_FILE_ATTRIBUTE_READONLY =  read only file W32_FILE_ATTRIBUTE_HIDDEN =  hidden file W32_FILE_ATTRIBUTE_SYSTEM =  system file W32_FILE_ATTRIBUTE_ARCHIVE =  file to be archived W32_FILE_ATTRIBUTE_NORMAL =  normal file (use it alone) W32_FILE_ATTRIBUTE_TEMPORARY =  temporary file; the file system tries to keep it in memory; the user must delete it as soon as it is no longer necessary W32_FILE_ATTRIBUTE_OFFLINE =  file not immediately available (moved offline) W32_FILE_FLAG_WRITE_THROUGH =  write modifications to disk as soon as possible W32_FILE_FLAG_RANDOM_ACCESS =  random access file (to be used to optimize caching)  W32_FILE_FLAG_SEQUENTIAL_SCAN =  random access from start to end (to be used to optimize caching); file pointer repositioning is allowed W32_FILE_FLAG_DELETE_ON_CLOSE =  delete the file as soon as all the processes are finished using it When opening a named pipe: W32_SECURITY_SQOS_PRESENT =  the information about Quality of Service are available W32_SECURITY_ANONYMOUS = anonymous W32_SECURITY_IDENTIFICATION =  identification W32_SECURITY_IMPERSONATION =  impersonation W32_SECURITY_DELEGATION =  delegation W32_SECURITY_CONTEXT_TRACKING =  dynamic security context tracking W32_SECURITY_EFFECTIVE_ONLY = only enabled user security context aspects are available to the server
wTemplate	optional handle of a file having W32_GENERIC_READ access, from which attributes are copied when creating the new file

W32CLOSEHANDLE(wHandle)

closes the handle; returns 0 on error (see W32GETLASTERROR), a value different from 0 on success

W32WRITEFILE(wHandle, cText)

writes cText to wHandle; returns the number of bytes written (that can be different from the length of cText, e.g. if the file is a pipe with full buffer), -1 on error. If cText is empty, updates only file date/time.

W32READFILE(wHandle, @cText)

reads STRLEN(cText) characters from wHandle; if there are not enough available bytes, cText is truncated. This function returns the number of bytes read, or -1 on error.

Serial port functions

W32READCOM(wHandle, nNumBytes)

reads nNumBytes characters from the port wHandle; if nNumBytes = 0, reads all the bytes available in the buffer. This function returns a string containing the bytes read, an empty string on error. The string returned can be shorter than the number of requested bytes.

W32GETCOMSTATE(wHandle, vDCB)

reads the status of the opened serial port; returns 0 on success, -1 on error.
vDCB must be the handle of an array with at least 13 items; the values are explained below (see win32.prt):

Constant	Value	Description
W32_COM_GS_DCBLENGTH	1	DCB length (ignore)
W32_COM_GS_BAUD	2	baud rate: 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000
W32_COM_GS_FLAGS	3	flags; numeric OR of the following values: W32_COM_BINARY = binary transmission, ignore EOF character W32_COM_PARITY_ON = enable parity control W32_COM_CTSFLOW_ON = enable hardware flowcontrol (CTS/RTS) W32_COM_DSRFLOW_ON = enable alternate hardware flowcontrol (DSR/DTR) W32_COM_DTR_ENABLE = raise DTR line when device is opened and keep it raised W32_COM_DTR_HANDSHAKE = enable DTR handshake W32_COM_DSR_SENSITIVITY = specify that the driver is sensible to DSR state; if set, the driver ignores any character received when the line is not raised W32_COM_XOFF_CONTINUE =  XOFF continues transmission W32_COM_XONXOFF_OUT = XON/XOFF handshake when transmitting W32_COM_XONXOFF_IN =  XON/XOFF handshake when receiving W32_COM_USE_ERRORCH =  use error character if parity is wrong W32_COM_STRIP_NULL =  remove NULL characters (chr(0)) from stream W32_COM_RTS_ENABLE =  raise RTS when the device is opened and keep it raised W32_COM_RTS_HANDSHAKE =  enable handshake: the driver raises RTS signal when input buffer is half full (or less) and drops it when it is 75% full. W32_COM_RTS_TOGGLE =  raise RTS if there are bytes to be transmitted, drops it otherwise W32_COM_ERROR_ABORT =  terminate read/write operation in case of error; no other communications will be accepted until W32ClearComErr is called
-	4	reserved
W32_COM_GS_TXON	5	threshold for XON transmission
W32_COM_GS_TXOFF	6	threshold for XOFF transmission
W32_COM_GS_BIT	7	data bits, from 4 to 8 (7 or 8, usually)
W32_COM_GS_PARITY	8	parity: W32_COM_PARITY_NONE W32_COM_PARITY_ODD  W32_COM_PARITY_EVEN  W32_COM_PARITY_MARK  W32_COM_PARITY_SPACE
W32_COM_GS_STOP	9	stop bits: W32_COM_STOP_1  W32_COM_STOP_15  W32_COM_STOP_2
W32_COM_GS_XONCHAR	10	XON character (ASCII value)
W32_COM_GS_XOFFCHAR	11	XOFF character (ASCII value)
W32_COM_GS_ERRCHAR	12	error character (ASCII value)
W32_COM_GS_EOFCHAR	13	EOF character (end of input, ASCII value)
W32_COM_GS_RXCHAR	[14]	[character for receive event (ASCII value), optional]

W32SETCOMSTATE(wHandle, vDCB)

sets port status. See W32GETCOMSTATE for the values to be assigned to items in vDCB. This function returns 0 on success, -1 on error.

W32SETCOMTIMEOUTS(wHandle, vTimeOut)

sets read and write timeouts for the serial port; vTimeOut must be an array with at least 5 items; the values are explained below (see win32.prt):

Constant	Value	Description
W32_COM_TO_READ	1	read timeout interval (milliseconds)
W32_COM_TO_READMUL	2	multiplier for read timeout (milliseconds)
W32_COM_TO_READCONST	3	constant for read timeout (milliseconds) total read timeout = (number of characters to read) * multiplier + constant   If multiplier and constant are 0, there is no read timeout
W32_COM_TO_WRITEMUL	4	multiplier for write timeout (milliseconds)
W32_COM_TO_WRITECONST	5	constant for write timeout (milliseconds) total write timeout = (number of characters to write) * multiplier + constant   If multiplier and constant are 0, there is no write timeout

W32PURGECOM(wHandle, nFlags)

purges receive or transmit buffer, according to nFlags; this function returns 0 on success, -1 on error.

Values admitted for nFlags:

• W32_PURGE_TXCLEAR =  purges transmission buffer
• W32_PURGE_RXCLEAR =  purges receive buffer

W32ESCCOMFUNC(wHandle, nFunction)

runs the specified function on the device identified by wHandle; this function returns 0 on success, -1 on error. The possible values for nFunction are explained below (see win32.prt):

Function	Description
W32_COM_SETXOFF	simulates XOFF reception
W32_COM_SETXON	simulates XON reception
W32_COM_SETRTS	raise RTS signal (request-to-send)
W32_COM_CLRRTS	drop RTS signal (request-to-send)
W32_COM_SETDTR	raise DTR signal (data-terminal-ready)
W32_COM_CLRDTR	drop DTR signal (data-terminal-ready)
W32_COM_RESETDEV	reset device, if possible
W32_COM_SETBREAK	suspend transmission and put line in break mode until function EscComFunc is called with parameter W32_COM_CLRBREAK. Please note that this extended function does not clear data that were not transmitted.
W32_COM_CLRBREAK	restore transmission and put line in out-of-break mode.

W32CLEARCOMERR(wHandle, @nErrMask, vST)

returns in nErrMask the mask with the specified error types and in vST (array with at least three items) the following information (see win32.prt):

Constant	Value	Description
W32_CE_STATUS	1	status; numeric OR of the following values: W32_CE_RXOVER =  overflow in input buffer. No room in input buffer or a character was received after EOF W32_CE_OVERRUN =  buffer overrun; next character will be lost W32_CE_RXPARITY = hardware detected a parity error W32_CE_FRAME =  hardware detected a framing error W32_CE_BREAK =  hardware detected a break condition W32_CE_TXFULL =  the application tried to transmit a character, but output buffer was full W32_CE_PTO = Windows 95™ e Windows 98™: time-out on parallel device W32_CE_IOE = an I/O error happened during communication W32_CE_DNS = Windows 95™ and Windows 98™: parallel device not selected W32_CE_OOP = Windows 95™ and Windows 98™: parallel device is out of paper W32_CE_MODE = requested mode is unsupported, or the specified handle is wrong; if this flag is set, it is the only valid error
W32_CE_RXBYTES	2	bytes in rx buffer
W32_CE_TXBYTES	3	bytes in tx buffer

This function returns 0 on success, -1 on error.

W32WAITCOMMEVT(wHandle, @nMask)

waits for one of the events specified in nMask; returns -1 on error, 0 if one of the events happened (nMask, passed by reference, is updated accordingly); nMask is the sum of one or more of the following values (see win32.prt):

Value	Description
EV_RXCHAR	received a character
EV_RXFLAG	received the specified character
EV_TXEMPTY	transmission queue is empty
EV_CTS	CTS status changed
EV_DSR	DSR status changed
EV_RLSD	RLSD status changed
EV_BREAK	BREAK received
EV_ERR	error detected on the line
EV_RING	ring detected
EV_PERR	printer error
EV_RX80FULL	receive buffer is full at 80%
EV_EVENT1	provider specific event #1
EV_EVENT2	provider specific event #2

W32SETCOMBREAK(wHandle)

suspends transmission on the serial line and puts the line on BREAK until W32CLEARCOMBREAK is called; this function returns -1 on error, 0 on success

W32CLEARCOMBREAK(wHandle)

restores transmission and puts the serial line in non-break state; this function returns -1 on error, 0 on success

W32GETMODEMSTATUS(wHandle, @nStatus)

returns the status of the control register for the connected modem; useful to determine what event triggered W32WAITCOMMEVT; nStatus is updated by reference with a combination of one or more of the following values (see win32.prt):

Value	Description
MS_CTS_ON	CTS signal is on
MS_DSR_ON	DSR signal is on
MS_RING_ON	RING signal is on
MS_RLSD_ON	RLSD signal is on

This function returns -1 on error, 0 on success.

W32WAITRXCHAR(wHandle, nTimeout[, nPolltime])

waits for a character to arrive at the serial port for nTimeout milliseconds; returns 0 if the timeout expired (or an error happened), the number of bytes in the buffer otherwise. If nTimeout is not zero, nPolltime is used to determine after how many milliseconds the port should be verified (default = 55, if not specified). If nTimeout is zero, waits forever.

W32WAITTXOVER(wHandle, nTimeout[, nPolltime])

waits for the output buffer to become empty for nTimeout milliseconds; returns 0 if empty, otherwise the number of bytes in the buffer (timeout expired). If nTimeout is not zero, nPolltime is used to determinare after how many milliseconds the port should be verified (default = 55, if not specified). If nTimeout is zero, waits forever.

Pipe functions

PIPECALL(cPipeName, cWriteText, @cReadText, nTimeOut)

writes cWriteText and reads into cReadText (pre-allocated buffer of the required size); waits for the pipe to become available for nTimeOut milliseconds. This function returns 0 on success, the error code otherwise. If  nTimeOut is zero, waits forever.

PIPECREATE(cPipeName, nOpenMode, nPipeMode, nInstances, nOutBufSize, nInBufSize, nTimeOut)

creates a pipe using the specified attributes; returns the handle to the pipe, or -1 on error. The meaning of the parameters is explained below (see win32.prt):

• cPipeName = pipe name; must have the form "\\\\.\\pipe\\name"  (double "\" is needed, because it is used as an escape character)
• nOpenMode = access mode, write-through mode and security. The value is the numeric OR of any combination of the following values (the same mode must be used for any instance of the pipe):

Constant	Description
PIPE_ACCESS_DUPLEX	bidirectional pipe; server and client can read and write. Same as using NOR(GENERIC_READ, GENERIC_WRITE) on the server side. The client can specify GENERIC_READ, GENERIC_WRITE or both, when the pipe is connected with W32CREATEFILE.
PIPE_ACCESS_INBOUND	server reads, client writes; server has GENERIC_READ access; the client must specify GENERIC_WRITE when the pipe is connected
PIPE_ACCESS_OUTBOUND	server writes, client reads; the server has GENERIC_WRITE access; the client must specify GENERIC_READ when the pipe is connected

Additional flags (can appear or not in different instances of the same pipe):

Constant	Description
W32_FILE_FLAG_WRITE_THROUGH	enable "write-through" mode; this flag influences write operations on byte-type pipes when client and server are on different computers. When enabled, write operations do not return until data are transmitted on the network and are in the input buffer of the remote pipe. If this mode is not specified, the system increases network efficiency by using buffering.

• nPipeMode = pipe type, reading mode, wait mode. The value is the numeric OR of any combination of the following values (the same mode must be used for any instance of the pipe):

Constant	Description
PIPE_TYPE_BYTE	data are written as a sequence of bytes (default, if nPipeMode = 0); this mode can not be used together with PIPE_READMODE_MESSAGE
PIPE_TYPE_MESSAGE	data are written as a series of messages. This mode can not be used together with PIPE_READMODE_MESSAGE or PIPE_READMODE_BYTE

Additional flags (can appear or not in different instances of the same pipe):

Constant	Description
PIPE_READMODE_BYTE	data are read from the pipe as a sequence of bytes (default, if nPipeMode = 0); this mode can not be used together with PIPE_TYPE_MESSAGE or PIPE_TYPE_BYTE
PIPE_READMODE_MESSAGE	data are read from the pipe as a series of messages. This mode can only be used together with PIPE_TYPE_MESSAGE.
PIPE_WAIT	enable wait mode (default, if nPipeMode = 0); when the pipe handle is used in W32READFILE or W32WRITEFILE, the function does not return until data are available or are completely written (respectively).
PIPE_NOWAIT	disable wait mode; in this mode, W32READFILE or W32WRITEFILE always return immediately.

• nInstances = maximum number of instances that can be created for the pipe; acceptable values go from 1 to PIPE_UNLIMITED_INSTANCES (instances limited only by system resources)
• nOutBufSize = number of bytes to be reserved for output buffer
• nInBufSize = number of bytes to be reserver for input buffer
• nTimeOut = default timeout, in milliseconds, for PIPEWAIT (when the function is invoked with NMPWAIT_USE_DEFAULT_WAIT)

PIPEWAITCONN(wHandle)

waits for the connection of a client on the pipe wHandle; returns 0 on success, the error code otherwise.

PIPEDISCONNECT(wHandle)

disconnects a client from the pipe wHandle; returns 0 on success, the error code otherwise.

PIPEPEEK(wHandle, @cBuffer, @nBytesLeft, @nBytesLeftMessage)

reads frome the pipe wHandle into cBuffer (which must have length equal to the number of bytes to be read) and stores into nBytesLeft the number of bytes remaining (and into nBytesLeftMessage the number of bytes left for the message, if the pipe type is message); cBuffer is resized to the number of bytes effectively read. This function returns 0 on success, the error code otherwise.

PIPETRANSACT(wHandle, cWriteText, @cReadText)

writes the string cWriteText on the pipe wHandle and reads into cReadText maximum STRLEN(cReadText) bytes; cReadText is resized to the number of bytes effectively read. This function returns 0 on success, the error code otherwise. Always check W32GETLASTERROR() after the call, to make sure there are no more bytes to be read (ERROR_MORE_DATA).

PIPEWAIT(cPipeName, nTimeOut)

waits for nTimeOut milliseconds for the pipe cPipeName to become available; returns 0 if available, -1 otherwise. The meaning of the parameters is the following:

• cPipeName = pipe name; must have the form "\\\\.\\pipe\\name"  (double "\" is needed, because it is used as an escape character)
• nTimeOut = timeout in milliseconds; use NMPWAIT_USE_DEFAULT_WAIT to use the default value for the named pipe on the server, or NMPWAIT_WAIT_FOREVER to disable timeout.

Socket functions

W32SOCKET(nFamily, nType, nProtocol)

creates a socket with the specified features. This function returns the handle to the socket, -1 on error.
The values for nFamily, nType and nProtocol are (see socket.prt):

• nFamily: AF_UNIX, AF_INET, AF_IMPLINK, AF_PUP, AF_CHAOS, AF_IPX, AF_NS, AF_ISO, AF_OSI, AF_ECMA, AF_DATAKIT, AF_CCITT, AF_SNA, AF_DECnet, AF_DLI, AF_LAT, AF_HYLINK, AF_APPLETALK, AF_NETBIOS, AF_VOICEVIEW, AF_FIREFOX, AF_UNKNOWN1, AF_BAN
• nType: SOCK_STREAM, SOCK_DGRAM
• nProtocol: IPPROTO_IP, IPPROTO_ICMP, IPPROTO_IGMP, IPPROTO_GGP, IPPROTO_TCP, IPPROTO_PUP, IPPROTO_UDP, IPPROTO_IDP, IPPROTO_ND, IPPROTO_RAW, IPPROTO_MAX

W32BIND(oHandle, nFamily, nPort, cAddress)

ties to the socket oHandle the address, the port and the family specified. This function returns 0 on success, another value otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32LISTEN(oHandle, nLength)

sets the length for the connection queue to the socket oHandle. This function returns 0 on success, another value otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32LASTSOCKETERR()

returns the last error that happened on a socket operation; can be used to determine why the last call on the socket failed.

W32SETLASTSOCKETERR()

sets the value returned by W32LASTSOCKETERR (can be used to reset the value after a failed call). Does not return any value.

W32CLOSESOCKET(oHandle)

closes the specified socket. This function returns 0 on success, another value otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32ACCEPT(oHandle, @nFamily, @nPort, @cAddress)

accepts a connection, returns the address of the caller and a new socket handle on which the communication can continue (this socket must be later closed); nFamily, nPort, cAddress are passed by implicit reference and updated on return. This function returns -1 on error, the handle to a new socket otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32GETPEERNAME(oHandle, @nFamily, @nPort, @cAddress)

returns cAddress, nPort, nFamily  for the client connected to the socket. This function returns -1 on error, 0 otherwise.
Use W32LASTSOCKETERR to know the error that happened.

W32GETSOCKNAME(oHandle, @nFamily, @nPort, @cAddress)

returns cAddress, nPort, nFamily for the connected host (W32CONNECT was called, without invoking W32BIND first). This function returns -1 on error, 0 otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32CONNECT(oHandle, nFamily, nPort, cAddress)

tries to connect to a remote socket, specified by nFamily, nPort and cAddress. This function returns -1 on error, 0 otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32IOCTLSOCKET(oHandle, nCommand, @nParameter)

executes a command on the socket oHandle. The possible values for nCommand are (see socket.prt):

Value	Description
FIONBIO	nParameter = 0 disable blocking mode; nParameter = 1 enable blocking mode
FIONREAD	store into nParameter the number of bytes that can be read from the socket
SIOCATMARK	store into nParameter the value 0 if there are out-of-band data to be read, a different value otherwise

This function returns -1 on error, 0 otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32SEND(oHandle, cText, nFlag)

sends data to the socket oHandle; nFlag is the numeric OR of one or more of the following values (default = 0, see socket.prt):

• MSG_OOB = send data as out-of-band
• MSG_DONTROUTE = don't route data

This function returns -1 on error, the number of bytes sent otherwise. Use W32LASTSOCKETERR to know the error that happened.

W32RECV(oHandle, @cText, nFlag)

receives data from the socket oHandle; nFlag is the numeric OR of one or more of the following values (default = 0, see socket.prt):

• MSG_PEEK = do not remove data read
• MSG_OOB = receive out-of-band data

This function returns -1 on error, the number of bytes received otherwise (stored in cText); cText deve essere pre-allocato con lunghezza sufficiente a contenere i dati ricevuti.

W32SHUTDOWN(oHandle, nHow)

disables receive or send operations on the socket oHandle; nHow can be one of the following values (see socket.prt):

• SD_RECEIVE = disable calls to W32RECV on the socket
• SD_SEND = disable calls to W32SEND on the socket
• SD_BOTH = disable both send and receive operations on the socket

This function returns -1 on error, 0 otherwise.

W32SENDTO(oHandle, cText, nFlag, nFamily, nPort, cAddress)

function similar to W32SEND, to be used when W32BIND was not invoked; allows to specify the host address; nFlag is the numeric OR of one or more of the following values (default = 0, see socket.prt):

• MSG_OOB = send data as out-of-band
• MSG_DONTROUTE = do not route data

This function returns -1 on error, the number of bytes sent otherwise.

W32RECVFROM(oHandle, @cText, nFlag, @nFamily, @nPort, @cAddress)

function similar to W32RECV, to be used when W32BIND was not invoked. This function returns the family, the port and the address for the client; nFlag is the numeric OR of one or more of the following values (default = 0, see socket.prt):

• MSG_PEEK =  do not remove data read
• MSG_OOB = receive out-of-band data

This function returns -1 on error, the number of bytes received otherwise (stored in cText); cText must be long enough to store received data.

W32SELECT(vReadSockets, vWriteSockets, vExceptSockets, nSeconds, nMicroSeconds)

allows to determine if one or more sockets are readable, writable or in error condition, using a timeout; vReadSockets, vWriteSockets and vExceptSockets are arrays of socket handles to be verified; nSeconds is the timeout in seconds, nMicroSeconds the timeout in microseconds: the sum of these values is the total timeout; if both values are negative, there is not timeout.

The function returns a number, nResult, which can be:

• 0, if the timeout expired
• -1, on error
• a positive value, which is a bitmap handle returning the status of the sockets in the three arrays.

In the last case, the bitmap is set to 1 in the positions corresponding to the indexes in the arrays for the sockets in the requested status (readable, writable, in error). If the function returns a positive value, the bitmap must be freed after usage by calling BITMAPFREE(iResult).

To check for readable sockets, use BITMAPGET(nResult, n) where n goes from 1 to VECLEN(vReadSockets).
To check for writable sockets, use the same function but add W32SELECT_WRITE_OFFSET (see socket.prt) to the index in vWriteSockets.
To check for sockets in error, use the same function but add W32SELECT_EXCEPT_OFFSET (see socket.prt) to the index in vExceptSocket.

W32GETSOCKOPT(oHandle, nLevel, nOption, @value)

returns the value of a specified parameter for the socket oHandle; nLevel can be SOL_SOCKET or IPPROTO_TCP. The possible values for nOption depend on nLevel (see socket.prt):

nLevel = SOL_SOCKET

Value	Returned type	Description
SO_ACCEPTCONN	integer (0/1)	the socket is listening
SO_BROADCAST	integer (0/1)	the socket is configured for broadcast messages
SO_DEBUG	integer (0/1)	debugging is enabled
SO_DONTLINGER	integer (0/1)	if true, the option SO_LINGER is disabled
SO_DONTROUTE	integer (0/1)	don't use routing tables
SO_ERROR	integer	get error status and reset
SO_GROUP_ID	integer	ID for socket group (unsupported)
SO_GROUP_PRIORITY	integer	group priority
SO_KEEPALIVE	integer (0/1)	keep alive packets sent
SO_LINGER	struct LINGER	linger on closing if data is available
SO_MAX_MSG_SIZE	integer	maximum message size, for message-oriented sockets (e.g. SOCK_DGRAM); ignored for stream sockets.
SO_OOBINLINE	integer (0/1)	"Out-of-band" data received in data stream
SO_PROTOCOL_INFO	WSAPROTOCOL_INFO	protocol information for the socket
SO_RCVBUF	integer	receive buffer size
SO_REUSEADDR	integer (0/1)	the socket can reuse a local address
SO_SNDBUF	integer	transmission buffer size
SO_TYPE	integer	socket type (e.g. SOCK_STREAM).
PVD_CONFIG	binary	"Opaque" data structure for socket service
SO_RCVLOWAT	integer	minimum receive watermark
SO_RCVTIMEO	integer	receive time-out
SO_SNDLOWAT	integer	minimum transmission watermark
SO_SNDTIMEO	integer	transmission timeout

nLevel = IPPROTO_TCP

Value	Returned type	Description
TCP_NODELAY	integer (0/1)	disable Nagle algorithm for transmission
TCP_MAXSEG	integer	maximum TCP segment size

The requested option is returned into value (the type is specified above). This function returns -1 on error, 0 otherwise.

W32SETSOCKOPT(oHandle, nLevel, nOption, value)

sets the value of the specified parameter for the socket oHandle; nLevel can be SOL_SOCKET or IPPROTO_TCP. The possible values for nOption depend on nLevel (see socket.prt):

nLevel = SOL_SOCKET

Value	Type	Meaning
SO_BROADCAST	integer (0/1)	socket configured for transmitting broadcast messages
SO_DEBUG	integer (0/1)	debugging enabled.
SO_DONTLINGER	integer (0/1)	if true, the options SO_LINGER is disabled.
SO_DONTROUTE	integer (0/1)	don't use routing tables
SO_GROUP_PRIORITY	integer	group priority
SO_KEEPALIVE	integer (0/1)	keep alive packets sent
SO_LINGER	struct LINGER	current linger options
SO_OOBINLINE	integer (0/1)	"Out-of-band" data received in data stream
SO_RCVBUF	integer	receive buffer size
SO_REUSEADDR	integer (0/1)	the socket can reuse a local address
SO_SNDBUF	integer	transmission buffer size
PVD_CONFIG	binary	"Opaque" data structure for socket service
SO_RCVLOWAT	integer	minimum receive watermark
SO_RCVTIMEO	integer	receive time-out
SO_SNDLOWAT	integer	minimum transmission watermark
SO_SNDTIMEO	integer	transmission time-out

nLevel = IPPROTO_TCP

Value	Type	Meaning
TCP_NODELAY	integer (0/1)	disable Nagle algorithm for transmission
TCP_MAXSEG	integer	maximum TCP segment size

The requested option is set to value; this function returns -1 on error, 0 otherwise.

Other functions

W32GETSERVBYNAME(@cName, @cProtocol, @cAlias, @nPort)

returns in the variables passed by reference the name, protocol, alias and port corresponding to cName and cProtocol. This function updates cName, cProtocol, cAlias and nPort (re-converted from network byte order); cAlias can contain several strings, delimited by tabs (ASC 9). Use an empty string for cProtocol to obtain any protocol. This function returns -1 on error, 0 otherwise.

W32GETHOSTBYNAME(@cName, @cAlias, @nType, @cAddress)

returns in the variables passed by reference the name, alias, type and address of the host corresponding to cName. This function updates cName, cAlias, nType and cAddress; cAlias and cAddress can contain several strings, delimited by tabs (ASC 9). This function returns -1 on error, 0 otherwise.

W32HTONS(n)

returns n (short integer) expressed in network byte order.

W32NTOHS(n)

returns n (short integer) converted from network byte order.

W32HTONL(n)

returns n (long integer) expressed in network byte order.

W32NTOHL(n)

returns n (long integer) converted from network byte order.

W32GETPROCESSID()

returns the current process ID.

W32GETTICKCOUNT()

returns the number of milliseconds elapsed from system start.

W32SENDKEYS(cKeys[, nfSeconds])

stuffs cKeys in the keyboard buffer, as if it was typed by the user. The string should be formatted according to the following rules. The parameter nfSeconds (if specified) is the inter-character delay; e.g. W32SENDKEYS("ABC", 0.1) stuffs the characters A, B and C into the keyboard buffer, waiting 0.1 seconds between them.

Every key is represented by one or more characters; to specify a single character on the keyboard, use its symbol: e.g. for the letter A, use "A" in cKeys. To enter several keys, put them one after the other, in sequence: e.g. to stuff A, B and C in the keyboard buffer, use "ABC" for cKeys.

The following symbols: +, ^, %, ~ and the (parenthesis) have special meanings for W32SENDKEYS. To specify one of these characters, enclose the symbol between braces: e.g. for "+" use "{+}". Square brackets ([ ]) do not have a special meaning for W32SENDKEYS, neverthless must be enclosed between braces. To stuff a brace in the keyboard buffer, use {{} and {}}.

There are special characters which are not printable (like Enter and Tab) and keys that represent actions instead of text; to specify these characters, use the codes from the following table:

Key	Code
BACKSPACE	{BACKSPACE}, {BS}, or {BKSP}
BREAK	{BREAK}
CAPS LOCK	{CAPSLOCK}
DEL	{DELETE} or {DEL}
ARROW DOWN	{DOWN}
END	{END}
ENTER	{ENTER}or ~
ESC	{ESC}
HELP	{HELP}
HOME	{HOME}
INS	{INSERT} or {INS}
LEFT ARROW	{LEFT}
NUM LOCK	{NUMLOCK}
PAG DOWN	{PGDN}
PAG UP	{PGUP}
PRINT SCREEN	{PRTSC}
RIGHT ARROW	{RIGHT}
SCROLL LOCK	{SCROLLLOCK}
TAB	{TAB}
LINE FEED	{LF}
ARROW UP	{UP}
F1	{F1}
F2	{F2}
F3	{F3}
F4	{F4}
F5	{F5}
F6	{F6}
F7	{F7}
F8	{F8}
F9	{F9}
F10	{F10}
F11	{F11}
F12	{F12}
F13	{F13}
F14	{F14}
F15	{F15}
F16	{F16}
CLEAR	{CLEAR}
APPLICATIONS	{APPS}
NUMPAD +	{NUMPAD+}
NUMPAD -	{NUMPAD-}
NUMPAD *	{NUMPAD*}
NUMPAD /	{NUMPAD/}
NUMPAD ENTER	{NUMPADENTER}
NUMPAD 0..9	{NUMPAD0} .. {NUMPAD9}
NUMPAD LEFT	{NUMPADLEFT}
NUMPAD RIGHT	{NUMPADRIGHT}
NUMPAD UP	{NUMPADUP}
NUMPAD DOWN	{NUMPADDOWN}
NUMPAD HOME	{NUMPADHOME}
NUMPAD PGUP	{NUMPADPGUP}
NUMPAD PGDN	{NUMPADPGDN}
NUMPAD END	{NUMPADEND}
NUMPAD INS	{NUMPADINS}
NUMPAD DEL	{NUMPADDEL}
LEFT CTRL	{LCONTROL}
RIGHT CTRL	{RCONTROL}
LEFT MENU	{LMENU}
RIGHT MENU	{RMENU}
LEFT SHIFT	{LSHIFT}
RIGHT SHIFT	{RSHIFT}
LEFT WINDOWS	{LWIN}
RIGHT WINDOWS	{RWIN}

To specify a key combo (SHIFT, CTRL and ALT pressed together with another key), use the following prefixes:

Key	Code
SHIFT	+
CTRL	^
ALT	%

If SHIFT, CTRL and ALT must be kept pressed while the other keys are typed, enclose these keys between parenthesis; e.g. if you want SHIFT to be kept pressed while entering E and C, use "+(EC)". If SHIFT must be released after typing E, use "+EC".

W32SHELL(cCommand)

runs cCommand and returns 0 (process correctly started) or -1 (unable to start the process). The function does not wait for the process to end before returning control to the program; see also SYSTEM, CAPTURE and EXEC.

W32PROTLICENSE()

returns the licence number embedded in the hardware protection key; only for the registered version of Proteus (the demo version always returns the string "20000000000"). This information can be used to protect your programs.