|
|||||
|
||||||
Related Topics | Other Library Functions |
function |
TCPConnectionGetCharacters |
Library: TCP/IP client and server support (OMTCP legacy, OmniMark versions 4 - 6.0.1)
Include: omtcp.xin |
Return type: String Returns: Characters read from the TCP connection. |
define external stream function TCPConnectionGetCharacters value TCPConnection this-TCPConnection size value integer minimum-read-length optional variable-to value integer maximum-read-length optional timeout value integer timeout-in-milliseconds optional as TCPConnectionGetCharacters
This function reads characters received from a source on the TCP connection object.
There are four combinations for specifying the size and variable-to values, as follows:
TCPConnectionGetCharacters
returns as many characters as it has available, as long as it has at least one character. It will wait (only for as long as the timeout value if one is specified) for at least one character, only if it has no characters to return.
TCPConnectionGetCharacters
reads and returns exactly minimum-read-length characters. If a timeout value is specified and is exceeded, it will return immediately with the (zero or more) characters it has available. It will also set the TCP connection to be in error.
TCPConnectionGetCharacters
reads as many characters as it has available, as if neither size nor variable-to were specified, except that if it has more than maximum-read-length available, it will only return maximum-read-length and will save any remaining characters for a subsequent read.
TCPConnectionGetCharacters
reads at least minimum-read-length characters, but will return up to maximum-read-length characters, if it has them available. Like the size value only case, it can timeout in reading the first minimum-read-length characters, but will not do so once that many have been read. It is an error for the size value to be greater than the variable-to value.
If the passed TCP connection object is closed or was never connected, then this function returns zero characters. At the same time, it sets the TCP connection to be in error. If an error is encountered during reading, either zero characters or those already read (if any) are returned, as seems appropriate, and the TCP connection object is set to be in error.
Note that difficulties inherent in deriving multiple sources from a connection apply equally to using TCPConnectionGetCharacters
when a TCPConnectionGetSource
derived source is also active. Note, however, that sequential uses of TCPConnectionGetCharacters
are allowed. It is also guaranteed that a TCPConnectionGetCharacters
will only ever read the characters it returns from a source. Any following characters are available to the next TCPConnectionGetSource
, TCPConnectionGetCharacters
, or TCPConnectionGetLine
.
Any attempt to do a TCPConnectionGetCharacters
when the associated TCP connection has been closed using TCPConnectionClose
is in error, and will set the TCP connection to be in error.
Any attempt to do a TCPConnectionGetCharacters
when there is already an active source derived from TCPConnectionGetSource
is not allowed and will result in an OmniMark external function exception.
Arguments:
TCPConnectionGetCharacters
will read.
TCPConnectionGetCharacters
will read.
Example
local TCPConnection TCP-Conn set TCP-Conn to TCPConnectionOpen on "localhost" at 5300 repeat exit unless TCPConnectionIsConnected TCP-Conn output TCPConnectionGetCharacters TCP-Conn again
Copyright © Stilo International plc, 1988-2010.