# Function Reference

# TCPListen

Creates a socket listening for an incoming connection.

TCPListen ( IPAddr, port [, MaxPendingConnection] )

## Parameters

IPAddr | Internet Protocol dotted address(IpV4) as "192.162.1.1".
port | port on which the created socket will be connected.
MaxPendingConnection | [optional] Maximum length of the queue of pending connections. By default the maximum reasonable value will be set.

## Return Value

Success: | the main socket identifier.
Failure: | -1 or 0 and sets the @error flag to non-zero.
@error: | 1 IPAddr is incorrect. 2 port is incorrect. Windows API WSAGetLastError return value (see MSDN).

## Related

TCPAccept, TCPCloseSocket, TCPConnect, TCPSend, TCPShutdown, TCPStartup, TCPTimeout (Option)

## Example

    #include <MsgBoxConstants.au3>
    #include <WinAPIError.au3>

    Example()

    Func Example()
        Local $sMsgBoxTitle = "AutoItVersion = " & @AutoItVersion

        TCPStartup() ; Start the TCP service.

        ; Register OnAutoItExit to be called when the script is closed.
        OnAutoItExitRegister("OnAutoItExit")

        ; Assign Local variables the loopback IP Address and the Port.
        Local $sIPAddress = "127.0.0.1" ; This IP Address only works for testing on your own computer.
        Local $iPort = 65432 ; Port used for the connection.

        ; Assign a Local variable the Listening socket and bind to the IP Address and Port specified with a maximum of 100 pending connections.
        Local $iListenSocket = TCPListen($sIPAddress, $iPort, 100)

        ; Notes: You can only listen on private IPs, such as the one used here;
        ; or on the range of 192 to 223 (generally 192.168.X.X, use @IPAddress1 to test on your local IP [you will need another computer]).
        ; The Listen socket identifier is only used for the TCP Accept function.

        ; If an error occurred display the error code and return False.
        If @error Then
            ; Someone is probably already listenings on this IP Address and Port (script already running?).
            MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), $sMsgBoxTitle, "Could not listen, Error code: " & @error & @CRLF & @CRLF & _WinAPI_GetErrorMessage(@error))
            Return False
        Else
            MsgBox($MB_SYSTEMMODAL, $sMsgBoxTitle, "Listen successful.", 3)
        EndIf

        ; Close the Listening socket to allow afterward binds.
        ; While not closed, any other program can NOT bind to the same IP Address and Port.
        TCPCloseSocket($iListenSocket)
    EndFunc   ;==>Example

    Func OnAutoItExit()
        TCPShutdown() ; Close the TCP service.
    EndFunc   ;==>OnAutoItExit