4D Doc Center : Low Level Routines, Overview

4D v13.2

Low Level Routines, Overview

TCP/IP or Transmission Control Protocol/Internet Protocol, is the primary protocol used for sending data over the internet. The TCP commands included with 4D Internet Commands allow developers to establish TCP session and send and receive TCP packets via these sessions.

There are two ways to establish a TCP connection. The first way is to execute the TCP_Open command. This will open a connection with the domain specified on the specified port. TCP_Open allows the use of SSL (Secured Socket Layer) protocol which permits a secured connection. The other way to open a connection is to execute the TCP_Listen command. This command will open a connection with the specified domain on the specified port, and will listen for an incoming connection. The best way to determine if a connection has been established is to check the state of the session with the command TCP_State upon completion of the TCP_Listen command. A status code will be returned which will correspond to the current state of the session. From here you can send and/or receive TCP packets as you could with a connection established with TCP_Open.

In any case, any TCP connection opened must be closed subsequently using the TCP_Close command.

The low-level TCP/IP commands require advanced knowledge about the protocols of communication. Developers using these routines should have a complete understanding of any protocol they attempt to implement. Information about the various TCP/IP assigned port numbers, communication protocols, addressing requirements, etc. can be found in the RFCs.

Connection references in TCP commands

4D Internet commands allow the passing of POP3, IMAP or FTP connection references directly to low-level TCP commands and vice versa.
In fact, on the one hand, protocols are constantly evolving which leads to the creation of new commands; on the other, some software packages make their own interpretation of RFCs — rendering standardized implementations unusable. Using low-level TCP commands, developers can create the high-level functions they need themselves (instead of using existing functions or to fill in for a function that does not exist).
This significantly increases compatibility and development possibilities since developers can create their own high-level commands without having to rewrite all the commands needed for using a protocol.

In this example, the IMAP_Capability command is replaced by an equivalent function developed using TCP_IP commands.

Here is the initial method using the IMAP_Capability command:

 $ErrorNum:=IMAP_Login(vHost;vUserName;vUserPassword;vImap_ID)

 If($ErrorNum=0)

    C_TEXT(vCapability)

    $ErrorNum:=IMAP_Capability(vImap_ID;vCapability)

    ... ` IMAP command using the vImap_ID parameter

 End if

 $ErrorNum:=IMAP_Logout(vImap_ID)

This method can be replaced by:

 $ErrorNum:=IMAP_Login(vHost;vUserName;vUserPassword;vImap_ID)

 If($ErrorNum =0)

    C_TEXT(vCapability)

  ` TCP method using the value of the vImap_ID parameter:

    $ErrorNum:=My_IMAP_Capability(vImap_ID)

    ... ` IMAP commands using the vImap_ID parameter

 End if

 $ErrorNum:=IMAP_Logout(vImap_ID)

Here is the code of the My_IMAP_Capability function:

 C_LONGINT($1;$vErrorNum;$0)

 C_TEXT($vSentText;$vReceivedText;vCapability)

 C_TEXT($2)

 

 $vImap_Id:=$1

 $vCmd_Id:="A001" ` This command ID must be unique (cf. RFC 2060)

 $MyvtRequestCmd:="CAPABILITY"

 $vSentText;:=$vCmd_Id+""+$MyvtRequestCmd+Character(13)+Character(10)

 $vReceivedText:=""

 $vErrorNum:=TCP_Send($vImap_Id;$vSentText)

 If($vErrorNum=0)

    $vErrorNum:=TCP_Receive($vImap_Id;$vReceivedText)

    Case of

       :($vErrorNum#0) `Reception error

          vCapability:=""

       :(Position($vCmd_Id+" OK ";$vReceivedText)#0)

  ` Command execution successful

          vCapability:=$vReceivedText

  ` In this example, we do not process the string received

       :(Position($vCmd_Id+" BAD ";$vReceivedText)#0)

  ` Failure of command execution (syntax error

  ` or unknown command)

          vCapability:=""

          $vErrorNum:=10096

    End case

 End if

 $0:=$vErrorNum