TcpOpen and TcpWaitOpen

The examples in this material illustrate TcpOpen and TcpWaitOpen.

Use TcpOpen or TcpWaitOpen to initiate a TCP connection. TcpOpen returns immediately, and connection establishment proceeds asynchronously with your program’s other operations. The connection is fully established when your program receives a CONNECTIONstateCHANGED notification with NewState set to OPEN. TcpWaitOpen does not return until the connection is established, or until an error occurs.

There are two types of TcpOpen calls: passive open and active open. A passive open call sets the connection state to LISTENING. An active open call sets the connection state to TRYINGtoOPEN.

Figure 1. TcpOpen example

   procedure TcpOpen
            (
        var    ConnectionInfo: StatusInfoType;
        var    ReturnCode: integer
            );
            external;

Figure 2. TcpWaitOpen example

   procedure TcpWaitOpen
            (
        var    ConnectionInfo: StatusInfoType;
        var    ReturnCode: integer
            );
            external;

Parameter

Description

ConnectionInfo

A connection information record.

Connection: Set this field to UNSPECIFIEDconnection. When the call returns, the field contains the number of the new connection if ReturnCode is OK.
ConnectionState: For active open, set this field to TRYINGtoOPEN. For passive open, set this field to LISTENING.
OpenAttemptTimeout: Set this field to specify how long, in seconds, TCP is to continue attempting to open the connection. If the connection is not fully established during that time, TCP reports the error to you. If you used TcpOpen, you receive a notification. The type of notification that you receive is CONNECTIONstateCHANGED. It has a new state of NONEXISTENT and a reason of TIMEOUTopen. If you used TcpWaitOpen, it returns with ReturnCode set to TIMEOUTopen.
Security: This field is reserved. Set it to DEFAULTsecurity.
Compartment: This field is reserved. Set it to DEFAULTcompartment.
Precedence: This field is reserved. Set it to DEFAULTprecedence.
LocalSocket: Active Open: You can use an address of UNSPECIFIEDaddress (TCP/IP uses the home address corresponding to the network interface used to route to the foreign address) and a port of UNSPECIFIEDport (TCP/IP assigns a port number, in the range of 1000 - 65535). You can specify the address, the port, or both if particular values are required by your application. The address must be a valid home address for your node, and the port must be available (not reserved, and not in use by another application).
Passive Open: You usually specify a predetermined port number, known by another program, which can do an active open to connect to your program. Alternatively, you can use UNSPECIFIEDport to let TCP/IP assign a port number, obtain the port number through TcpStatus, and transmit it to the other program through an existing TCP connection or manually. You generally specify an address of UNSPECIFIEDaddress, so that the active open to your port succeeds, regardless of the home address to which it was sent.
ForeignSocket: Active Open: The address and port must both be specified, because TCP/IP cannot actively initiate a connection without knowing the destination address and port.
Passive Open: If your program is offering a service to anyone who wants it, specify an address of UNSPECIFIEDaddress and a port of UNSPECIFIEDport. You can specify a particular address and port if you want to accept an active open only from a certain foreign application.

ReturnCode

Indicates success or failure of call. Possible return values are:

OK
ABNORMALcondition
FATALerror
LOCALportNOTavailable
NObufferSPACE
NOsuchCONNECTION
NOTyetBEGUN
OPENrejected (TcpWaitOpen Only)
PARAMlocalADDRESS
PARAMstate
PARAMtimeout
PARAMunspecADDRESS
PARAMunspecPORT
REMOTEreset (TcpWaitOpen Only)
SOFTWAREerror
TCPipSHUTDOWN
TIMEOUTopen (TcpWaitOpen Only)
TOOmanyOPENS
UNAUTHORIZEDuser (TcpWaitOpen Only)
UNREACHABLEnetwork (TcpWaitOpen Only)
ZEROresources

For a description of Pascal return codes, see Table 1.