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.