<HTML><HEAD>
<!-- This document was created with h2.pl -->
<TITLE>Tcp4u - Telnet related functions</TITLE></HEAD>
<BODY BACKGROUND="" BGCOLOR="#FFFFC0" TEXT="#000000">
<H1>
Tcp4u - Telnet related functions</H1>
<UL>
<LI><A HREF="#Mention1">TnGetAnswerCode</A>
<LI><A HREF="#Mention2">TnProtoExchange</A>
<LI><A HREF="#Mention3">TnReadLine</A>
<LI><A HREF="#Mention4">TnReadMultiLine</A>
<LI><A HREF="#Mention5">TnSend</A>
<LI><A HREF="#Mention6">TnSendMultiLine</A>
</UL>
<hr size=4>
<h1>
<A NAME="Mention1">TnGetAnswerCode</A></h1>
<p><br>
This function reads a full answer via TnReadMultiLine, then translate the 3 digits at the beginning of the string.<br>
The function returns either a telnet code (the 3 digits at the beginning of the string) or an error code.</p>
<pre>
Syntax: TnGetAnswerCode (SOCKET skt, LPSTR szBuf, UINT uBufSize,
UINT uTimeOut, HFILE hf);
</pre>
<pre>
</pre>
<p>Arguments:<br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">skt <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szBuf <BR></TD>
<TD colspan=1 align="left">The user's buffer into which the string will be copied <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uBufSize <BR></TD>
<TD colspan=1 align="left">Its size <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uTimeOut <BR></TD>
<TD colspan=1 align="left">The timeout <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hf <BR></TD>
<TD colspan=1 align="left">A file handler into which the data will be copied <BR></TD></TR></TABLE><p><br>
Returns:<br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error or a timeout has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">100< Rc < 999 <BR></TD>
<TD colspan=1 align="left">Rc is a telnet answer code <BR></TD></TR></TABLE>
<pre>
</pre>
<HR><H1>
<A NAME="Mention2">TnProtoExchange</A></h1>
<p><br>
This function sends a command using TnSend(), waits for its reply using a application-specified function, then translates the reply using a application specified array.<br>
Notes:<br>
<UL><LI>Although it is fully documented, <b>this function is subject to change</b>. Thus its use should be reserved.<br>
<LI>If the callback function TnProtoRecv returns either 0 or a negative value, TnProtoExchange considers that the function failed and returns the same value to the caller.<br>
</UL> <pre>
Syntax: TnProtoExchange (SOCKET s,
LPCSTR szCommand,
LPSTR szResponse, UINT uBufSize,
int CALLBACK TnProtoRecv (SOCKET s,
LPSTR szResponse,
UINT uBufSize,
UINT uTimeOut,
HFILE hLogFile),
struct S_TnProto *tTranslation,
int nTabSize,
BOOL bCaseCmp,
UINT uTimeout,
HFILE hLogFile);
</pre>
<pre>
</pre>
<p>Arguments:<br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">s <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szCommand <BR></TD>
<TD colspan=1 align="left">The command to be sent. NULL if no command are to be sent. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szResponse <BR></TD>
<TD colspan=1 align="left">A buffer provided by the application. This buffer shall be large enough to contain the full answer returned by the server <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uBufSize <BR></TD>
<TD colspan=1 align="left">Its size <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TnProtoRecv <BR></TD>
<TD colspan=1 align="left">A callback function call with arguments provided by the application. This function waits for the server's response. On success, it should return a positive value. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">tTranslation <BR></TD>
<TD colspan=1 align="left">An array of S_TnProto structures. TnProtoExchange compare each string of this array with the beginning of the server's reply until the both strings match. On success, it returns the integer part of the structure. If a string is set to NULL, TnProtoExchange returns a TN_UNEXPECTED answer. <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">nTabSize <BR></TD>
<TD colspan=1 align="left">number of structures S_TnProto contained in the array tTranslation <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">bCaseCmp <BR></TD>
<TD colspan=1 align="left">True if the comparison between the char part of the structure S_TnProto and the received string should be case sensitive <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uTimeOut <BR></TD>
<TD colspan=1 align="left">The timeout in seconds <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hLogFile <BR></TD>
<TD colspan=1 align="left">A file handler into which the transmission will be copied for logging purpose <BR></TD></TR></TABLE><p><br>
Returns:<br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_OVERFLOW <BR></TD>
<TD colspan=1 align="left">uBufSize character have been transferred into the user's buffer, but the telnet termination mark has not been found <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_TIMEOUT <BR></TD>
<TD colspan=1 align="left">A timeout has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SOCKETCLOSED <BR></TD>
<TD colspan=1 align="left">Remote host has closed the connection <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_UNEXPECTED <BR></TD>
<TD colspan=1 align="left">The beginning of the string sent by the server does not match any strings from the tTranslation array <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">Other <BR></TD>
<TD colspan=1 align="left">The integer part of the matching S_TnProto element <BR></TD></TR><TR align="left">
<TD colspan=1 align="left"><BR></TD>
<TD colspan=1 align="left"><BR></TD></TR><TR align="left">
<TD colspan=1 align="left"><BR></TD>
<TD colspan=1 align="left"><BR></TD></TR></TABLE>
<pre>
</pre>
<HR><H1>
<A NAME="Mention3">TnReadLine</A></h1>
<p><br>
This function receives a string ended by an EOL character (ASCII 10).<br>
A NUL character is added to the returned string.</p>
<pre>
Syntax: TnReadLine (SOCKET skt, LPSTR szBuf, UINT uBufSize,
UINT uTimeOut, HFILE hf);
</pre>
<pre>
</pre>
<p><tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">skt <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szBuf <BR></TD>
<TD colspan=1 align="left">The user's buffer into which the string will be copied <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uBufSize <BR></TD>
<TD colspan=1 align="left">Its size <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uTimeOut <BR></TD>
<TD colspan=1 align="left">The timeout <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hf <BR></TD>
<TD colspan=1 align="left">A file handler into which the data will be copied <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_BUFFERFREED <BR></TD>
<TD colspan=1 align="left">szBuf is not a writeable buffer <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_OVERFLOW <BR></TD>
<TD colspan=1 align="left">uBufSize character have been transferred into the user's buffer, but the EOL character has not been found <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_TIMEOUT <BR></TD>
<TD colspan=1 align="left">A timeout has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SOCKETCLOSED <BR></TD>
<TD colspan=1 align="left">Remote host has closed the connection <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SUCCESS <BR></TD>
<TD colspan=1 align="left">The string is available into szBuf <BR></TD></TR></TABLE>
<pre>
</pre>
<HR><H1>
<A NAME="Mention4">TnReadMultiLine</A></h1>
<p><br>
This function receives one or more strings ended by an EOL character (ASCII 10).<br>
A NUL character is added to the returned string.<br>
TnReadMultiLine returns when the last string received begins with a digit character ('0', ..., '9') and if its 4<sup>th</sup> character is not an hyphen character ('-'). </p>
<pre>
220 Hello
or
220-
220- Welcome to our FTP server
123 digits padded with blanks
220 end of string
</pre>
<p><br>
Note: TnReadLine should be enough for numerous protocols, however some more sophisticated protocols like FTP are more verbose and require to send multi-line requests or response. TnReadMultiLine reads the full request or response.</p>
<pre>
Syntax: TnReadMultiLine (SOCKET skt, LPSTR szBuf, UINT uBufSize,
UINT uTimeOut, HFILE hf);
</pre>
<pre>
</pre>
<p><tt>Arguments:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">skt <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szBuf <BR></TD>
<TD colspan=1 align="left">The user's buffer into which the string will be copied <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uBufSize <BR></TD>
<TD colspan=1 align="left">Its size <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">uTimeOut <BR></TD>
<TD colspan=1 align="left">The timeout <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hf <BR></TD>
<TD colspan=1 align="left">A file handler into which the data will be copied <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_BUFFERFREED <BR></TD>
<TD colspan=1 align="left">szBuf is not a writeable buffer <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_OVERFLOW <BR></TD>
<TD colspan=1 align="left">uBufSize character have been transferred into the user's buffer, but the EOL character has not been found <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_TIMEOUT <BR></TD>
<TD colspan=1 align="left">A timeout has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SOCKETCLOSED <BR></TD>
<TD colspan=1 align="left">Remote host has closed the connection <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SUCCESS <BR></TD>
<TD colspan=1 align="left">The string is available into szBuf <BR></TD></TR></TABLE>
<HR><H1>
<A NAME="Mention5">TnSend</A></h1>
<p><br>
This function sends a 0-terminated string, then sends the telnet termination string (<CR><LF>).<br>
Note :<br>
If an end of line character (<LF>) is found in the string, no conversion is done.</p>
<pre>
Syntax: TnSend (SOCKET skt, LPCSTR szString, BOOL bHighPriority, HFILE hf);
</pre>
<p><tt>Arguments: </tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">skt <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szString <BR></TD>
<TD colspan=1 align="left">The string to be sent <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">bHighPriority <BR></TD>
<TD colspan=1 align="left">TRUE if the string must be sent in Out Of Band mode <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hf <BR></TD>
<TD colspan=1 align="left">A file handler into which the data will be written <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SUCCESS <BR></TD>
<TD colspan=1 align="left">The string has been successfully sent <BR></TD></TR></TABLE>
<pre>
</pre>
<HR><H1>
<A NAME="Mention6">TnSendMultiLine</A></h1>
<p><br>
This function sends a 0-terminated string, then sends the telnet termination string (<CR><LF>). <br>
The end of line characters <LF> are expanded into the telnet format <CR><LF>. Of course the sequence <CR><LF> is send as is.</p>
<pre>
Syntax: TnSendMultiLine (SOCKET skt, LPCSTR szString, HFILE hf);
</pre>
<p><tt>Arguments: </tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">skt <BR></TD>
<TD colspan=1 align="left">The descriptor of the connection returned by TcpConnect or TcpAccept <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">szString <BR></TD>
<TD colspan=1 align="left">The string to be sent <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">hf <BR></TD>
<TD colspan=1 align="left">A file handler into which the data will be written <BR></TD></TR></TABLE><p><br>
<tt>Returns:</tt><br>
</p>
<TABLE><TR align="left">
<TD colspan=1 align="left">TN_ERROR <BR></TD>
<TD colspan=1 align="left">An error has occurred <BR></TD></TR><TR align="left">
<TD colspan=1 align="left">TN_SUCCESS <BR></TD>
<TD colspan=1 align="left">The string has been successfully sent <BR></TD></TR></TABLE>
<pre>
</pre>
</body></html>
<hr size=4>
<table border=1 CELLPADDING=7 align=center><tr>
<td><A HREF="tcp4u.htm">Overview</A></td>
<td><A HREF="tcp4u_p1.htm">Multi purpose func.</A></td>
<td><A HREF="tcp4u_p2.htm">TCP functions</A></td>
<td><A HREF="tcp4u_p3.htm">Telnet related func</A></td>
<td><A HREF="tcp4u_p4.htm">HTTP functions</A></td>
<td><A HREF="tcp4u_p5.htm">UDP functions</A></td>
<td><A HREF="tcp4u_p6.htm">SMTP functions</A></td>
</tr></table>
<font italic size=2>
<table border=0><tr>
<td align=left>Tcp4u version 3.31 by Ph. Jounin and Laurent Le Bras</td>
<td align=right>Last updated: 10th march 1998</td>
<tr>
</table>
</font>
syntax highlighted by Code2HTML, v. 0.9.1